数据Agent14 个章节
数据 Agent 项目
172 次阅读更新于 2026/9/12
从电商数仓到可信数据 Agent
这套资料不是代码说明书，也不是提示词合集。它围绕一个可运行的电商经营分析系统，完整讲清楚如何从业务问题出发，设计数仓和指标语义层，再让 Agent 在受控边界内完成规划、查询、解释、追问和报告沉淀。
完成学习后，你应该能够：
- 从经营问题反推数仓模型，而不是先堆表。
- 用统一的语义层管理指标口径、时间字段和可用维度。
- 区分规则规划、大模型规划、查询执行和结果解释的职责。
- 使用 SQL AST 校验和白名单工具约束 Agent 的执行边界。
- 实现可追踪的多轮分析、证据链和版本化报告。
- 把本地演示项目整理成可以部署、评测和交付的产品。
适合谁
- 希望从传统数仓转向 AI 数据产品的数据工程师。
- 希望做出完整项目，而不只是调用大模型 API 的后端工程师。
- 需要构建企业数据助手的数据分析师和 BI 工程师。
- 希望学习 Data Agent 产品设计、工程实现和商业交付的开发者。
学习者需要具备基础 SQL 和 Python 阅读能力。不了解 DuckDB、FastAPI 或大模型 Structured Outputs 不会阻塞学习，相关概念会在使用时解释。
课程地图
| 阶段 | 章节 | 解决的问题 | 核心产物 |
|---|---|---|---|
| 产品定义 | 01. 业务问题与产品边界 | 为什么不能从聊天框开始做 Data Agent | 业务问题清单、产品边界、可信回答契约 |
| 数据底座 | 02. 电商数仓建模 | Agent 应该查询什么样的数据结构 | ODS、DIM、DWD、DWS 模型 |
| 语义治理 | 03. 指标语义层 | 如何避免模型猜口径、猜表名 | 指标 YAML、维度白名单、指标测试 |
| Agent 核心 | 04. 规则型 Agent | 没有大模型能否跑通分析闭环 | 意图识别、时间推理、分析计划 |
| 大模型接入 | 05. 结构化规划器 | 大模型应该负责什么、不该负责什么 | Structured Outputs 规划器与降级策略 |
| 查询安全 | 06. SQL 校验与执行 | 如何让 Agent 只能做受控查询 | SQLGlot AST 校验、只读执行和审计 |
| 分析体验 | 07. 多轮会话与下钻 | 如何沿用上下文继续定位原因 | SQLite 会话、上下文规划和安全过滤 |
| 产品界面 | 08. Web 工作台 | 如何把 API 变成可使用的分析产品 | 结果表、趋势图、证据链、响应式界面 |
| 分析沉淀 | 09. 报告版本化 | 如何把一次问答变成业务资产 | 不可变快照、版本号、报告库和导出 |
| 产品交付 | 10. 评测、部署与售卖 | 如何证明可用并标准化交付 | 评测报告、Docker、交付清单和授权边界 |
完整的章节目标、依赖和练习见 课程地图。
课程主视觉和技术细节图的使用说明见 图资产说明。
项目架构
架构图采用 C4 三层模型，可编辑源文件为 data-agent-studio-architecture.drawio：
- 01 System Context：参与者、业务数据、系统边界和可选大模型服务。
- 02 Containers：Web、FastAPI、语义层、DuckDB、SQLite 和外部服务。
- 03 Agent Components：规划器、指标目录、查询服务、SQL 安全校验和持久化。
三个 .drawio.png 文件都嵌入了完整图表数据，可以直接拖入 Draw.io 查看和编辑。
推荐学习方式
每章按照同一顺序学习：
业务问题 -> 原理 -> 架构 -> 对应代码 -> 动手任务 -> 验收 -> 复盘
不要只阅读文档。每章完成后都要运行对应代码、修改一个配置或实现一个任务，并用本章验收清单确认结果。
建议保留两个工作目录：
wo-x/：完整参考实现，用于对照和运行。- 自己的练习仓库：从数据契约开始逐章实现，保留提交记录。
文档分层
仓库中的资料分为两层：
materials/：面向学习者和购买者的正式教程，强调学习路径、实践和验收。docs/：项目开发过程、设计原稿和实现日志，保留工程决策的上下文。
正式学习从 materials/ 开始；遇到设计细节时，再跳转到 docs/ 查阅原始记录。
当前版本
当前参考实现已经具备：
- DuckDB 电商分层数仓和指标语义层。
- 规则规划器与可选大模型规划器。
- SQLGlot 只读 SQL 安全校验。
- FastAPI 指标、Agent、会话和报告 API。
- SQLite 多轮会话和报告版本化。
- Web 分析工作台、趋势图、证据链和 Markdown 导出。
- 36 个 Python 单元及 API 测试。
- 20 题结构化评测契约、规则模式评测 runner 和 Docker/Compose 参考部署。
本资料会明确区分“当前已实现”和“产品化待完成”，不会把路线图中的能力写成已经交付的功能。
从这里开始
- 第一次学习先读
BEGINNER_START_HERE.md，完成环境检查。 - 阅读 课程地图，选择学习路径。
- 按照 第 1 章：业务问题与产品边界 完成业务问题清单。
- 继续完成 第 2 章：电商数仓建模，跑通数仓构建和质量检查。
- 继续完成 第 3 章：指标语义层，验证指标口径和安全查询。
- 继续完成 第 4 章：规则型 Data Agent，跑通规划、查询、解释和上下文下钻。
- 继续完成 第 5 章：结构化大模型规划器，理解大模型规划与规则降级。
- 继续完成 第 6 章：SQL 安全、执行与证据链，验证只读查询和安全边界。
- 继续完成 第 7 章：多轮会话与安全下钻，验证上下文继承与会话隔离。
- 继续完成 第 8 章：Web 分析工作台，把 API 变成可使用、可核对、可追问的产品界面。
- 继续完成 第 9 章：报告版本化，把一次分析变成可复核、可回看的业务资产。
- 阅读并执行 第 10 章：评测、部署与商业交付，核对评测报告、部署包和授权边界。
- 按
labs/README.md完成六个渐进练习，再用solutions/README.md复盘。 - 完成 结课项目，提交评测、Web 和报告证据。
- 遇到问题时查 术语表 和 排错手册。
- 需要扩写新章节时，使用
appendix/chapter-writing-standard.md。
课后实践与交付
正文解释设计和实现，labs/ 负责让你动手，solutions/ 负责复盘。实验、参考答案和结课项目都不依赖另一个电商数仓目录；当前项目自带的 DuckDB、样例数据、测试和 Web 服务即可完成全部练习。