> ## Documentation Index
> Fetch the complete documentation index at: https://vectorpeak.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# RAG

> 整理 RAG 技术体系、工程实践和课程讲义内容

# RAG

<Badge icon="clock" color="green">Written: 2026.06</Badge>
欢迎！这是一套基于 **LangChain + Milvus Hybrid Search** 构建的 **KnowForge RAG Platform** 19 讲系统课程。

> 🎬 **快速入门**：先看 [RAG Pipeline 执行流程动画演示](/RAG/demos/pipeline-demo)，5 分钟建立对整个系统执行流程的直观认识。

***

## 1. 前言：如何高效学习这个项目

这个项目已经接近企业级 RAG 教学项目的完整度。如果第一次学习时把所有模块都当成同等重要，会很容易迷失。**正确方式是先抓住"能跑通一次高质量问答"的主链路，再逐步补治理、评测、多场景和复杂资料能力。**

### 1.1 核心原则

第一遍学习只回答一个问题：

> 用户问一个业务问题，系统如何找到正确资料，并流式生成一个有引用、可追溯的答案？

能把这条链路讲清楚，就已经掌握了项目的主干。其他内容是为了让系统更像企业项目、更适合面试表达，但不是第一遍必须全部吃透。

### 1.2 四层学习优先级

| 层级            | 定位                                                         | 是否必须 | 学习目标                                |
| ------------- | ---------------------------------------------------------- | ---- | ----------------------------------- |
| **P0 主链路**    | 在线问答闭环                                                     | 必须掌握 | 能解释一次请求从页面到 RAG Pipeline 再到流式返回的全过程 |
| **P1 核心工程能力** | 检索质量、Prompt、入库、版本、评测                                       | 建议掌握 | 能说明为什么答案可靠、资料如何更新、如何防止质量退化          |
| **P2 企业化增强**  | 多租户隔离、多场景、LangSmith Trace/Evaluation、领域指标、生产部署、容量评估、企业资料治理 | 面试加分 | 能把项目讲成企业可落地方案                       |
| **P3 扩展能力**   | OCR/VLM、表格复杂治理、Agent 化编排、GraphRAG Agent                    | 了解即可 | 知道边界和升级路线，不要求第一期完全掌握                |

> **LangSmith 学习提示**：Trace 用来观察一次 RAG 请求内部发生了什么，Evaluation 用来判断回答效果好不好。首页只建立概念，详细实现和项目落地点放在 [第 17 讲：RAG 回归验收与入库质量](/RAG/advanced/rag-evaluation) 和 [第 19 讲：LangSmith 观测、Trace 与生产化部署](/RAG/production/observability-tracing)。

### 1.3 P0 主链路一览

| 模块             | 对应代码                            | 核心概念                     |
| -------------- | ------------------------------- | ------------------------ |
| 意图识别           | `qa_core/intent/classifier.py`  | 决定是否检索、如何检索、用什么 Prompt   |
| 检索策略           | `qa_core/retrieval/strategy.py` | 不同问题动态调整 top\_k 和阈值      |
| 查询改写           | `qa_core/pipeline/rewrite.py`   | 补全追问、生成多路检索变体            |
| Milvus 混合检索    | `qa_core/retrieval/store.py`    | Dense + BM25 Sparse 混合召回 |
| 上下文构建          | `qa_core/pipeline/context.py`   | 控制哪些证据进入 LLM，避免噪声        |
| Prompt Profile | `qa_core/prompts/`              | 不同问题类别用不同回答口径            |
| 流式生成 + 引用      | `qa_core/pipeline/rag.py`       | WebSocket 流式输出 + 来源标注    |

### 1.4 P0 最低验收标准

1. 能画出"页面 → API → QAService → Pipeline → 检索 → LLM → 流式返回"的流程
2. 能解释为什么先做意图识别，再做检索计划
3. 能解释 Dense、Sparse、Reranker 在一次检索中的作用
4. 能解释为什么答案必须带来源引用

### 1.5 推荐学习节奏

