The Talk-to-Data Project¶

企业级 Agentic BI 与语义治理平台：用自然语言提问 → 三层语义治理 + R/V/G/D 四引擎检索 → AI Agent 编排生成可信 SQL → 安全执行并返回图表与洞察。

本站点是 TTD 的学习式技术文档——一本由浅入深、讲清设计取舍、关联 AI Agent 前沿理论的工程实践书。它既适合第一次接触项目的开发者建立认知，也适合有经验的工程师评估选型、寻找改进方向。

这是什么项目¶

TTD（The Talk-to-Data）把"让业务人员用大白话查数"这件事做成了一个可治理、可解释、安全执行的工程系统，而非一个会出 SQL 的聊天机器人。

不是：把问题丢给 LLM，让它自由发挥生成 SQL。
而是：先用语义治理资产（术语、指标、业务规则）约束 LLM 的"想象空间"，再用确定性图算法规划表路径，最后用五层护栏守住安全与性能底线。

flowchart LR
    Q[用户自然语言问题] --> SUP[Supervisor 嵌入 + 治理]
    SUP --> QU[Query Understanding 意图解析]
    QU --> RTR{Router 7 路由}
    RTR --> RAG[R/V/G/D 四引擎检索]
    RAG --> SP[语义规划器<br/>Steiner 树 + 代数重写]
    SP --> SQL[SQL 生成]
    SQL --> GR[五层护栏]
    GR --> EX[数据面执行]
    EX --> VZ[可视化 + 洞察]
    VZ --> OUT[流式返回]

一个诚实的提醒

TTD 是一个学习与工程实践结合的项目。它的架构设计在部分维度上并非业界最优——本文档不会回避这一点。每一章的"方案选型对比"小节都会指出当前实现的可改进之处，并给出具体的优化方向。这不是缺陷清单，而是工程演进的路线图——让后续开发者能真正理解设计取舍、把系统推向更好。

四大子项目¶

#	子项目	路径	职责
1	Semantic Plane	`semantic-plane/`	三层治理元数据资产（YAML）：表/指标 → 术语关系 → 业务规则与上下文
2	Data Plane	`data-plane/`	本地数据执行环境（PostgreSQL + AGE + pgvector + pg_mooncake + MinIO）
3	Backend	`backend/`	AI Agent 编排服务（FastAPI + LangGraph + 多模型 + 元数据发布管道）
4	Web	`web/`	对话式分析前端（Next.js 16 + React 19 + Zustand + shadcn/ui）

另有 deploy/（部署编排）和 scripts/（CI 校验工具）作为横切关注点，不单列为子项目。

这本文档怎么读¶

文档按六个部分组织，由浅入深。建议新读者按顺序读第一部到第三部；有经验的读者可直接跳到感兴趣的章节。

部分	内容	适合谁
第一部 · 导论	第 1 章：Agentic BI 是什么、TTD 在其中的位置、与主流方案对比	所有人
第二部 · 整体设计	第 2-3 章：整体架构与设计哲学、18 条关键设计决策（ADR）	想理解全局的人
第三部 · AI Agent 内核	第 4-8 章：编排、RAG 检索、SQL 生成、记忆、工具调用——系统的核心	后端 / AI 工程师
第四部 · 子系统设计	第 9-12 章：语义治理、数据面、后端服务、前端	子系统负责人
第五部 · 工程实践	第 13-15 章：开发流程、运维安全、质量评估	全体开发者
第六部 · 演进与改进	第 16 章：系统性梳理可改进点与演进路线——动手优化前必读	想贡献改进的人

按角色推荐路径¶

开发者数据治理（Data Steward）运维 / 平台

第 1 章导论 — 建立整体认知
第 2 章整体架构 — 理解在线/离线两条链路
第 4 章 Agent 编排 — 进入 AI Agent 内核
按负责子系统深入：Backend / Web / Data Plane
第 13 章开发流程 — 分支策略、CI/CD、Task 命令
第 16 章演进路线 — 找到可以贡献的改进点

第 1 章导论 — 理解 Agentic BI 的治理诉求
第 9 章 Semantic Plane — 三层治理模型、9 类资产、Git+CI/CD 发布管道
第 5 章 RAG 检索 — 资产如何被运行时消费
第 10 章 Data Plane — H&M 测试数据集
第 15 章质量评估 — LLM-as-a-Judge 与回归基线

第 1 章导论 → 第 2 章整体架构
第 10 章 Data Plane — 本地数据执行环境
第 14 章运行与安全 — 可观测性、安全策略、回滚方案
附录 B 环境变量 — 完整配置参考
附录 C 仓库地图 — 快速定位文件与模块

五分钟本地预览¶

# 使用 uv 一键启动 MkDocs 开发服务器（支持热更新）
uvx --with mkdocs-material mkdocs serve

启动后访问 http://127.0.0.1:8000，保存任意 Markdown 文件后浏览器自动刷新。

完整启动开发栈

预览文档只需上面的命令。若要跑通完整系统（数据面 + 后端 + 前端），请参考第 13 章开发与协作流程的"五步启动"。

演示¶

文档治理说明¶

范畴	策略
当前维护入口	本站点（`docs/book/`）——单一可信来源（Single Source of Truth）
术语权威	附录 D 术语表统一定义 R/V/G/D 等所有术语
配置权威	附录 B 环境变量是环境变量的唯一完整参考
贡献方式	修改 `docs/book/` 下 Markdown → PR → 自动部署

这本文档的不同之处¶

与传统的 API 参考手册相比，本文档刻意做了三件事：

由浅入深的叙事——每章从"背景与动机"讲起，再到"设计原理"、"实现详解"，最后才是"选型对比"。读者能理解"为什么这样设计"，而不只是"这样用"。
深度关联 AI Agent 理论——每章核心节都有"AI Agent 理论关联"块，把 ReAct、Plan-and-Execute、RAG 范式演进、记忆模式、Tool Use 等通用理论与本系统的实现选择对应起来，便于举一反三。
批判性选型对比——每章的"方案选型对比"小节不只罗列主流方案，还会客观指出当前实现可改进之处，并给出优化方向。这部分内容与第 16 章演进路线相互呼应。

准备好了？从第 1 章导论开始吧。