11-关键词抽取与多路召回
11 - 电商问数：关键词抽取与多路召回 本章课程目标： 理解为什么问数智能体要先抽取关键词，再进入字段、指标、字段取值三路召回。 掌握 DataAgentState 和 DataAgentContext 在召回阶段各自保存什么。 看懂 PromptTemplate | llm | JsonOutputParser 这条最小 LCEL 链路。 掌握字段召回和指标召回的共同模式：关键词 -> Embedding -> Qdrant -> 去重。 掌握字段取值召回的特殊模式：关键词 -> Elasticsearch -> ValueInfo -> 去重。 学习建议： 这是问数智能体开始填业务逻辑的地方。先看用户问题如何变成关键词，再看关键词为什么需要扩展，最后分别看字段、指标、字段值三路召回。三路代码长得像，但职责不同：字段找列，指标找算法口径，字段值帮过滤条件写对真实取值。 对应代码分支： 11-agent-keyword-multi-recall 1、本章在问数链路中的位置上一章我们已经把问数智能体的 LangGraph 工作流骨架搭起来...
10-问数智能体总览与工作流骨架
10 - 电商问数：问数智能体总览与工作流骨架 本章课程目标： 理解元数据知识库和问数智能体之间的关系。 看清问数智能体为什么不是“一个提示词直接生成 SQL”，而是一条多节点工作流。 理解 StateGraph、State、Node、Edge、Runtime Context、stream_writer 在本项目中的作用。 先不实现节点内部业务逻辑，只把整张工作流图搭起来，并用流式输出验证它能正常执行。 学习建议： 这一章只搭工作流骨架，不解决每个节点的业务细节。读的时候从一个用户问题出发，看它被拆成哪些节点，哪些节点可以并行，哪些地方需要条件分支，状态如何在节点之间传递，进度如何流式输出。后面几章会填节点内部逻辑，这里先把图的形状看稳。 对应代码分支： 10-agent-overview-workflow 前面几章，我们已经把「电商问数」的元数据知识库基本搭好了。系统现在知道有哪些表、有哪些字段、字段是什么意思、字段里有哪些真实取值，也知道业务指标如何定义。具体能力如下： 表信息和字段信息已经保存到 Meta MySQL 字段语义信息已经写入 Qdrant 字段真实取值...
9-字段与指标检索能力构建
9 - 电商问数：字段与指标检索能力构建 本章课程目标： 理解为什么问数系统不能只靠字段信息，而要同时建设字段向量索引、字段值全文索引和指标向量索引。看懂“字段语义召回 -> 字段真实值匹配 -> 指标语义召回”这三条链路分别解决什么问题，以及它们在元数据知识库构建流程中的位置。建立清晰的分层认识：Service 负责编排字段与指标检索能力构建流程，Qdrant Repository 负责字段和指标语义向量落库，ES Repository 负责字段值全文索引落库，DW Repository 负责查询真实字段值。 学习建议： 这一章先分清三类召回对象：字段回答“查哪一列”，字段值回答“过滤条件里的真实值怎么写”，指标回答“业务口径怎么算”。向量索引和全文索引只是实现手段，不是学习起点。读到最终测试时，留意三条链路怎样一起为后面的 SQL 生成准备上下文。 对应代码分支： 09-metadata-retrieval-capability 上一章我们已经把表信息和字段信息沉淀到了 Meta MySQL。这一步解决的是：系统先有一份稳定、结构化的字段元数据。 但只有结构化元...
8-表与字段信息同步到元数据库
8 - 电商问数：表与字段信息同步到元数据库 本章课程目标： 理解为什么元数据知识库的第一步，一定是先把表信息和字段信息沉淀到 Meta MySQL。 看懂“配置描述 -> 业务实体 -> DW 补齐真实信息 -> Meta MySQL 落库”这条完整链路。 建立清晰的分层认识：Service 负责组织流程，DW Repository 负责查询真实结构，Meta Repository 负责落库，Mapper 负责对象转换。 学习建议： 这一章先抓住一条落库链路：配置文件描述表字段，系统去数仓补齐真实结构，再转换成内部实体，最后写入 Meta MySQL。ORM、Repository、事务这些细节都服务于这条链路。读代码时重点看哪些数据来自配置，哪些数据来自 DW，哪些数据最终沉淀到元数据库。 对应代码分支： 08-metadata-table-column-sync 上一章我们已经把“元数据知识库构建”的入口说明白了：脚本如何启动、配置如何加载、服务层如何接过 config_path 并进入真正的业务流程。 从这一章开始，我们正式进入第一条真正落地的业务链...
7-元数据知识库总览与构建入口
7 - 电商问数：元数据知识库总览与构建入口 本章课程目标： 先看清“元数据知识库”为什么是问数系统真正开始工作的前提。 理解一次元数据知识库构建到底会产出什么，以及会写入哪些存储组件。 搞清楚同步脚本是如何从命令行启动、如何把配置传进服务层、以及配置最终如何变成程序对象。 学习建议： 这一章是元数据知识库篇的入口。先看它为什么必须先建，再看同步脚本如何接收配置文件，最后看配置如何进入服务层。读完后最好能回答：为什么不能让大模型直接猜表字段，为什么构建脚本要配置驱动，为什么入口脚本只做调度、不堆业务逻辑。 对应代码分支： 07-metadata-base-overview 前面几章，我们已经把「电商问数」运行所需的基础设施准备好了，包括：MySQL、Qdrant、Elasticsearch、Embedding、配置管理、日志管理、客户端封装。 这些内容本质上都在做一件事：**为真正的业务逻辑做准备。**前面第 1 章和第 2 章，已经分别讲清楚了「电商问数」要解决什么问题，以及这套系统整体是怎么运转的。因此从这一章开始，我们不再重复项目背景，而是把视角正式切进第一条核心业务...
6-MySQL、Embedding与日志管理
6 - 电商问数：MySQL、Embedding 接入与日志管理 本章课程目标： 看懂 Embedding 客户端管理器的作用，以及它与后续向量检索之间的衔接关系。 理解 MySQL 在当前项目里同时承担元数据库和数据仓库模拟库两类角色。 了解项目如何通过统一日志配置支撑调试、排障和运行观察。 学习建议： 这一章是三块基础能力的接线图：Embedding 负责把文本变向量，MySQL 负责存和查结构化数据，日志负责让你知道系统跑到哪一步。读代码时别只看封装类本身，要追它们在哪里初始化、如何注入到业务层、出了错能不能通过日志定位到请求。 对应代码分支： 06-mysql-embedding-log 上一章我们已经把 Qdrant 和 Elasticsearch 接进来了，但其实还有两个关键问题没闭环： Qdrant 里要写的向量，到底从哪里来？ 检索、建库、执行 SQL 的过程中，结构化数据和运行日志怎么统一管理？ 这一章讲的正是这两个问题。 把它们放回整体架构里，可以概括成下面这条链： 12345678910文本 -> Embedding 服务 -> 向...
5-Qdrant与ES快速入门与接入
5 - 电商问数：Qdrant 与 ES 快速入门与接入 本章课程目标： 理解 Qdrant 和 Elasticsearch 在「电商问数」里的职责边界，而不是把它们都当成“检索组件”混在一起。 掌握向量数据库、全文检索、mapping、collection、payload 等核心概念。 看懂项目里的 QdrantClientManager 和 ESClientManager 是如何封装、初始化与测试的。 学习建议： Qdrant 和 ES 都叫检索，但不要把它们混成一个东西。读这篇时先记住分工：Qdrant 更适合语义相似度召回，ES 更适合全文匹配和精确过滤。跑 quickstart 的目的不是熟练所有 API，而是看清 collection / point / payload 和 index / document / mapping 分别在项目里对应什么。 对应代码分支： 05-qdrant-es 很多同学第一次看到这套项目时，都会问一个很自然的问题： 既然都是“检索”，为什么还要同时接 Qdrant 和 Elasticsea...
4-项目结构与基础服务配置管理
4 - 电商问数：项目结构与基础服务配置管理 本章课程目标： 先建立对 shopkeeper-agent 项目结构的整体认识，知道代码、配置、提示词和脚本分别放在哪里。 理解当前项目默认依赖哪些服务端口，以及这些端口与后续基础服务之间的关系。 掌握本项目的配置参数管理方式，理解 YAML 配置、dataclass 结构定义和 OmegaConf 加载链路。 学习建议： 这篇先看项目骨架，再看配置对象如何被创建和复用。重点不是记住每个目录名，而是理解 MySQL、Qdrant、ES、Embedding 为什么都应该从同一套配置体系取参数。读完后再看各类客户端代码时，可以顺手追一下：它们拿到的 host、port、key 到底从哪里来。 对应代码分支： 04-structure-config 这一章开始，我们正式进入「电商问数」的基础服务搭建部分。 这里的“基础服务”可以看作三类和业务无关、但项目运行离不开的内容： 各类外部服务客户端例如 MySQL、Elasticsearch、Qdrant、Embedding 服务的客户端 配置与日志例如配置文件加载、日志输出、通用基础能力...
3-开发环境与基础服务准备
3 - 电商问数：开发环境与基础服务准备 本章课程目标： 理解「电商问数」项目为什么使用 uv 管理 Python 环境与依赖。 掌握 uv add、uv remove、uv sync 这几个最常用命令。 明确本项目依赖哪些基础服务，以及这些服务分别解决什么问题。 了解 Docker Desktop、镜像加速、代理配置和 docker compose 的基本使用方式。 学习建议： 这一章更适合当成环境清单来读。先把项目创建、依赖安装、.env 配置这些后端准备做完，再确认 MySQL、Qdrant、Elasticsearch、Embedding 服务是否能启动。不要急着看业务代码；只要基础服务没跑稳，后面的报错大多都会变成环境问题。 对应代码分支： 03-env-services 1、先建立整体认识在正式动手之前，建议先知道「电商问数」这套工程大致由哪些部分组成。 当前实际项目仓库是 shopkeeper-agent，前后端代码放在同一个仓库里： 后端入口：shopkeeper-agent/main.py 后端代码：shopkeeper-agent/app/ 前端项目：s...
2-项目整体架构与智能体流程
2 - 电商问数：项目整体架构与智能体流程 本章课程目标： 从整体上理解「电商问数」的项目整体架构，知道元数据知识库、同步脚本、问数智能体分别解决什么问题。 理解元数据库、向量索引、全文索引三者的分工关系，以及它们如何共同支撑 SQL 生成。 按流程图掌握问数智能体的执行链路，并建立“架构图和代码目录基本一一对应”的工程感知。 学习建议： 这一章是全项目总图，别当知识点清单背。先分成两大段：离线构建元数据知识库，在线根据用户问题调用知识并生成 SQL。读到某个表、字段或节点觉得细时，先问它属于“构建知识”还是“查询使用知识”。能画出这两段链路，后面细节会自己归位。 1、整体架构概述1.1 先看整体链路第 1 章已经回答过「电商问数」是什么项目，也介绍了它为什么属于典型的 NL2SQL 场景。因此进入这一章后，我们重点看：这套系统在工程上到底是怎么跑起来的。 一句话来说这套系统的工作方式，可以概括成下面这句话： 先把数据仓库里的表、字段、指标、字段取值等知识整理成一套可检索的元数据知识库，再让问数智能体基于这套知识库生成、校验并执行 SQL。 可以把整条链路看作下面这个顺序：...