| 阶段       | 时长    | 内容                                                | 对应讲次      |
| -------- | ----- | ------------------------------------------------- | --------- |
| **快速体验** | 1 天   | 启动项目，提问看流式输出，理解 RAG vs ChatGPT 区别                 | 第 1-2 讲   |
| **主链路**  | 3-5 天 | P0 全部内容：LangChain→意图→检索→改写→Milvus→Pipeline→Prompt | 第 3-10 讲  |
| **工程化**  | 2-3 天 | 框架原理、入库、版本管理、数据隔离、评测、测试                           | 第 12-18 讲 |
| **面试拔高** | 1-2 天 | 多场景复用、LangSmith 诊断、Bad Case 沉淀、生产部署、容量评估、二期规划     | 第 19 讲    |

### 1.6 遍可以暂时跳过的内容

* 企业 overlay、dirty samples 和复杂 OCR / VLM 细节
* 复杂 Excel 语义还原
* 所有 scripts 脚本的逐行解释
* 所有 8 个业务场景的完整资料细节
* Mermaid 架构图里的每个辅助节点
* 历史报告复盘的实现细节
* 二期 Agent Router、LangGraph、A2A、GraphRAG Agent 设计细节
* 状态页前端样式和非核心 UI 交互

第一遍只需要知道它们存在，以及它们服务于哪个工程目标。

### 1.7 最小闭环作业

完成下面 **5 件事**，就说明已经掌握一期主线：

1. 启动项目并完成一次流式问答
2. 解释该问题的意图分类结果
3. 解释该问题的检索计划为什么这样设置
4. 找到至少一条引用来源，并说明它是怎么从 Milvus 召回来的
5. 修改一份文档或 FAQ，重新入库并让新版本生效

### 1.8 代码阅读路线

如果要读代码，按这条线走——不要跳，不要从中间开始：

```text theme={null}
app.py
  → qa_core/api/chat.py          (WebSocket 流式事件 + HTTP 诊断/历史/反馈)
  → qa_core/application/service.py (QAService 编排层)
  → qa_core/pipeline/rag.py        (RAG 主流程)
  → qa_core/pipeline/steps.py      (意图识别、边界判断、上下文构建)
  → qa_core/pipeline/retrieval_steps.py (FAQ 检索、文档检索)
  → qa_core/retrieval/             (Milvus Hybrid Search、过滤、重排)
  → qa_core/prompts/               (Prompt Profile 路由)
  → qa_core/indexing/              (文档加载、切分、入库)
```

### 1.9 面试表达主线

面试时不要从"项目有很多功能"开始讲，而应按主次讲：

> 这个项目的核心是一套企业级 RAG 问答主链路。
> 在线侧通过 WebSocket 实现统一流式问答；
> 检索侧通过意图识别、动态检索计划、查询改写、Milvus Dense+Sparse 混合检索和 Reranker 提高召回质量；
> 生成侧通过 Prompt Profile、引用增强和上下文筛选保证答案可控；
> 工程侧通过知识库版本、数据隔离、入库质量检查、领域评测指标和 LangSmith Trace/Evaluation 保证系统可维护、可回滚、可诊断。
> OCR/VLM、GraphRAG、LangGraph Agent 属于后续扩展方向，不混入一期主链路。

### 1.10 二期扩展方向：Agent 化编排

一期目标是先把企业级 RAG 平台做可靠，重点解决检索、重排、Prompt、版本、隔离、评测和观测。二期可以在这个基础上引入 Agent 化编排：将当前 RAG Pipeline 封装为 **RAG Agent**，再新增 **GraphRAG Agent**、SQL Agent、Workflow Agent 等专用能力，由 Router/Planner 统一调度。

其中 GraphRAG Agent 不作为全平台默认检索方式，而是作为“跨文档实体关系推理”能力独立存在。它适合合同风险、跨境供应链、工程项目等强实体关系场景，用来回答“风险如何传导”“实体之间有什么关联”“某个项目会影响哪些节点”这类问题。

