KnowForge RAG Platform — 学习大纲¶
本目录包含 20 章系统化学习内容，并在第 04 章之后安排一个 Vibe Coding 实践单元。这个实践单元先复用已经学过的 Milvus 索引和混合检索知识，再用 Codex 完成一个简易 RAG。
如何使用本文档¶
- 第一次学习：先完成 01-04，建立 RAG、LangChain 和 Milvus 基础；再完成实践单元，把混合检索、Reranker 和 LLM 串成一条可运行链路；之后继续学习 05-11、12-13 和 14-20
- 有经验的开发者：先看 内容结构表 速览全貌，再挑薄弱章节精读
- 赶时间的项目汇报准备：优先看 01 → 02 → 03 → 04 → 实践单元 → 05 → 08 → 10 → 11
主次分层¶
这套学习内容不要求初次阅读把所有内容都学到同一深度。推荐按四层吸收：
| 层级 | 内容范围 | 学习要求 |
|---|---|---|
| P0 基础与实践 | 01、02、03、04、实践单元 | 首轮必须掌握，能用 AI 完成一条混合检索 RAG 闭环。 |
| P0 主链路 | 05、06、07、08、09、10、11 | 首轮必须掌握，能说明企业级在线问答闭环。 |
| P1 核心工程能力 | 12、13、14、15、16、17、18 | 第二阶段掌握，能说明应用入口、Web 异步、入库、版本、隔离、评测和测试。 |
| P2 企业化增强 | 19、20、多场景、可选 LangSmith Trace、本地 Evaluation、生产部署、Docker 交付深化、容量评估、企业 overlay、资料治理 | 项目亮点，体现企业级项目经验。 |
| P3 扩展方向 | OCR/VLM、GraphRAG、LlamaIndex 入库替代 | 知道边界和规划即可，不放进首轮主线。 |
详细拆分见下方 内容总览 表格。
学习路线图¶
flowchart LR
subgraph Phase1["第一阶段：基础概念"]
L01["01 项目概述<br/>Docker环境搭建"]
L02["02 RAG 核心<br/>概念深入"]
end
subgraph Phase2["第二阶段：核心 RAG 链路（P0）"]
L03["03 LangChain<br/>生态系统 ⚠️"]
L04["04 Milvus 索引<br/>机制与基本操作"]
L045["第二阶段实践<br/>Vibe Coding 简易混合检索 RAG"]
L05["05 意图<br/>分类"]
L06["06 检索策略与<br/>动态计划"]
L07["07 查询改写<br/>与变体生成"]
L08["08 Milvus<br/>混合检索"]
L09["09 QAService<br/>核心编排"]
L10["10 RAG Pipeline<br/>主流程"]
L11["11 Prompt 工程<br/>与 Profile"]
end
subgraph Phase3["第三阶段：Web 服务基础设施（P1）"]
L12["12 FastAPI 与<br/>异步 Web 框架"]
L13["13 应用入口与<br/>环境前置校验"]
end
subgraph Phase4["第四阶段：治理与运维（P1-P2）"]
L14["14 知识库<br/>版本管理"]
L15["15 数据隔离<br/>与多租户"]
L16["16 文档入库<br/>与索引链路"]
L17["17 RAG 回归验收<br/>与入库质量"]
L18["18 测试与<br/>接口验收"]
L19["19 观测 Trace<br/>与生产化"]
L20["20 Docker<br/>交付深化"]
end
L01 --> L02 --> L03 --> L04 --> L045 --> L05 --> L06 --> L07 --> L08 --> L09 --> L10 --> L11 --> L12 --> L13 --> L14 --> L15 --> L16 --> L17 --> L18 --> L19 --> L20
style L03 fill:#FFFBEB,stroke:#D97706,stroke-width:2px
style L045 fill:#FEF3C7,stroke:#D97706,stroke-width:2px
style Phase1 fill:#EFF6FF,stroke:#3B82F6,stroke-width:2px
style Phase2 fill:#FEF2F2,stroke:#DC2626,stroke-width:2px
style Phase3 fill:#ECFDF5,stroke:#059669,stroke-width:2px
style Phase4 fill:#F5F3FF,stroke:#7C3AED,stroke-width:2px路线图的设计逻辑：先学习 RAG、LangChain 和 Milvus 基础，再在第二阶段实践单元中用 Vibe Coding 把 Dense + BM25 + Reranker + LLM 串起来；后续 05-11 再逐层拆解企业级意图、检索计划、改写、编排和 Prompt。20 章主体仍遵循"基础概念 → 框架基础 → 核心链路 → Web 基础设施 → 治理运维"的递进。
第二阶段实践单元（第 04 章之后 · 1 天）：先用结构化需求让 Codex 分析和规划，再分阶段完成文档入库、Milvus 2.5+ Dense HNSW + BM25 混合检索、BGE Reranker、LLM 生成、测试和 Docker 验收。它使用单一场景，暂不展开意图网关、Redis、版本治理、评测和 Trace。完成后，你能把前面学过的 Milvus 知识落实为一条可运行链路，并掌握 Vibe Coding 的基本工作方法。
第一阶段（基础概念 · 2 章）：01 和 02 先建立心智模型。01 先说明 Docker/Compose 运行底座，再进入环境部署，让你跑通项目、看到效果；02 深入理解 Embedding、向量检索、混合检索这些 RAG 最核心的概念。学完这两章，你至少知道 RAG 是什么、为什么需要它，以及本项目为什么用 Docker 管理依赖。
第二阶段（核心 RAG 链路与实践 · 9 章 + 1 个实践单元，P0）：这是学习内容的核心区。03 到 11 构成完整 RAG 问答数据流，实践单元负责连接知识和代码：LangChain 生态系统（03）→ Milvus 索引机制（04）→ Vibe Coding 实践 → 意图分类（05）→ 检索计划（06）→ 查询改写 + 变体（07）→ Milvus 混合检索（08）→ QAService 编排（09）→ Pipeline 主流程（10）→ Prompt 模板（11）。03 先打 LangChain 基础，04 说明 Milvus 底层操作，实践单元把混合检索和 Reranker 跑起来，后续内容再回到企业级实现逐层拆解。
离线构建在第二阶段怎么处理？ 第二阶段会把离线知识库构建作为“检索前置背景”轻量说明：Milvus 里的 FAQ、文档 chunk 和向量数据，是由离线脚本提前构建好的。第二阶段不展开
rebuild_kb_version.py、质量门禁、版本激活、增量入库等工程细节，完整实现统一放到第 16 章说明。设计意图：LangChain 放在 P0 最前面——先掌握模型调用、消息历史、Prompt、文档对象、切分器和 VectorStore 抽象，再在后续链路中看到它们被实际使用（"查询变体用了结构化输出""QAService 用了 stream()"），形成"先学后用"的正向循环。
复杂度控制：一期主链路不引入 Python 本地 BM25 或 LlamaIndex QueryEngine。FAQ 与文档召回统一进入 Milvus Hybrid Search；Redis 只做 query embedding 和检索候选缓存，并通过
cache_epoch绑定版本失效。RAGAS 只作为补充评测。这样可以先掌握一条完整企业 RAG 链路，再理解可选扩展。
第三阶段（Web 服务基础设施 · 2 章，P1）：12 深入 FastAPI 的 async/await 和 WebSocket——这是整个项目的"骨架"。13 深入 app.py 和 preflight check，理解项目为什么要求依赖完整后再启动。学完这阶段，你能理解项目的 Web 服务层和启动流程。
第四阶段（治理与运维 · 7 章，P1-P2）：14 到 20 覆盖了"让 RAG 系统能上线"所需的一切——知识库版本管理（14）、多租户数据隔离（15）、知识库离线构建链路（16）、RAG 回归验收与入库质量（17）、测试与接口验收（18）、LangSmith 观测、Trace 与生产化部署（19）、Docker 交付深化与排障（20）。14 → 15 → 16 建议按序学习（先理解版本和隔离，再看资料如何安全进入可检索知识库）。
第四阶段不要把每一章都理解成新的总论。它是一条治理链路的七个切面：14 定义版本发布边界，15 定义数据访问边界，16 把资料写入候选版本，17 决定候选版本质量是否过关，18 用测试保护代码和接口，19 用观测支撑线上运行，20 把第 1 章学过的 Docker 底座升级成可交付、可验收、可排障的部署闭环。
flowchart LR
L14["14 版本治理<br/>STAGED/ACTIVE/ARCHIVED<br/>active 指针/回滚"]
L15["15 数据隔离<br/>DataScope<br/>Milvus expr"]
L16["16 离线入库<br/>Loader/FAQ/Table/OCR<br/>Manifest/STAGED"]
L17["17 质量决策<br/>入库报告<br/>Evaluation/Gate/Bad Case"]
L18["18 自动化验收<br/>pytest/guardrails<br/>API/smoke"]
L19["19 生产观测<br/>Trace/耗时/部署<br/>事故排查"]
L20["20 Docker 交付深化<br/>Compose/镜像/挂载<br/>部署排障"]
L14 --> L16
L15 --> L16
L16 --> L17
L17 --> L18
L18 --> L19
L19 --> L20
L19 -. "线上问题沉淀回评测集" .-> L17
L17 -. "门禁通过才允许激活" .-> L14| 章节 | 本章只负责 | 不在本章重复展开 |
|---|---|---|
| 14 | 版本状态机、active 指针、激活、回滚、版本序号 | 文档加载、隔离表达式、质量算法、接口测试 |
| 15 | DataScope、租户/数据集/可见性/角色隔离、Milvus 过滤表达式 |
版本状态机、入库主流程、质量评测 |
| 16 | 离线入库主链路、Loader、FAQ/Table/OCR、Manifest、候选版本写入 | 质量指标算法、自动化测试体系、生产观测 |
| 17 | 入库质量报告、质量门禁、回归评测、Bad Case 沉淀 | 文档解析细节、API 接口测试、部署容量 |
| 18 | 单测、接口验收、保护性测试、Smoke Test | 入库链路设计、评测指标设计、Trace 诊断 |
| 19 | LangSmith Trace、阶段耗时、部署、容量评估、线上排查 | 版本/隔离/入库/评测的实现细节 |
| 20 | Docker 交付深化、镜像构建、模型挂载、容器命令、部署排障 | 第 1 章已经说明过的基础环境启动；Kubernetes、滚动发布、多副本自动扩缩容和灾备演练 |
P3 扩展方向：当前主链路不接入 GraphRAG、OCR/VLM 和 LlamaIndex 入库替代，避免干扰 RAG 基础链路。GraphRAG 可以作为独立关系推理能力，专门处理合同风险、跨境供应链、工程项目等强实体关系场景；OCR/VLM 用于复杂资料入库增强；LlamaIndex 只作为文档加载、transformations 和缓存的替代方案理解，不替代本项目的多版本治理、DataScope 和线上检索主链路。
学习路径：
完整学习主线为 01 → 19；实践单元紧接第 04 章，用于把前面学过的 Milvus 知识落实到可运行代码。
| 路径 | 章节 | 适合人群 |
|---|---|---|
| Milvus 后实践路径 | 01 → 02 → 03 → 04 → 实践单元 | 先学基础，再完成一条可运行的混合检索 RAG |
| 主链路路径 | 01 → 02 → 03 → 04 → 实践单元 → 05 → 06 → 07 → 08 → 09 → 10 → 11 | 首轮学习，先抓住 RAG 在线问答闭环（全 P0） |
| 框架深入路径 | 12 → 13 | 进阶学习，理解 FastAPI 和应用入口原理 |
| 工程化路径 | 14 → 15 → 16 → 17 → 18 | 进阶学习，补齐企业级工程能力 |
| 完整路径 | 01 → 04 → 实践单元 → 05 → 20 顺序学 | 有充足时间，希望全面掌握 RAG 工程 |
| 速览路径 | 先读内容总览表再挑薄弱章节精读 | 有经验的开发者 |
| 汇报路径 | 01 → 02 → 03 → 04 → 05 → 08 → 10 → 11 → 18 → 19 → 20 | 赶时间准备汇报，第 1 章先说明 Docker 环境底座，最后用生产部署、Docker 交付和容量评估收口 |
内容总览¶
| 章节 | 主题 | 优先级 | 核心收获 |
|---|---|---|---|
| 01 | 项目概述与 Docker 环境搭建 | P0 | 理解 RAG 基本概念、Docker/Compose 运行底座，完成环境搭建并跑通项目 |
| 02 | RAG 核心概念深入 | P0 | 掌握 Embedding、Dense/Sparse 检索、Reranker 原理 |
| 03 | LangChain 生态系统 | P0 | 掌握模型、消息、历史、结构化输出及离线组件的统一接口与项目边界 |
| 04 | Milvus 索引机制与基本操作 | P0 | 掌握向量库选型、索引、PyMilvus 操作、混合检索融合排序及 LangChain 封装边界 |
| 实践单元 | Vibe Coding 实践：简易混合检索 RAG | P0 | 用 AI 完成文档入库、Dense + BM25 混合检索、BGE Reranker、LLM 生成、测试和 Docker 验收 |
| 05 | 意图分类 | P0 | 理解规则候选、BERT 模型增强、决策网关仲裁和知识查询兜底 |
| 06 | 检索策略与动态计划 | P0 | 掌握 RetrievalPlan，理解不同问题用不同检索参数 |
| 07 | 查询改写与变体生成 | P0 | 理解追问改写和 query variants 生成机制 |
| 08 | Milvus 混合检索 | P0 | 将 Dense+BM25、融合配置、过滤表达式和 CrossEncoder 重排接入项目检索层 |
| 09 | QAService 核心编排 | P0 | 理解服务门面模式、事件生成器、HTTP 与 WS 分工 |
| 10 | RAG Pipeline 主流程 | P0 | 掌握 Stage 0-7 Pipeline、FAQ 快速路径、引用增强、流式事件协议 |
| 11 | Prompt 工程与 Profile 系统 | P0 | 理解 Prompt Profile、问题类别与模板映射、安全约束 |
| 12 | FastAPI 与异步 Web 框架 | P1 | 理解 async/await、WebSocket、FastAPI 路由设计 |
| 13 | 应用入口与环境前置校验 | P1 | 理解 preflight check 设计模式，读懂 app.py |
| 14 | 知识库多版本管理 | P1 | 掌握版本状态机、激活/回滚、版本对比 |
| 15 | 数据隔离与多租户 | P1 | 理解 tenant/dataset/visibility/role 四维隔离 |
| 16 | 文档入库与索引链路 | P1 | 掌握 8 场景全量初始化、知识库构建总链路、文档加载、FAQ 入库、资料治理边界 |
| 17 | RAG 回归验收与入库质量 | P1 | 理解入库质量、本地 Evaluation、Bad Case 沉淀和验收机制 |
| 18 | 测试与接口验收 | P1 | 理解测试金字塔、纯逻辑测试设计、验收测试 |
| 19 | LangSmith 观测、Trace 与生产化部署 | P2 | 掌握 LangSmith Trace、业务 metadata、阶段耗时诊断、生产部署和容量评估 |
| 20 | Docker 交付深化与排障 | P2 | 掌握镜像构建、模型挂载、全量初始化、跨平台验收和容器排障 |
各章详细内容¶
第二阶段实践¶
第二阶段实践：Vibe Coding 实践（简易混合检索 RAG）¶
- 内容：在第 04 章基础上，使用结构化需求、分阶段提示词、diff 检查、测试验收和报错修复，完成文档加载、切分、Dense + BM25 混合检索、BGE Reranker、LLM 生成和 Docker 运行
- 学完后：能让 Codex 先分析、再分阶段实现项目；能解释召回、精排和生成的边界；遇到问题时能提供完整上下文并完成验证
- 关键代码：
mini-rag/、mini-rag/qa_core/retrieval.py、mini-rag/qa_core/pipeline.py、mini-rag/prompts/vibe-coding-lab.md
第一阶段：基础概念¶
第 1 章：项目概述与 Docker 环境搭建¶
- 内容：什么是 RAG、RAG 系统的基本组成、向量和向量检索的直观理解、Docker/Compose 基础、8 个业务场景介绍、技术架构总览、环境搭建与验证
- 学完后：能启动项目，在页面上完成一次完整问答
- 关键代码：
docker-compose.yml、.env.compose/.env
第 2 章：RAG 核心概念深入¶
- 内容：Embedding 模型工作机制、向量相似度计算（余弦/欧几里得/内积）、BGE-M3 模型介绍、Dense 检索与 Sparse 检索对比、Reranker 原理、混合检索策略
- 学完后：理解为什么 RAG 需要混合检索 + 重排
- 前置知识：第 1 章（了解 RAG 基本概念即可）
第二阶段：核心 RAG 链路（P0）¶
第 3 章：LangChain 生态系统¶
- 内容：围绕在线问答和离线入库两条主线，理解 ChatModel、结构化输出、Message、SQLChatMessageHistory、Document、Loader、Splitter、VectorStore 的统一接口和职责边界；具体入库实现放在第 16 章
- 学完后：能解释 LangChain 在本项目中承担的是工程适配器角色，而不是替代完整 RAG 主流程
第 4 章：Milvus 索引机制与基本操作¶
- 内容：向量数据库选型、索引原理、FLAT/IVF/HNSW、PyMilvus 基本操作、Dense+BM25 原生混合搜索、WeightedRanker/RRFRanker，以及 langchain-milvus 与 PyMilvus 的职责边界
- 学完后：能操作 Milvus，并能解释索引与融合排序的选型依据
- 前置知识：第 2 章（HNSW 概念）、第 3 章（VectorStore 抽象）
第 5 章：意图分类¶
- 内容：6 种意图类型、路由与检索分层、规则候选 + BERT 模型增强 + 决策网关仲裁、知识查询兜底、source 自动推断、rule_score 与检索计划联动
- 学完后：理解意图如何驱动后续检索策略
- 关键代码：
qa_core/intent/classifier.py
第 6 章：检索策略与动态计划¶
- 内容：RetrievalPlan 数据结构、动态阈值设计、不同问题类别的参数分支、为什么不能所有问题用一套参数
- 学完后：理解检索参数是如何按问题类型动态生成的
- 关键代码：
qa_core/retrieval/strategy.py
第 7 章：查询改写与变体生成¶
- 内容：追问改写（代词消解）、query variants 生成（启发式+LLM）、多轮对话历史管理、历史摘要压缩
- 学完后：理解"审批呢"如何变成"入职审批流程需要多长时间"
- 关键代码：
qa_core/pipeline/rewrite.py、qa_core/pipeline/query_variants.py
第 8 章：Milvus 混合检索¶
- 内容：把第 2、4 章的检索原理落到
MilvusHybridStore：BM25BuiltInFunction、FAQ/Doc 分集合、Dense+Sparse 配置、过滤表达式、多查询合并和 CrossEncoder 重排 - 学完后：理解一次混合检索的完整链路
- 关键代码：
qa_core/retrieval/store.py、qa_core/retrieval/filters.py
第 9 章：QAService 核心编排¶
- 内容：服务门面模式、WebSocket stream 主链路、检索诊断半链路、事件生成器（start/status/token/end/error）、
asyncio.to_thread桥接 - 学完后：理解 QAService 如何编排整个 RAG 流程
- 关键代码：
qa_core/application/service.py、qa_core/api/chat.py
第 10 章：RAG Pipeline 主流程¶
- 内容：Stage 0-7 主流程（创建上下文 → 查询路由 → 检索准备 → FAQ 检索 → 文档检索 → 上下文构建 → LLM 生成/引用增强 → 保存历史/Trace）、FAQ exact route 复用机制、上下文筛选/去重/截断策略、答案引用增强、流式事件协议
- 学完后：能完整追踪一个用户问题从输入到流式返回的全过程
- 关键代码：
qa_core/pipeline/rag.py、qa_core/pipeline/steps.py、qa_core/pipeline/context.py
第 11 章：Prompt 工程与 Profile 系统¶
- 内容：System Prompt 编写原则（身份/边界/约束）、8 种 Prompt Profile、问题类别与模板映射、场景变量注入、高风险问题的安全约束
- 学完后：理解费用/合规/安全类问题的回答边界控制
- 关键代码：
qa_core/prompts/profiles.py、qa_core/prompts/selector.py
第三阶段：Web 服务基础设施（P1）¶
第 12 章：FastAPI 与异步 Web 框架¶
- 内容：Python async/await 机制、FastAPI 路由与依赖注入、WebSocket 通信原理
- 学完后：理解 FastAPI 如何支撑 WebSocket 在线问答主通道和 HTTP 辅助接口
- 关键代码：
app.py、qa_core/api/
第 13 章：应用入口与环境前置校验¶
- 内容：preflight check 设计模式、启动校验链（LLM/Milvus/MySQL/模型/场景配置/active KB 版本）、检索栈预热、为什么启动前必须保证依赖完整
- 学完后：理解 app.py 的每一行代码和启动流程
- 关键代码：
app.py、qa_core/config/preflight.py
第四阶段：治理与运维¶
第 14 章：知识库多版本管理¶
- 内容：版本状态机（STAGED→ACTIVE→ARCHIVED）、激活与回滚、版本对比、metadata 版本字段（kb_version/embedding_model_version/chunk_schema_version）
- 学完后：理解如何安全地更新知识库而不影响在线服务
- 关键代码：
qa_core/governance/kb_versions.py
第 15 章：数据隔离与多租户¶
- 内容：DataScope 四维隔离（tenant/dataset/visibility/role）、Milvus 表达式过滤、array_contains 角色过滤、场景配置全貌（scenario.toml → ScenarioDefinition → 既有场景维护）
- 学完后：理解同一套 collection 如何实现多租户数据隔离
- 关键代码：
qa_core/governance/data_scope.py
第 16 章：文档入库与索引链路¶
- 内容：离线入库 vs 在线问答的边界、8 场景全量初始化（
rebuild_scenarios.py）、单场景知识库构建（rebuild_kb_version.py）、Loader 注册表、文档标准化、父子块切分、CSV/Excel 表格行入库、表格练习与边界、FAQ CSV 入库、IndexManifest 增量机制、data_packs企业增强资料包与 dirty samples 治理边界 - 学完后：理解如何把 FAQ、文档和表格资料构建成带版本、带权限、可检索、可回滚的知识库
- 关键代码：
qa_core/indexing/
第 17 章：RAG 回归验收与入库质量¶
- 内容：三层保障体系（入库质量 → 本地 Evaluation → 质量检查）、评测指标（Recall@K/MRR/关键词覆盖/场景隔离率）、验收机制、Bad Case 沉淀
- 学完后：理解如何用数据证明 RAG 系统的效果
- 关键代码：
scripts/evaluate_core_chain.py、scripts/extract_bad_cases_from_report.py、scripts/check_*_gate.py
第 18 章：测试与接口验收¶
- 内容：测试金字塔（纯逻辑/API 保护/E2E）、意图识别测试、检索过滤测试、Prompt 选择测试、验收逻辑测试、pytest 用例的分层组织方式
- 学完后：理解 RAG 系统如何做分层测试
- 关键代码：
tests/
第 19 章：LangSmith 观测、Trace 与生产化部署¶
- 内容：LangSmith Trace、业务 metadata、trace 字段含义、阶段耗时诊断、Bad Case 沉淀与复盘、生产部署拓扑、并发容量估算、硬件选型、压测方式、监控告警
- 学完后：能通过 trace 定位"为什么这次答得不好"，也能回答生产环境怎么部署、怎么压测、怎么判断是否需要扩容
- 关键代码：
qa_core/observability/
第 20 章：Docker 交付深化与排障¶
- 内容：在第 1 章 Docker 基础之上，继续说明 Compose 服务拓扑、Dockerfile、
.env.compose、模型挂载、知识库初始化、API 启动、验收命令和常见排障 - 学完后：能把项目从源码交付到可运行容器环境，解释宿主机视角和容器视角的区别，并能定位常见部署问题
- 关键代码：
Dockerfile、docker-compose.yml、.env.compose.example、scripts/deploy/deploy_docker.ps1
附录¶
| 附录 | 主题 | 相关章节 |
|---|---|---|
| A | Pydantic 数据校验 | 第 3、4、8 章 |
| B | SHA256 稳定指纹 | 第 16 章（文档去重） |
| C | HNSW 索引算法 | 第 4、8 章（HNSW 理论深入） |
| D | CrossEncoder 重排器 | 第 2、6、8 章 |
| E | RecursiveCharacterTextSplitter 详解 | 第 16 章 |
| F | Embedding 模型深入 | 第 2 章（文本→向量的完整过程） |
| G | 文档切分策略（Parent-Child Chunking） | 第 16 章（切分策略设计 + 参数选择） |
| H | 项目工具类开发详解 | 第 13、14、16 章（跨模块基础设施） |