shopkeeper-agent

📊 电商数仓智能问数 AI Agent，最适合用于系统学习 LangGraph 的实战项目：基于 LangGraph、FastAPI、Qdrant、Elasticsearch、MySQL 与 React，完整实现元数据知识库、混合检索、自然语言生成 NL2SQL 生成校验、SQL 执行与流式查询展示。前后端完整代码全栈可跑，Docker 环境一键部署，配套 ai-agents-from-zero 免费教程与章节代码分支。适合系统学习大模型应用、数据分析 Agent 和企业级 AI 工程落地。

语言Python
默认分支main
大小5.1 MB
更新3 天前
Issues1

在 GitHub 打开

didilili

技术解读

以下内容由 GitRead 中文社区编辑团队基于项目 README 与官方资料整理，结合中文开发者的常见使用场景补充技术选型建议。具体以项目官方文档为准。

didilili/shopkeeper-agent 深度技术分析

项目背景与痛点

电商数仓智能问数 AI Agent（简称 Shopkeeper Agent）是由 didilili 维护的一个开源项目，它提供了一种全新的智能问数方式，通过借助 LangGraph、自然语言处理（NLP）和数据库检索技术，简化了数据分析的流程。对于企业而言，数据仓库中积累的海量数据需要专业的 SQL 技术才能高效利用，但在日常业务场景中，大部分业务人员对 SQL 不熟甚至完全不懂。这直接阻碍了数据分析效率的提升。Shopkeeper Agent 则通过提供智能提问功能，使得业务人员可以像和同事对话一样轻松地获取所需的数据洞察。

核心技术揭秘

技术栈与架构

Shopkeeper Agent 采用了多项前沿技术，构建了一个混合检索与自然语言生成（NL2SQL）的系统。项目的技术栈包括：

LangGraph：用于构建知识图谱与NLP处理。
FastAPI：用于构建 Web 服务。
Qdrant：用于矢量相似度搜索。
Elasticsearch：用于全文搜索。
MySQL：用于存储结构化数据。
React：用于前端页面开发。这些技术的结合使得项目具备了强大的检索、生成与执行能力，能够处理海量数据仓库中的复杂查询和检索任务。

数据流分析

以下是一张详细的 Mermaid 数据流图，展示了系统的核心数据流动过程：

graph TD A[用户提问] --> B[LangGraph] B --> C[生成SQL] C --> D[Qdrant] C --> E{"执行SQL?"} E -->|"需要执行"| F[Elasticsearch] E -->|"不需要执行"| G[输出结果] F --> G G --> H[React]

在向 Shopkeeper-Agent 提交自然语言问题后，低级组件 LangGraph 进行复杂处理，生成相应的 SQL 语句。SQL 语句可能需要在 Qdrant 进行矢量相似度搜索或在 Elasticsearch 进行全文搜索。生成的 SQL 执行结果最终经由 React 显示给用户。

功能亮点与差异

Shopkeeper Agent 的优势主要体现在其混合检索机制以及 NL2SQL 的实现与校验上。混合检索不仅能够快速搜索到结果，还能结合知识图谱和自然语言处理技术通过语义相似度更精确地匹配数据。此外，项目配套的 ai-agents-from-zero 教程与具体的实践代码库分支，进一步降低了学习成本，提供了完整的开箱即用能力。

应用场景与落地建议

在生产环境中，Shopkeeper Agent 适用于电商、金融、制造等涉及大数据分析的行业。使用过程中，企业需要确保网络连接的稳定性和数据仓库的完整性。对于前端展示层，确保 React 组件的响应性和良好性能，可以让数据查询更具直观性。另外，为防止数据泄露，需要确保各技术栈的安全性，建议引入监控和日志系统，对异常行为进行预警。

综合评价

