Python Agentic RAG 实战教程写作契约
本文是后续实战系列的唯一写作基准，并随仓库版本管理。正式章节开写前必须先核对本文；如果项目范围、技术栈或章节目标发生变化，先修改本文，再修改教程。不能一边写一边临时扩展范围。
一、为什么先写这份契约
这个系列不是再补一组零散的 Agent 文章，而是把全栈之路已有的 Python、后端、RAG、Agent、数据库、异步任务和部署知识组合成一个可以运行的项目。
它需要同时达成三个目标：
- 是完整教程：读者能从空目录开始，按顺序得到一套可运行、可测试、可部署的系统。
- 体现 AI 应用开发思路：正文把篇幅留给切分、检索、状态编排、权限、可靠性和评测等关键决策，不逐行讲普通 CRUD。
- 能支持求职：读者做完后能演示项目、解释架构、展示实验记录，并如实写成个人实战项目。
任何章节如果只满足其中一项，都不能算完成。
二、目标读者
读者已经具备
- 有前端、Node.js 或普通全栈开发经验。
- 理解 HTTP、REST、SQL、Git 和 Docker 的基本用法。
- 学过 Python 基础，能够读懂函数、类、类型标注和异步代码。
- 看过或愿意按链接补充本站的 Agent 与 RAG 原理文章。
读者希望获得
- 从普通全栈开发转向 AI 应用、AI 全栈或 Agent 工程岗位。
- 不再停留在调用一次模型 API 的 Demo 阶段。
- 拥有一个能运行、能演示、能测试、能解释的个人实战项目。
- 能回答面试官对检索、引用、状态机、权限、失败恢复和效果评测的连续追问。
本教程不承担
- 从变量、循环开始教授 Python。
- 训练或微调基础模型。
- 讲解向量和 Transformer 的数学推导。
- 模拟无法验证的商业数据或虚构上线效果。
- 把购买的 NestJS 项目逐文件翻译成 Python。
三、读完后的可执行结果
读者完成全部章节后，应当能够独立完成下面的动作：
- 在本地用 Docker Compose 启动整套系统。
- 创建用户、团队和知识库，上传并审核一份真实文档。
- 查看解析、切分、Embedding 和索引任务的执行进度。
- 对文档进行普通 RAG 问答，获得可以定位到原文的引用。
- 对比较、多跳和证据不足的问题启动 Agentic RAG。
- 在页面或 API 客户端中看到 Agent 的流式执行过程。
- 验证不同用户无法召回无权访问的文档。
- 注入任务失败并观察重试、补偿和索引恢复。
- 运行离线评测，比较修改前后的检索与回答指标。
- 根据真实代码、测试和实验记录整理项目介绍。
四、项目画像
项目名称
企业知识库 Agentic RAG 平台。
核心业务
企业将制度、产品资料、项目文档和技术手册上传到知识库。文档经过审核、解析和索引后，员工可以获得带原文引用的回答。简单问题走固定 RAG；比较、多跳和证据不足的问题由 Agent 改写查询、拆分问题、多轮检索并检查证据。所有检索必须遵守用户、团队、知识库和文档状态权限。
技术栈基线
2026-09 修订：为了让读者零外部依赖跑通、把学习重心放在链路与决策上，配套项目把“教学基线”与“生产迁移目标”分开声明。本次先更新契约，各章再同步边界声明。
教学基线（当前实际交付）：
- Python 3.12（uv 管理）
- FastAPI、Pydantic
- SQLAlchemy 2（async，默认 aiosqlite，asyncpg 驱动已声明）
- 进程内向量索引（查询前重建，教学取舍）
- SQLite 任务表（入库队列）
- 本地文件系统对象存储（MinIO 客户端可切换）
- OpenAI-compatible 模型接口（httpx 直连，未引入 LangChain）
- LangGraph
- Python Worker、SSE、Docker Compose
生产迁移目标（出现在各章边界声明中的“后续方向”，不是当前交付）：
- PostgreSQL + pgvector、Redis 队列、MinIO、Alembic 迁移
- 持久化 Checkpoint、租约与共享队列、OpenTelemetry
技术栈不是展示清单。新增 Elasticsearch、消息队列、图数据库或其他基础设施之前，必须先有当前方案无法满足的可复现问题，并在正文比较新增后的收益和运维代价。
与参考项目的关系
购买的 NestJS 知识库项目只作为业务流程和工程问题的参考素材。教程使用 Python 重新建模和实现，并补齐 Agentic RAG、权限下推、可靠性、评测、可观测性与测试。
私人的面试答辩材料不是教程实现依据。教程不能继承其中的公司名称、任职时间、职责边界和占位数字。所有教程指标必须由配套项目实际运行得到。
配套代码与当前进度
配套代码统一放在 projects/agentic-rag/，正式文章放在 guide/。每章只能在同一个配套项目上继续演进。
| 章节 | 状态 | 已验证产物 |
|---|---|---|
| 第 1 章：项目目标与架构 | 已完成 | 业务场景、5 份样例文档、11 条验收问题、一致性校验脚本和 4 个边界测试 |
| 第 2 章：最小 RAG 闭环 | 已完成 | FastAPI 上传与问答、Markdown 切分、可替换模型接口、内存向量检索、来源返回和 10 个测试 |
| 第 3 章：用户、团队与权限 | 已完成 | 开发 JWT、服务端用户目录、资源级写权限、检索前权限与状态过滤、固定样例加载和 Alice/Bob 对照测试 |
| 第 4 章：文件存储与文档生命周期 | 已完成 | SQLAlchemy 文档元数据、文件系统与 MinIO 对象存储适配器、草稿/待审核/发布/归档状态、乐观锁发布和版本归档测试 |
| 第 5 章：多格式解析与结构化切分 | 已完成 | PDF、Word、PPT、Excel、Markdown 与文本的统一解析入口，保留页/幻灯片/工作表定位标题，以及多格式解析测试 |
| 第 6 章：异步入库与任务状态 | 已完成 | 持久化任务表、独立 Worker、进度查询、取消、失败重排队和单任务条件领取测试 |
| 第 7 章：混合召回与 Rerank | 已完成 | 权限内向量与关键词召回、RRF、确定性 Rerank、Profile 和管理员检索调试测试 |
| 第 8 章：上下文、引用与拒答 | 已完成 | Evidence 预算、请求内来源 ID、Claim 与数值支持校验、可解释拒答和 API 测试 |
| 第 9 章：问题分类与执行路线 | 已完成 | 确定性路由、敏感请求拒绝、受限历史版本入口、显式降级和路由测试 |
| 第 10 章：LangGraph 多轮检索状态机 | 已完成 | LangGraph 规划、受限多轮检索、预算退出、节点轨迹和跨轮权限范围测试 |
| 第 11～17 章：完整教程路线 | 核心本地链路已完成，生产扩展进行中 | 工具、会话摘要、发布提案、SSE、Outbox 记录、健康探针、本地评测 Runner 与求职复盘已落地；持久化 Checkpoint、Redis Relay、租约索引切换、OpenTelemetry 和真实多服务部署仍标为规划项 |
五、写作与实现的不可变规则
1. 始终按一个项目向前建设
每章必须基于上一章的可运行代码继续修改。不能为了讲一个知识点，另起一套与主项目无关的示例代码。
2. 第二章就交付最小闭环
读者不能连续阅读多章配置和 CRUD 才看到 AI 效果。第二章结束时必须能够上传一份样例文档，并得到一条带来源的回答。后续章节再逐步替换其中的简化实现。
3. 正文重点是关键决策
普通路由、DTO、Repository 和重复性模型代码应当完整存在于配套仓库，但正文只解释其项目约定。正文重点包括：
- 文档结构如何保留。
- Chunk 为什么这样切。
- 检索失败发生在哪里。
- 为什么需要混合召回或 Rerank。
- Agent 为什么进入或退出循环。
- 权限在哪一层过滤。
- 失败后如何恢复。
- 如何证明修改有效。
4. 每个能力都要有业务入口
不能单独写“接入 Redis”“接入 LangGraph”或“增加 Rerank”。必须先说明它解决哪条项目链路中的具体问题，再实现和验证。
5. 先固定 RAG，后 Agentic RAG
先建立可以评测的固定 RAG 基线，再升级复杂问题。不能一开始就把所有逻辑交给 Agent，也不能为了展示框架而制造无意义的自主决策。
6. 思路必须落到代码和证据
每个核心设计至少包含：实现代码、运行方法、一个正常样例和一个失败或边界样例。涉及效果提升时必须给出同一数据集上的前后对比。
7. 面试整理不能侵入教程主线
正文按项目建设展开，不写成高频问答。面试表达集中放在阶段复盘和最终章，内容必须来自已经实现和验证的功能。
8. 不虚构生产结果
可以给出本地实验指标、测试结果和容量估算，但必须写清环境、样本量和口径。没有运行证据时只能写目标或预期，不能写成已经达成。
六、正式章节路线
第一阶段：先交付最小产品
| 章 | 标题 | 项目增量 | 完成标志 |
|---|---|---|---|
| 1 | 项目效果、需求与架构 | 展示最终产品，确定业务边界、技术基线、数据流和验收集 | 读者知道最终要实现什么，以及如何判断完成 |
| 2 | 从空目录跑通第一条 RAG 链路 | FastAPI 骨架、最小上传、最小切分、Embedding、检索和引用回答 | 上传样例文档后能得到第一条带来源回答 |
第二阶段：建立企业知识库后台
| 章 | 标题 | 项目增量 | 完成标志 |
|---|---|---|---|
| 3 | 用户、团队、知识库与权限模型 | JWT、团队成员、知识库角色和资源级权限 | 两个用户能看到不同的知识库和文档 |
| 4 | 文件存储、审核与文档生命周期 | MinIO、草稿、审核、发布、下架和版本 | 未发布文档不可检索，新版本可以替换旧版本 |
第三阶段：把固定 RAG 做正确
| 章 | 标题 | 项目增量 | 完成标志 |
|---|---|---|---|
| 5 | 多格式解析与结构化切分 | PDF、Word、PPT、Excel、页码/幻灯片/工作表定位标题；父子 Chunk 与坐标定位列为生产扩展 | 可以查看并比较同一文档不同格式的解析输出 |
| 6 | 异步入库与任务状态 | Worker、解析、切分、Embedding、索引、进度和失败信息 | 大文件不阻塞接口，失败任务可以定位并重新执行 |
| 7 | 向量、关键词、混合召回与 Rerank | 教学内存向量与关键词召回、RRF、确定性 Rerank；pgvector 与相邻块合并列为生产扩展 | 在固定问题集上比较各阶段的召回与排序 |
| 8 | 引用、拒答与上下文构造 | Token 预算、结构化答案、引用校验和证据不足拒答 | 每条有效答案可定位原文，无证据问题不会编造来源 |
第四阶段：升级为 Agentic RAG
| 章 | 标题 | 项目增量 | 完成标志 |
|---|---|---|---|
| 9 | 问题分类与执行路线 | 闲聊、固定 RAG、总结、比较、多跳和敏感操作路由 | 同一入口能选择简单链路或 Agentic 链路 |
| 10 | LangGraph 多轮检索状态机 | 查询改写、问题拆解、证据判断、再次检索、循环与预算 | 复杂问题能有限次补充检索，并且不会无限循环 |
| 11 | 工具、记忆、Checkpoint 与人工介入 | 历史版本工具、会话摘要、发布提案与人工确认 | 工具和确认接口可运行；持久化 Checkpoint 明确列为后续扩展 |
| 12 | SSE 流式输出与事件协议 | 版本化 Envelope、递增序号、节点、答案、引用和终态事件 | 客户端能看到稳定、可解析的最小执行事件流 |
第五阶段：达到可交付标准
| 章 | 标题 | 项目增量 | 完成标志 |
|---|---|---|---|
| 13 | 权限安全与越权检索测试 | JWT、检索权限下推、Prompt Injection、版本工具边界 | 自动化测试证明用户无法召回或读取无权文档 |
| 14 | 入库可靠性与索引一致性 | Outbox、幂等、重试、补偿和索引版本切换 | 注入中断和重复消费后，文档最终状态仍一致 |
| 15 | RAG 与 Agent 离线评测 | 固定 JSONL、路由、来源召回、拒答和越权泄漏指标 | 可以用同一命令比较本地 Demo 版本；Token/成本/LLM Judge 仍待接入 |
| 16 | 可观测性、测试与部署 | 健康探针、Dockerfile、Compose 单机入口、测试与评测命令 | 新环境可以启动本地 API/Worker，生产 Trace、备份和多服务拓扑明确标为待办 |
| 17 | 项目复盘与求职材料 | 基于当前代码、测试和本地基线整理演示脚本与简历边界 | 已实现能力与生产规划项分开表述，每项结果可指向仓库证据 |
七、与全栈之路知识体系的映射
实战章节不重复完整讲授已有理论，而是在需要时简要回顾并链接原文，然后说明本项目如何应用和验证。
| 实战内容 | 必须融合的已有知识 |
|---|---|
| 最小 RAG 与入库 | RAG 入库链路 |
| 切分与复杂文档 | 多模态 RAG、上下文工程 |
| 混合检索与排序 | 混合检索与 Rerank |
| 引用与拒答 | 引用溯源与拒答 |
| 选择固定链路或 Agent | Agent 工程总览、Agent 范式与框架选型 |
| 多轮检索状态机 | LangGraph 状态机 |
| 工具和人工介入 | Tool Calling 与 MCP、Multi-Agent 与人工兜底 |
| SSE | Agent 流式输出 |
| 权限与攻击面 | Agent 安全 |
| 失败恢复 | Agent 生产可靠性 |
| 效果证明 | Agent 与 RAG 评测 |
| Trace、成本和容量 | Agent 可观测性 |
“融合”不等于在每章末尾放一个链接。正文必须明确指出：当前项目使用了哪条原则、对应哪段代码、通过什么样例验证。
八、每章统一结构
正式章节统一按下面顺序写。小节名称可以为可读性调整，但内容不能缺失。
1. 本章完成后的可见结果
先展示接口、页面、日志或指标结果，让读者知道本章会给项目增加什么。
2. 当前系统的缺口
说明上一章为什么还不能满足当前业务。缺口必须可以通过请求、数据或失败样例复现，不能只说“为了更完善”。
3. 方案与取舍
给出选用方案、至少一个合理替代方案，以及本项目当前选择的依据。避免为尚未出现的问题提前堆基础设施。
4. 完成这一条纵向链路
按数据流讲解本章实现。只展开关键代码和状态变化，完整工程代码由配套项目承载。
5. 运行和观察
提供可复制的启动、请求或操作步骤，并给出预期结果。命令应在发布前实际执行。
6. 失败与边界验证
至少验证一个失败或边界场景，例如解析失败、证据不足、越权访问、重复消息、模型超时或客户端取消。
7. 本章小结与下一步
正文只总结读者完成了什么，以及下一章会在当前系统上增加什么。作者使用的完成清单、文件数量、内部校验命令和写作过程记录保留在项目规范或测试中，不能直接搬进公开教程。
阶段结束时可以增加一次项目复盘；普通章节不插入大段面试问答。
九、明确禁止的流水账写法
出现下面任一情况，应停止扩写并重构章节：
- 连续多页都在安装依赖、创建目录、声明 DTO 或粘贴配置。
- 用“第一步、第二步、第三步”罗列操作，却没有解释数据怎样流动以及为什么这样设计。
- 为展示技术而接入组件，正文没有可复现的问题和前后对比。
- 示例代码脱离主项目，章节结束后无法合并回完整系统。
- 只展示成功路径，没有错误、权限、超时或恢复验证。
- 声称性能、准确率或成本得到提升，却没有数据集、环境和测量口径。
- 重复抄写现有 Agent 理论，没有说明项目中的具体应用。
- 把教程写成面试问答，导致项目建设主线频繁中断。
- 一章引入过多新概念，读者无法判断真正需要掌握的核心变化。
- 每章都换一套示例数据，导致前后实验不能比较。
十、单章完成定义
一章只有同时满足下面条件才可以发布：
- [ ] 在上一章代码基础上产生可见的项目增量。
- [ ] 开头明确本章完成后的运行结果。
- [ ] 使用统一的企业文档样例和评测问题集。
- [ ] 至少解释一个关键设计取舍。
- [ ] 关键代码已进入配套项目，不依赖文章中的残缺片段。
- [ ] 提供读者可以执行的运行或调用步骤。
- [ ] 至少验证一个正常场景和一个失败或边界场景。
- [ ] 涉及效果时提供实际测量结果和口径。
- [ ] 与相关的全栈之路知识文章建立具体联系。
- [ ] 没有虚构公司经历、用户规模或线上指标。
- [ ] 完成本章后，整个项目仍然可以启动。
- [ ] 正文没有泄露作者工作流、写作契约或内部完成清单。
- [ ] 文末只保留面向读者的小结和下一章连接，不堆面试题。
十一、系列级验收和防偏离机制
写每章之前
- 从第六节找到本章唯一的项目增量和完成标志。
- 从第七节确定要应用的已有知识。
- 写出本章正常样例、失败样例和验证命令。
- 如果这些内容写不出来，先补设计，不能直接开始填正文。
写每章之后
- 按第十节逐项验收。
- 重新运行项目和本章验证命令。
- 删除不能帮助读者完成项目的背景知识和重复代码。
- 检查有没有把计划、预期或估算写成既成结果。
每完成一个阶段
- 从空环境重新启动当前版本。
- 重跑固定样例和评测集。
- 检查后续目录是否仍与实际项目一致。
- 只有出现真实实现冲突时才调整目录；不能因为写作过程中想到新技术就自由扩展。
变更规则
- 改变项目定位、核心技术栈、章节数量或 Agent 路线时，先更新本文并记录原因。
- 小范围代码调整可以直接进行，但不能改变本章完成标志。
- 新增组件必须同时记录它解决的问题、替代方案和验证方法。
- 最终项目与本文不一致时，以经过更新并重新确认的本文为准，不能靠聊天上下文解释。
十二、写作停止条件
当第 17 章完成，并且下面四项都有实际证据时，系列才算结束：
- 可运行：新环境能按文档启动并完成端到端演示。
- 可验证：关键链路有自动化测试和固定评测集。
- 可解释：架构、状态流、权限边界和失败恢复都有明确记录。
- 可求职使用：项目描述中的每个功能和指标都能在仓库里找到实现或实验依据。