欢迎来到「电商问数」项目，正式开启「AI 智能体实战速成指南」的实战项目学习~~ ✨
如果你正在找一个真正适合入门进阶的 AI 项目，而不是只调用一次大模型接口、写几个 Prompt、演示一下 SQL 生成结果，那么这套「电商问数」教程非常适合你。
它把 MySQL、LangGraph、Qdrant、Elasticsearch、Embedding、FastAPI、SSE 和前端联调放进同一条业务链路里，用一个自然语言问数场景，把智能体项目开发中最关键的知识点串起来：
- 用
MySQL模拟教学数仓和元数据库 - 用
Qdrant做字段和指标的语义向量检索 - 用
Elasticsearch做字段真实取值的全文检索 - 用
LangGraph编排多阶段问数智能体工作流 - 用
FastAPI + SSE把后端能力交付给前端页面
一句话概括：「电商问数」不是一个只会让大模型裸写 SQL 的 Demo，而是一套围绕“先构建元数据知识库，再检索、推理、生成、校验和执行 SQL”展开的智能问数实战项目。
它可能不是一个完整的企业级生产系统，但非常适合作为入门到进阶阶段的项目实战课程。你可以在这里系统学习一套智能体应用从“数据准备”到“检索增强”，再到“工作流编排”和“接口交付”的完整主链路。
配套源码仓库地址：https://github.com/didilili/shopkeeper-agent
很多 AI 项目教程容易走向两个极端：
- 要么太轻，只演示一次模型调用，学完之后不知道怎么做真实项目
- 要么太重，一上来就塞进大量生产级能力，新手很容易迷失在工程复杂度里
「电商问数」选择的是中间更适合学习的一条路：保留真实问数系统最核心、最必要的工程链路，但不一开始追求大而全。
你会看到一个智能问数项目为什么不能只靠大模型直接生成 SQL，而要先解决下面这些问题：
- 面对多张事实表和维度表，系统怎么知道该查哪些表
- 用户说“华北”“黄金会员”“苹果品牌”时，系统怎么定位到真实字段和值
- 字段、指标、字段取值为什么要分开建索引
- 元数据库、向量索引、全文索引分别负责什么
- 召回出来的信息为什么不能直接丢给模型，还要合并、过滤和补全
- SQL 生成后为什么还要校验、纠错，再执行
- 后端接口为什么要用流式返回，让前端看到执行过程
这也是它非常适合学习 MySQL、LangGraph、Qdrant 等技术的原因：这些技术不是孤立出现的，而是都被放进了一个清楚的业务目标里。
你不是单独学一个数据库、一个向量库、一个框架 API，而是在学习它们如何配合完成一个真实的智能体应用。
这套实战项目不只是“最终代码 + 一篇说明文档”。它的每个关键章节，都配有对应的代码分支。
也就是说，你不用一上来面对完整项目的最终形态，而是可以按章节一步一步切换代码：
- 第 3 章先准备环境和基础服务
- 第 4 章理解项目结构和配置管理
- 第 5、6 章接入 Qdrant、Elasticsearch、MySQL、Embedding 和日志
- 第 7 到 9 章构建元数据知识库和检索能力
- 第 10 到 14 章逐步搭建 LangGraph 问数智能体
- 第 15 到 17 章把能力通过 FastAPI、SSE 和前端页面交付出去
每个阶段都有明确的学习目标、代码实现和知识讲解。你可以先看章节理解设计，再切换到对应分支对照代码，也可以先跑代码，再回到文档理解为什么这么写。
这对入门进阶非常友好。因为真正难的不是“看懂最终项目里有哪些文件”，而是知道这些文件是怎么一步步长出来的，为什么要这样拆层，为什么这一章只做这一部分，下一章又在前一章基础上补了什么能力。
如果你想做一个后续能写进简历、面试里也聊得起来的 AI 项目，「电商问数」会比单纯的模型调用 Demo 更有代表性。它不只是展示效果，而是能让你讲清楚：数据层、检索层、智能体层、服务层和前端交付层分别做了什么。
在真实企业里，业务同学通常不会写 SQL，数据分析同学也不可能随时记住所有表结构、字段含义和指标口径。于是就会出现一个非常典型的需求：
- 能不能直接用自然语言提问？
- 系统能不能自动找到相关表、字段和指标？
- 能不能自动生成 SQL，并返回可以真正拿来分析的结果？
「电商问数」要解决的，就是这个问题。
下面这张图可以先帮助你建立整体印象：用户提出自然语言问题后，系统会经过后端调度、字段和表结构召回、自然语言转 SQL、数据库查询、SSE 流式推送，最后把结果展示给用户。
从使用者视角看，它就是一个“会查数的智能数据分析助手”：
- 用户先用自然语言提问
- 系统理解问题，并抽取适合检索的关键信息
- 再到元数据知识库中召回相关表、字段、指标和字段取值
- 把这些信息整理成更适合大模型理解的上下文
- 再由大模型生成 SQL，并做必要的校验和纠错
- 最后到数据仓库执行 SQL，并把过程和结果返回给前端
当一次查询真正跑起来时，前端不只是等待最后结果，而是可以看到 LangGraph 工作流的执行过程：抽取关键词、召回字段信息、召回指标信息、召回字段取值、合并召回信息、过滤上下文、生成 SQL、校验 SQL、执行 SQL，最后展示查询结果。
所以，这个项目的重点从来不只是“大模型”，而是下面这整条链路：
- 数据仓库怎么设计和模拟
- 元数据知识库怎么构建
- 字段、指标、字段取值怎么做混合检索
- 智能体怎么基于上下文生成更可靠的 SQL
- 后端服务怎么把智能体能力交付给前端
- 日志和异常怎么帮助排查一条完整请求链路
后面的章节都会围绕这条主线展开：先把数仓里的表、字段、指标和字段取值整理成元数据知识库，再让问数智能体基于这套知识库完成检索、推理、SQL 生成、校验、执行和结果返回。
这套项目非常适合学习下面这些内容：
| 学习方向 | 在项目里的体现 |
|---|---|
MySQL |
模拟教学数仓、保存元数据库、执行最终 SQL 查询 |
| 数仓基础 | 理解事实表、维度表、指标、字段角色和分析型查询 |
| 元数据建模 | 构建 table_info、column_info、metric_info、column_metric 等结构化元数据 |
Qdrant |
保存字段和指标向量，用于语义召回 |
Elasticsearch |
保存字段真实取值，用于关键词和值域检索 |
Embedding |
将字段、指标、问题等文本转成向量 |
LangGraph |
编排关键词抽取、并行召回、上下文合并、SQL 生成、校验和执行 |
FastAPI |
提供查询接口，组织依赖注入和生命周期管理 |
SSE |
将问数过程、执行结果和异常信息实时返回前端 |
| 工程分层 | 学习配置、客户端、仓储层、服务层、智能体节点和接口层如何协作 |
同时也要把边界说清楚：
「电商问数」适合入门到进阶阶段学习，不是完整企业级生产系统。
它重点覆盖问数系统最核心的主链路：教学数仓、元数据知识库、混合检索、LangGraph 工作流、SQL 生成校验执行、FastAPI 接口、SSE 返回、前后端联调和日志追踪。
但它不会在第一个项目里展开所有生产级能力，比如：
- 用户权限和数据权限控制
- 多租户隔离
- 复杂 SQL 安全审计
- 查询缓存和性能治理
- 完整评测体系
- 监控告警和链路追踪平台
- 灰度发布和生产部署治理
- 更复杂的多轮问数记忆系统
这些能力当然重要，但如果全部放进第一个实战项目里，学习成本会非常高，主线反而容易被淹没。
所以这套项目更适合承担一个清晰角色：先帮你把智能问数项目最关键、最必要、最值得学习的主链路跑通，并且讲透。
为了把这条链路真正落成一个可运行的项目，当前这套实战项目主要使用了下面这些技术：
| 模块 | 技术栈 | 作用说明 |
|---|---|---|
| 教学数仓 | MySQL |
在教学环境中模拟数据仓库，保存事实表和维度表 |
| 元数据库 | MySQL |
保存结构化元数据，如 table_info、column_info、metric_info、column_metric |
| 向量数据库 | Qdrant |
保存字段和指标的语义向量索引 |
| 全文检索 | Elasticsearch |
保存部分字段真实取值，支持关键词和值域检索 |
| 向量化服务 | TEI + BAAI/bge-large-zh-v1.5 |
负责文本向量化 |
| 智能体编排 | LangGraph |
组织问数智能体的多阶段工作流 |
| 大模型调用 | LangChain |
封装模型调用与部分链路能力 |
| 后端接口 | FastAPI |
提供后端服务与接口能力 |
| ORM 与数据访问 | SQLAlchemy |
管理元数据库和数据仓库相关访问 |
| 流式返回 | SSE |
将查询过程与结果实时返回前端 |
| 中文分词 | Jieba |
支撑部分文本预处理和关键词处理 |
| 环境与依赖管理 | uv |
管理 Python 项目环境和依赖 |
| 前端项目 | React + Vite + Tailwind CSS |
承载问数前端页面与交互展示 |
后端用 FastAPI + LangGraph 组织问数流程，用 MySQL + Qdrant + Elasticsearch 搭建元数据知识库，再由大模型完成 SQL 生成、校验和纠错，最后通过 SSE 把执行过程和结果返回给前端。
shopkeeper-agent/
├── app/ # 后端源码主目录
│ ├── agent/ # 问数智能体与 LangGraph 图流程
│ │ └── nodes/ # 关键词抽取、召回、过滤、SQL 生成、校验、执行等节点
│ ├── api/ # 对外 HTTP 接口层，对应 FastAPI 路由、依赖注入和请求参数结构
│ ├── clients/ # 各类基础服务客户端，例如 MySQL、ES、Qdrant、Embedding 服务
│ ├── conf/ # 配置类与配置加载工具，把 YAML 配置转换成代码可直接使用的对象
│ ├── core/ # 通用基础能力，例如日志、生命周期管理、请求上下文等
│ ├── entities/ # 业务实体定义，承接比 ORM 更贴近业务含义的数据结构
│ ├── models/ # ORM 模型，主要对应 MySQL 中的表结构
│ ├── prompt/ # 提示词加载工具，负责读取和组织静态 Prompt 资源
│ ├── repositories/ # 数据访问层，封装 MySQL / Qdrant / ES 的具体读写逻辑
│ ├── scripts/ # 工具脚本，例如构建元数据知识库、初始化或同步数据
│ └── services/ # 业务逻辑层，负责把客户端、仓储层和智能体能力真正串起来
├── conf/ # 项目级 YAML 配置文件，例如数据库、向量库、ES、LLM、日志等配置
├── docker/ # 本地开发环境相关文件，例如 docker-compose 和自定义镜像资源
│ ├── elasticsearch/ # Elasticsearch 相关文件，例如 Dockerfile、插件或初始化资源
│ ├── embedding/ # Embedding 服务相关文件，例如模型目录或推理服务配置
│ └── mysql/ # MySQL 初始化 SQL、建表脚本或测试数据导入文件
├── frontend/ # React + Vite + Tailwind CSS 前端项目
├── logs/ # 本地运行时日志输出目录
└── prompts/ # 静态提示词文件，和 app/prompt 中的加载工具配合使用
如果你已经准备好了，就从下一章开始，正式进入「电商问数」的项目学习。
后面的内容会按照 “项目概述与数仓基础 -> 整体架构与智能体流程 -> 环境准备 -> 元数据知识库 -> 问数链路实现 -> API 接口与前后端联调” 这条主线，逐步把整套项目拆开讲清楚。
学完之后，你收获的不只是“我跑通了一个 AI Demo”，而是能真正讲清楚：一个智能问数系统为什么要这样设计，代码为什么要这样拆，MySQL、Qdrant、Elasticsearch、LangGraph 和 FastAPI 在一条完整业务链路里分别解决什么问题。
