企业官网建设流程全解析

配套源码仓库地址：GitHub - didilili/shopkeeper-agent: 📊 电商数仓智能问数 AI Agent，最适合用于系统学习 LangGraph 的实战项目

笔记主要是对原本的教程做一些增删查，增加了实际运行遇到的一些坑，删除了觉得啰嗦的地方，对教程里面遇到的问题，会上网查一下，写在笔记里。

原本的Agent教程AI 智能体实战速成指南：从零到企业级落地 | ai-agents-from-zero 也挺推荐的，都有配套的代码

这章主要是总览，了解项目的技术栈，业务场景，目录结构等

电商问数 前言

项目把MySQL、LangGraph、Qdrant、Elasticsearch、Embedding、FastAPI、SSE和前端联调放进同一条业务链路里，用一个自然语言问数场景，把智能体项目开发中最关键的知识点串起来：

• 用MySQL模拟教学数仓和元数据库
• 用Qdrant做字段和指标的语义向量检索
• 用Elasticsearch做字段真实取值的全文检索
• 用LangGraph编排多阶段问数智能体工作流
• 用FastAPI + SSE把后端能力交付给前端页面

一句话概括：「电商问数」不是一个只会让大模型裸写 SQL 的 Demo，而是一套围绕“先构建元数据知识库，再检索、推理、生成、校验和执行 SQL”展开的智能问数实战项目。

这个项目到底在做什么

它可能不是一个完整的企业级生产系统，但非常适合作为入门到进阶阶段的项目实战课程。你可以在这里系统学习一套智能体应用从“数据准备”到“检索增强”，再到“工作流编排”和“接口交付”的完整主链路。

在真实企业里，业务同学通常不会写 SQL，数据分析同学也不可能随时记住所有表结构、字段含义和指标口径。于是就会出现一个非常典型的需求：

• 能不能直接用自然语言提问？
• 系统能不能自动找到相关表、字段和指标？
• 能不能自动生成 SQL，并返回可以真正拿来分析的结果？

「电商问数」要解决的，就是这个问题。

下面这张图可以先帮助你建立整体印象：用户提出自然语言问题后，系统会经过后端调度、字段和表结构召回、自然语言转 SQL、数据库查询、SSE 流式推送，最后把结果展示给用户。

从使用者视角看，它就是一个“会查数的智能数据分析助手”：

1. 用户先用自然语言提问
2. 系统理解问题，并抽取适合检索的关键信息
3. 再到元数据知识库中召回相关表、字段、指标和字段取值
4. 把这些信息整理成更适合大模型理解的上下文
5. 再由大模型生成 SQL，并做必要的校验和纠错
6. 最后到数据仓库执行 SQL，并把过程和结果返回给前端

当一次查询真正跑起来时，前端不只是等待最后结果，而是可以看到 LangGraph 工作流的执行过程：抽取关键词、召回字段信息、召回指标信息、召回字段取值、合并召回信息、过滤上下文、生成 SQL、校验 SQL、执行 SQL，最后展示查询结果。

所以，这个项目的重点从来不只是“大模型”，而是下面这整条链路：

• 数据仓库怎么设计和模拟
• 元数据知识库怎么构建
• 字段、指标、字段取值怎么做混合检索
• 智能体怎么基于上下文生成更可靠的 SQL
• 后端服务怎么把智能体能力交付给前端
• 日志和异常怎么帮助排查一条完整请求链路

后面的章节都会围绕这条主线展开：先把数仓里的表、字段、指标和字段取值整理成元数据知识库，再让问数智能体基于这套知识库完成检索、推理、SQL 生成、校验、执行和结果返回。

技术栈

当前这套实战项目主要使用了下面这些技术：

后端用FastAPI + LangGraph组织问数流程，用MySQL + Qdrant + Elasticsearch搭建元数据知识库，再由大模型完成 SQL 生成、校验和纠错，最后通过 SSE 把执行过程和结果返回给前端。

它重点覆盖问数系统最核心的主链路：教学数仓、元数据知识库、混合检索、LangGraph 工作流、SQL 生成校验执行、FastAPI 接口、SSE 返回、前后端联调和日志追踪。

但是不会在第一个项目里展开所有生产级能力，比如：

• 用户权限和数据权限控制
• 多租户隔离
• 复杂 SQL 安全审计
• 查询缓存和性能治理
• 完整评测体系
• 监控告警和链路追踪平台
• 灰度发布和生产部署治理
• 更复杂的多轮问数记忆系统

项目目录结构

感觉内容还挺多的

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 中的加载工具配合使用