Shopkeeper Agent 项目的亮点在于其巧妙地将 NLP 及搜索技术与数据分析相结合，提供了一条从提问到结果的快速通道，极大地提高了数据分析的效率。但同时也需要注意系统运行时可能存在的延时和资源消耗，以及前端用户体验提升。总体来看，这是一款值得电商平台、数据分析人员和 AI 基础设施建设者深入学习与研究的综合性应用项目。

关于

agent-workflow ai-agent elasticsearch fastapi langchain langgraph llm nl2sql qdrant rag vector-database

MIT License
527 Stars
151 Forks
1 Watching

简要分析

热度分

830

价值分

361

活跃状态

活跃

GitHub

语言占比

CSS

Dockerfile

HTML

JavaScript

Python

TypeScript

贡献者

didilili

fc-dot

fuqingyingbai-netizen

「电商问数」智能数据分析 Agent

shopkeeper-agent

可能是全网最适合用于系统学习 LangGraph 的智能问数实战项目，配套系统性文字教程与对应章节分支，带你打通混合检索、多阶段推理、SQL 生成与执行全链路

Python LangGraph Stars

快速开始 • 项目亮点 • 系统架构 • 配套教程 • 面试题库 • 加入社群

📚 在线阅读

📢 说明：本套实战项目已更新完成，配套教程、章节分支和前后端代码均可对照学习。

如果你正在找一个适合学习 LangGraph、Qdrant、MySQL、FastAPI 和 AI Agent 工程开发的实战项目，「电商问数」很可能是最适合你的项目。

它不是只调用一次大模型接口，也不是写几个 Prompt 演示 SQL 生成结果。这个项目围绕电商数仓问数场景，先构建元数据知识库，再做字段、指标、字段取值的混合检索，随后用 LangGraph 编排多阶段问数流程，完成 SQL 生成、校验、修正、执行和前端流式展示。换句话说，你学到的不是某一个框架 API，而是一条 AI 应用从数据准备、检索增强、智能体编排、接口交付到前端联调的完整项目主线。

本套仓库是 ai-agents-from-zero 教程体系中的实战项目-电商问数配套源码仓库，除了可直接运行和二次开发的项目代码之外，也提供了与教程章节对应的 Git 分支演进过程，以及完整的在线图文讲义入口。如果你想系统学习「AI智能体大模型应用开发」，也可直接从系统教程 AI 智能体实战速成指南-大模型入门开始。

电商问数前端首页：样例问题、自然语言输入和智能数据分析 Agent 界面

🎯 面栈 MianStack｜程序员面试题库天花板

把「电商问数」写进简历，再把技术亮点讲清楚。打造全网最有价值的面试题库！

简历有示例：从项目描述、技术栈到主要工作，参考业务场景，提炼自己实际完成的技术亮点。
项目有拆解：对照架构、选型与源码，准备 NL2SQL、检索增强与 LangGraph 的项目追问。
备考有重点：真实面经关联高频题，结合原理、代码与图解，理清答题思路。

👉 在线刷题 · 电商问数：简历示例与面试题 · GitHub 开源仓库，欢迎 Star ⭐

📖 项目介绍

在真实问数场景里，业务同学通常不会写 SQL，数据分析同学也很难随时记住所有表结构、字段含义、指标口径和字段取值。单纯把自然语言问题直接交给大模型，很容易出现表选错、字段选错、指标理解错和 SQL 幻觉等问题。

电商问数 要解决的就是这个问题：

用户用自然语言提问
系统自动召回相关字段、指标和字段取值
大模型基于上下文进行分步推理
生成 SQL 并查询数据仓库
以流式方式返回分析结果

✨ 项目亮点

