didilili/shopkeeper-agent

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

解决的问题

本项目解决了业务数据分析中的常见挑战，即用户需要使用自然语言查询数据库但缺乏SQL专业知识。它通过实现结构化的多阶段推理管道，而不是依赖简单的直接LLM到SQL提示，解决了“幻觉”和错误数据检索（如选择错误的表或字段）的问题。

工作原理

该系统使用基于LangGraph构建的复杂代理工作流。它首先通过索引MySQL、Qdrant（用于语义向量搜索）和Elasticsearch（用于基于关键字的值搜索）中的表模式、指标和字段值来构建元数据知识库。当用户提问时，代理执行多路径检索以收集相关上下文，生成并验证SQL，执行查询，并将结果流式传输回React前端。

适用对象

它专为希望学习如何构建生产级AI代理的开发人员设计。对于那些希望掌握LangGraph、将多个数据存储（MySQL、Qdrant、Elasticsearch）集成到单个AI应用程序中，并理解从数据准备到前端交付的代理项目的完整生命周期的开发人员尤其有用。

亮点

多阶段推理： 超越简单的提示工程，使用LangGraph编排检索、SQL生成、验证和纠正。
混合检索： 结合语义搜索（Qdrant）和关键字搜索（Elasticsearch），确保自然语言到数据库模式和值的准确映射。
全栈实现： 包括完整的、可运行的代码库，包含FastAPI后端、React前端和基于Docker的基础设施。
教育重点： 附带全面的、逐章教程系列，直接映射到Git分支，便于动手学习。
工程最佳实践： 演示专业模式，如依赖注入、结构化配置和用于跟踪的请求ID日志记录。