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