检索 + 推理 + 生成，而不是模型直出 SQL
- 先围绕问题召回相关字段、指标和值域，再组织上下文生成 SQL，整体链路更稳、更可控。
面向企业问数场景的混合检索
- Qdrant 负责字段和指标的语义召回。
- Elasticsearch 负责字段取值的全文检索。
- MySQL 负责保存完整、权威的结构化元数据。
支持字段、指标、取值三类信息协同召回
- 比单纯做表级或字段级检索更贴近真实企业分析流程。
从检索到执行的完整可运行链路
- 不停留在 Prompt 设计，而是会真实生成 SQL、执行查询，并以流式方式返回结果。
工程化后端结构清晰
- 基于 FastAPI + LangGraph + Repository + Client Manager 组织配置、客户端、仓储层、服务层与智能体流程，便于维护和扩展。
不仅有实战代码，还有完整配套教程文档
- 项目配有一套系统化、持续更新、完全免费的教程讲义，适合按章节从数仓基础、元数据知识库到问数智能体流程逐步学习。
兼顾学习价值与可扩展性
- 既可以按教程章节逐步理解，也可以在此基础上继续扩展权限控制、SQL 审核、结果可视化等能力。

这套课程十分适合这些场景：

想系统学习 LangGraph，但不想只停留在几个玩具节点。
想把 MySQL、Qdrant、Elasticsearch 和大模型放到同一个业务场景里理解。
想做一个比简单模型调用更接近实际开发的 AI Agent 项目。
想把项目写进简历，并且能说清楚数据层、检索层、智能体层、服务层和前端层分别做了什么。

🏗️ 系统架构

电商问数系统架构图：前端通过 FastAPI 和 SSE 连接后端，LangGraph 问数智能体基于 Jieba、MySQL、Qdrant、Elasticsearch 和 LLM 完成召回、SQL 生成校验执行与结果返回

项目围绕两条主线展开：

主线	做什么	涉及模块
元数据知识库构建	抽取教学数仓中的表、字段、指标和字段取值，写入结构化库、向量库和全文索引	`MySQL` / `Qdrant` / `Elasticsearch` / `TEI`
自然语言问数	基于用户问题完成召回、上下文整理、SQL 生成校验执行，并把过程流式返回前端	`LangGraph` / `FastAPI` / `SSE` / `React`

电商问数查询结果页：LangGraph 执行流程、SQL 校验执行和查询结果表格

🛠️ 项目技术栈

模块	技术	作用
教学数仓	`MySQL`	模拟事实表、维度表和分析型查询环境
元数据库	`MySQL` / `SQLAlchemy`	保存表、字段、指标、字段指标关系等结构化元数据
向量检索	`Qdrant`	保存字段和指标向量，支持语义召回
全文检索	`Elasticsearch`	保存字段真实取值，支持关键词和值域检索
Embedding	`TEI` / `BAAI/bge-large-zh-v1.5`	将字段、指标、问题等文本转成向量
智能体编排	`LangGraph`	组织多阶段问数工作流
模型接入	`LangChain`	封装 LLM 与 Embedding 调用
后端接口	`FastAPI`	提供问数 API、依赖注入和生命周期管理
流式协议	`SSE`	实时返回节点进度、查询结果和错误消息
前端	`React` / `Vite` / `Tailwind CSS`	提供聊天式问数界面和流程展示
日志追踪	`ContextVar` / `loguru`	为并发请求注入 request_id，便于排查链路
依赖管理	`uv` / `pnpm`	管理 Python 后端和前端依赖

📁 项目结构

shopkeeper-agent/
├── app/
│   ├── agent/            # LangGraph 图、状态、上下文和各类节点
│   ├── api/              # FastAPI 路由、依赖注入、生命周期和请求结构
│   ├── clients/          # MySQL、Qdrant、Elasticsearch、Embedding 客户端管理
│   ├── conf/             # 配置 dataclass 与配置加载工具
│   ├── core/             # 日志、request_id 上下文等通用能力
│   ├── entities/         # 更贴近业务语义的数据对象
│   ├── models/           # SQLAlchemy ORM 模型
│   ├── prompt/           # Prompt 加载工具
│   ├── repositories/     # MySQL、Qdrant、Elasticsearch 数据访问层
│   ├── scripts/          # 元数据知识库构建脚本
│   └── services/         # 元数据构建服务和问数查询服务
├── conf/                 # app_config.yaml、meta_config.yaml
├── docker/               # Docker Compose、MySQL 初始化 SQL、ES 插件、Embedding 挂载目录
├── frontend/             # React + Vite + Tailwind CSS 前端项目
├── prompts/              # SQL 生成、修正、过滤等 Prompt 模板
├── main.py               # FastAPI 应用入口
└── pyproject.toml        # Python 项目依赖与工具配置

