shopkeeper-agent：电商数仓智能问数 Agent，全栈 NL2SQL 实战项目

获取下载链全程约 1 分钟

打开微信，搜索「软件教程管家」关注，或长按下方二维码关注
回复关键词 shopkeeper-agent
公众号自动回复网盘链接，点击即可保存下载

shopkeeper-agent：电商数仓智能问数 Agent，全栈 NL2SQL 实战项目

打开微信扫一扫关注
或搜索【软件教程管家】

shopkeeper-agent 是一个面向电商数仓的智能问数全栈项目：把自然语言问题转成 SQL，在数仓里查出结果再流式展示出来。它覆盖了从元数据准备、混合检索、LangGraph 多阶段编排到 NL2SQL 校验执行和前端展示的完整链路，更像一份可以跟着学、跟着跑的 AI Agent 工程实战代码，而不是一个只能调接口的演示。仓库还配套在线教程和按章节演进的代码分支，适合想系统理解问数 Agent 是怎么搭起来的人。

项目	内容
项目名称	shopkeeper-agent
项目定位	电商数仓智能问数 Agent（全栈）
核心技术	LangGraph、FastAPI、Qdrant、Elasticsearch、MySQL、React
开发语言	Python（后端）+ React（前端）
部署方式	Docker，提供前后端完整代码
配套资料	在线讲义与章节演进分支

快速判断

如果目标是学习 LangGraph 及完整的问数 Agent 工程链路，可以选择该项目作为实践型代码库。它适合需要同时理解元数据建模、混合检索、NL2SQL、FastAPI 服务和 React 展示的开发者；如果目标是直接部署到非电商业务或生产数仓，应先评估数据模型适配、权限治理、SQL 审核和多组件运维成本。

技术定位与链路全景

这个项目的链路分四层：先把表、字段、指标和字段取值整理成元数据知识库；再用 Qdrant 做语义召回、Elasticsearch 做全文检索、MySQL 保存结构化元数据，三路协同把问题相关的字段、指标和取值找出来；接着由 LangGraph 编排检索、上下文整理、SQL 生成、校验、修正与执行的多阶段流程；最后后端通过 FastAPI 和 SSE 把问数过程和结果流式返回给 React 前端。字段、指标和字段取值三类信息的协同召回，是它比单一向量检索更贴近结构化数据分析场景的地方。

核心功能

三类元数据协同召回：字段、指标和字段取值一起参与检索，问数时能同时命中表结构、业务口径和具体取值。
混合检索：Qdrant 承担语义检索、Elasticsearch 承担全文检索、MySQL 承担结构化元数据存储，三者各司其职。
LangGraph 多阶段编排：从检索、上下文整理到 SQL 生成、校验、修正和执行，整个流程按阶段组织，中间结果可见、可干预。
流式问数体验：后端通过 FastAPI 提供服务，以 SSE 将问数过程和结果流式返回前端，查数过程不是等半天才一次性吐结果。
完整工程交付：仓库提供前后端代码、Docker 部署方式、配套教程和章节演进分支，可以按阶段对照着学。

架构与工作机制

系统先把表、字段、指标和字段取值整理为元数据知识库，再通过 Qdrant 进行语义召回、Elasticsearch 进行全文检索、MySQL 保存结构化元数据，并由 LangGraph 编排多阶段推理、SQL 生成、校验、修正与执行流程，后端通过 FastAPI 和 SSE 向 React 前端流式返回结果。项目还用到 Jieba 和 TEI 等组件，并通过 SSE 连接后端与前端；LangGraph、FastAPI、Repository 和 Client Manager 的组织方式，便于学习模块化工程结构。仓库关联 ai-agents-from-zero 教程体系，提供在线讲义和与章节对应的代码分支。

上手路径

项目提供前后端完整代码，并明确支持 Docker 环境一键部署。按仓库 README 的快速开始操作，大致是：拉取仓库代码，准备 MySQL、Qdrant、Elasticsearch、TEI 和大模型的相关配置，完成元数据初始化，再启动前后端服务。运行前需要准备好项目依赖的多个组件，具体环境变量、初始化步骤和兼容要求，应以 README 或源码中的快速开始说明为准，不要凭印象配。

适合人群与使用场景

适合希望系统学习 LangGraph、检索增强生成、NL2SQL、数据分析 Agent 和全栈 AI 工程开发的开发者，也适合作为理解 FastAPI、MySQL、Qdrant、Elasticsearch 与大模型协同工作的教学型代码库。可以用它来学习 LangGraph 多阶段工作流、构建电商数仓自然语言问数原型、研究混合检索与 NL2SQL 的协同方式，以及练习 FastAPI 后端、React 前端和 SSE 流式交付；也可以作为理解元数据知识库、数据分析 Agent 分层设计和大模型应用工程化流程的教学案例。

主要优势

覆盖从元数据准备、检索增强到 SQL 执行和前端展示的完整链路，学完能看到一整条线。
字段、指标和字段取值的协同检索更贴近结构化数据分析场景，比只做语义召回更实用。
LangGraph、FastAPI、Repository 和 Client Manager 的组织方式便于学习模块化工程结构。
配套在线教程和章节分支有助于按阶段理解系统演进过程。
项目同时提供前后端代码和 Docker 部署路径，便于本地复现和二次开发。

限制与注意点

聚焦电商数仓问数场景，迁移到其他业务域时需要重新准备元数据、指标口径和字段取值，不能直接照搬。
运行链路依赖 MySQL、Qdrant、Elasticsearch、TEI 及大模型等多个组件，部署和配置复杂度高于单体示例。
README 将权限控制、SQL 审核和结果可视化列为可继续扩展的能力，不能据此确认这些能力已经完整提供。
SQL 由模型生成并执行，实际使用仍需结合目标数据仓库做权限隔离、查询约束和结果校验，生产环境尤其不能裸跑。
公开信息有限，需查看 README 或源码确认具体模型配置、数据初始化方式和生产环境适配范围。

选型建议

当选型重点是学习多阶段 Agent 编排、混合检索和可运行的 NL2SQL 流程时，该项目匹配度较高；当需求是轻量级问答、单一向量库应用，或已经具备成熟权限与 SQL 治理平台时，应比较它的多服务依赖和业务改造成本。选择前应阅读 README 或源码，确认模型接入、数据初始化、配置项和部署脚本是否符合目标环境。建议先按 README 和配套教程完成依赖服务、元数据初始化及大模型配置，再逐步验证检索、SQL 生成和执行链路；长期维护时需要同步关注 LangGraph、检索组件、数据库连接配置和前后端接口变化，并为生成 SQL 设置独立权限、资源限制和审计机制。