***

## 2. 快速导航

* [课程大纲与学习路线](/RAG/advanced/rag-optimization) — 19 讲整体结构和推荐学习顺序
* [第 1 讲：项目概述与环境搭建](/RAG/foundations/project-overview) — 从这里开始
* [技术附录](/RAG/appendix/pydantic) — 专题深度解析
* [🎬 流程动画演示](/RAG/demos/pipeline-demo) — 5 分钟建立系统整体认知
* [📊 业务流程图](/RAG/demos/business-flow) — 在线问答、离线入库、系统全景、章节跟敲路线图

## 3. 课程结构

| 阶段   | 讲次    | 内容                                                            | 优先级        |
| ---- | ----- | ------------------------------------------------------------- | ---------- |
| 第一阶段 | 01-02 | 基础概念：RAG 原理、向量检索、Embedding                                    | P0         |
| 第二阶段 | 03-11 | 核心 RAG 链路：LangChain→Milvus索引→意图→检索→改写→混合检索→编排→Pipeline→Prompt | **P0(核心)** |
| 第三阶段 | 12-13 | Web 服务基础设施：FastAPI、Preflight                                  | P1         |
| 第四阶段 | 14-19 | 治理与运维：版本管理、数据隔离、知识库离线构建、评测、测试、追踪                              | P1-P2      |

### 3.1 讲详细优先级

| 讲次 | 主题                        | 优先级 | 第一遍学习要求                                           |
| -- | ------------------------- | --- | ------------------------------------------------- |
| 01 | 项目概述与环境搭建                 | P0  | 必学，先跑通系统                                          |
| 02 | RAG 核心概念                  | P0  | 必学，理解 Dense/Sparse/Reranker                       |
| 03 | LangChain 生态              | P0  | 必学，RAG 的"语言基础" — Runnable 协议、ChatModel 调用、LCEL 组合 |
| 04 | Milvus 索引机制与基本操作          | P0  | 必学，理解 pymilvus 操作和索引选型                            |
| 05 | 意图分类                      | P0  | 必学，后续策略都依赖它                                       |
| 06 | 检索策略                      | P0  | 必学，理解动态参数                                         |
| 07 | 查询改写与变体                   | P0  | 必学，追问补全和多路检索                                      |
| 08 | Milvus 混合检索               | P0  | 必学，RAG 召回核心                                       |
| 09 | QAService 编排              | P0  | 必学，理解服务层如何串联                                      |
| 10 | RAG Pipeline              | P0  | 必学，全项目主流程                                         |
| 11 | Prompt Profile            | P0  | 必学，控制答案结构和业务边界                                    |
| 12 | FastAPI 与异步               | P1  | 理解 async/await、WebSocket，RAG 的"骨架"                |
| 13 | 应用入口与前置校验                 | P1  | 理解为什么环境必须完整                                       |
| 14 | 知识库版本                     | P1  | 建议掌握，体现工程可靠性                                      |
| 15 | 数据隔离                      | P1  | 建议掌握，企业项目必问                                       |
| 16 | 文档入库                      | P1  | 建议掌握，解释知识如何进入系统                                   |
| 17 | RAG 回归验收与入库质量             | P1  | 建议掌握，证明效果不是拍脑袋                                    |
| 18 | 测试与接口验收                   | P1  | 先掌握核心测试思路                                         |
| 19 | LangSmith 观测、Trace 与生产化部署 | P2  | 第二遍学习，面试加分；能讲生产部署、容量评估和监控                         |

## 4. 技术栈

| 层级        | 技术                                |
| --------- | --------------------------------- |
| API 框架    | FastAPI + WebSocket               |
| RAG 编排    | LangChain                         |
| 向量数据库     | Milvus 2.5 Hybrid Search          |
| Embedding | BGE-M3 (本地部署)                     |
| Reranker  | BGE Reranker Large (CrossEncoder) |
| LLM       | DashScope (OpenAI 兼容)             |
| 会话存储      | MySQL                             |