🚀 快速开始

当前仓库已经包含一套可直接启动的本地开发环境，你可以按照以下顺序启动项目。

1. 准备环境

Python >= 3.14
uv
Docker 与 Docker Compose
Node.js 与 pnpm

2. 克隆项目

git clone https://github.com/didilili/shopkeeper-agent.git
cd shopkeeper-agent

3. 安装后端依赖

uv sync

4. 配置大模型 API Key

cp .env.example .env

把 .env 中的 LLM_API_KEY 替换成真实密钥：

LLM_API_KEY=your_real_api_key

默认配置使用兼容 OpenAI 接口的硅基流动服务：

llm:
    model_name: Pro/zai-org/GLM-5.1
    api_key: ${oc.env:LLM_API_KEY}
    base_url: https://api.siliconflow.cn/v1

如需使用其他兼容 OpenAI API 的模型平台，修改 conf/app_config.yaml 中的 model_name 和 base_url。

5. 准备 Embedding 模型

项目通过 TEI 加载 BAAI/bge-large-zh-v1.5。模型文件体积较大，无法再仓库中进行提交，需要先下载到 Docker 挂载目录：

uv run hf download BAAI/bge-large-zh-v1.5 --local-dir docker/embedding/bge-large-zh-v1.5

如果手动下载，请解压到：docker/embedding/bge-large-zh-v1.5路径下。

6. 启动 Docker 基础服务

docker compose -f docker/docker-compose.yaml up -d

默认端口：

服务	端口
MySQL	`3306`
Elasticsearch	`9200`
Kibana	`5601`
Qdrant	`6333`
Embedding	`8081`

docker/mysql/meta.sql 和 docker/mysql/dw.sql 会在 MySQL 容器首次启动时自动初始化元数据库和教学数仓。

7. 构建元数据知识库

uv run python -m app.scripts.build_meta_knowledge -c conf/meta_config.yaml

这一步会把表字段元数据写入 MySQL，把字段和指标向量写入 Qdrant，并把字段真实取值写入 Elasticsearch。

8. 启动后端

uv run fastapi dev main.py

后端接口：

POST http://127.0.0.1:8000/api/query

请求示例：

{
    "query": "统计华北地区的销售总额"
}

SSE 消息类型：

类型	含义
`progress`	节点执行进度
`result`	最终查询结果
`error`	全局异常消息

9. 启动前端

cd frontend
pnpm install
pnpm dev

前端默认通过 Vite 代理把 /api 转发到 http://127.0.0.1:8000。如需修改：

cd frontend
cp .env.example .env

VITE_DEV_PROXY_TARGET=http://127.0.0.1:8000

💬 加入社群

想和更多朋友聊聊 AI 编程、Vibe Coding、面试经验，顺便吹水唠嗑、吐槽老板？欢迎加入「全宇宙最有爱的 AI Agent 交流群 —— 胡思妙想研究所」！🎉

👉 猛击这里！申请入所：在申请帖留言，并按帖内说明添加微信。

愿我们在这里少一点焦虑，多一点灵感；少一点单打独斗，多一点一起胡思妙想～

📚 配套教程目录

教程总入口：电商问数完整教程

章节	标题	学习重点	对应分支
0	前言	项目定位、学习价值与能力边界	`-`
1	项目概述与数仓基础	业务库、数仓、事实表、维度表与教学数仓设计	`-`
2	项目整体架构与智能体流程	MySQL、Qdrant、Elasticsearch、LLM 与 Agent 工作流如何协作	`-`
3	开发环境与基础服务准备	uv、Docker Compose、MySQL、Qdrant、Elasticsearch、Kibana、Embedding 服务	`03-env-services`
4	项目结构与基础服务配置管理	工程结构、YAML 配置、OmegaConf 与 dataclass 配置加载	`04-structure-config`
5	Qdrant 与 ES 快速入门与接入	向量检索、全文检索与客户端管理	`05-qdrant-es`
6	MySQL、Embedding 接入与日志管理	异步 MySQL、TEI Embedding、loguru 日志	`06-mysql-embedding-log`
7	元数据知识库总览与构建入口	元数据知识库产物、存储分工和构建入口	`07-metadata-base-overview`
8	表与字段信息同步到元数据库	Service、Repository、Mapper、ORM 如何配合入库	`08-metadata-table-column-sync`
9	字段与指标检索能力构建	字段向量索引、字段值全文索引和指标向量索引	`09-metadata-retrieval-capability`
10	问数智能体总览与工作流骨架	LangGraph 工作流骨架与节点设计	`10-agent-workflow-skeleton`
11	关键词抽取与多路召回	关键词抽取，字段、指标和字段取值并行召回	`11-agent-keyword-multi-recall`
12	召回信息合并与上下文构建	召回结果合并、依赖字段补齐和值域上下文构建	`12-agent-merge-retrievals`
13	SQL 生成前的信息过滤与补全	候选表字段过滤、指标过滤、日期和数据库上下文补齐	`13-agent-filter-extra-context`
14	SQL 生成与执行闭环	SQL 生成、EXPLAIN 校验、错误修正和最终执行	`14-agent-sql-loop`
15	API 接口基础与 FastAPI 入门	`/api/query`、StreamingResponse 和 SSE 基础	`15-api-streaming-basics`
16	查询接口实现与依赖组装	QueryService、依赖注入和应用生命周期资源管理	`16-api-query-service`
17	前后端联调与日志追踪	SSE 消息协议、前端展示、异常兜底和 request_id 日志追踪	`17-api-integration-logging`

可以用分支切换对照每一阶段的代码演进：

git checkout 04-structure-config
git checkout main

main 分支保留当前完整闭环版本。

本项目基于尚硅谷「大模型智能体掌柜问数」项目，并在此基础上整理完善。

🚧 能力边界

这套项目主要关注智能问数的学习流程，不刻意覆盖生产治理能力，例如：

用户登录、角色权限和数据权限控制
多租户隔离
SQL 安全审计和执行白名单
查询缓存、限流和性能治理
系统化评测集与自动化回归评测
监控告警、链路追踪平台和灰度发布
更复杂的多轮问数记忆、追问改写和会话管理

这些能力适合在基础流程跑通之后继续扩展。shopkeeper-agent 更适合承担一个清晰角色：先把智能问数最关键、最必要、最值得学习的工程链路讲清楚、跑起来，并为后续扩展企业级能力打基础。

⭐ Star History

暂无评论

shopkeeper-agent

技术解读

didilili/shopkeeper-agent 深度技术分析

项目背景与痛点

核心技术揭秘

技术栈与架构

数据流分析

功能亮点与差异

应用场景与落地建议

综合评价

相关仓库

关于

简要分析

语言占比

贡献者

「电商问数」智能数据分析 Agent

shopkeeper-agent

🎯 面栈 MianStack｜程序员面试题库天花板

📖 项目介绍

✨ 项目亮点

🏗️ 系统架构

🛠️ 项目技术栈

📁 项目结构

🚀 快速开始

1. 准备环境

2. 克隆项目

3. 安装后端依赖

4. 配置大模型 API Key

5. 准备 Embedding 模型

6. 启动 Docker 基础服务

7. 构建元数据知识库

8. 启动后端

9. 启动前端

💬 加入社群

📚 配套教程目录

🚧 能力边界

⭐ Star History

评论