本页目录
Lesson 09 — 毕业整合：kb-qa v3 + 全仓课程重编号
本课目标：全机制协同跑通硬任务，完成 v3 定稿与全仓收尾——kb-qa 从「只吃纯文本」升级为「多模态文档智能 v3」，全仓课程重编号为八大方向。
学完你能回答面试官那句：「你的知识库经历了几个版本？」——能跑的 RAG → 运维就绪 v2 → 多模态文档智能 v3。扫描件、表格、图表都能吃，引用回溯到页码和区域，每个机制的收益有评估数字，每个开关有降级路径。
1. 端到端验收：全机制协同
全开关打开，毒文档从上传到带页码引用回答四类题，全程可复现：
毒文档 company_briefing.pdf（6 页：纯文本/扫描/表格/图表/混排）
│
▼ POST /api/upload（或 cli ingest）
┌─────────────────────────────────────────────────────────────┐
│ ① 解析层（L01）：parse_pdf → Element(type, page, bbox) │
│ P1/P2/P6 → text | P3 → image(扫描) │
│ P4 → table | P5 → text + image(图表) │
│ │
│ ② 理解层（L02-L04）：按类型翻译 │
│ table → markdown（L02 pdfplumber） │
│ image(扫描) → OCR 文本（L03 RapidOCR，置信度路由） │
│ image(图表) → VLM 描述（L04 glm-4v-plus，缓存去重） │
│ │
│ ③ 索引层（L05）：描述索引入 Chroma │
│ metadata: element_type / page / bbox │
│ │
│ ④ 生成层（L05 路由）：按 element_type 消费 │
│ text → stream_answer | table → 结构化作答 │
│ image(图表命中) → answer_with_image 现场看图 │
│ │
│ ⑤ 溯源层（L06）：引用带页码+区域 │
│ 「briefing.pdf · P4·表格」+ 可选区域裁剪图 │
└─────────────────────────────────────────────────────────────┘
│
▼ 四类题问答（带页码引用）+ 语音入口可选（L07）
硬任务收益表定稿（对照 L00 基线）
| 配置 | text | table | scan | chart | 成本 |
|---|---|---|---|---|---|
| L00 基线（text-only） | 100% | 0% | 0% | 0% | ~0.001元 |
| kb-qa v3（全开） | 100% | 100% | 100% | 100% | ~0.076元 |
🎯 三类杀手题从 0% 爬到 100%，纯文本保持 100% 防退化。 唯一成本是图表 VLM 描述（~0.075 元/图），把 chart 题从 0 拉到 100——这笔钱值得。详见 L08 收益表。
2. kb-qa v3 五层架构
┌─────────────────────────────────────────────────────────────┐
│ 多模态文档智能系统 v3（kb-qa） │
├─────────────────────────────────────────────────────────────┤
│ ⑤ 溯源层 引用 文档名+页码+区域(bbox)，可回原图核对 │ ← L06
│ ▲ Citation 三级：text / page / region(裁剪图) │
│ ④ 生成层 按 element_type 路由消费 │ ← L04,L05
│ ▲ image→现场看图 / table→结构化 / text→直答 │
│ ③ 索引层 描述索引入统一 Chroma，metadata 带类型 │ ← L05
│ ▲ 统一库 + element_type 路由 │
│ ② 理解层 图表→VLM 描述 / 扫描→OCR / 表格→结构化 │ ← L02-L04
│ ▲ 成本-精度分类路由（本地优先，VLM 按需） │
│ ① 解析层 PDF→Element(type, page, bbox) 流 │ ← L01,L02
│ │ 版面感知分类（扫描/表格/图文/纯文本） │
│ ▼ │
│ 原始文档（扫描件/表格/图表/纯文本） │
│ │
│ 入口扩展：语音（L07，enable_voice）ASR→主链路→TTS │
└─────────────────────────────────────────────────────────────┘
每个开关的默认值与降级路径
| 开关 | 默认 | 开启后 | 降级路径（关掉时） |
|---|---|---|---|
enable_multimodal_ingest |
off | PDF 走版面感知解析 | 只吃 md/txt（现状） |
ocr_engine |
off | 扫描页 OCR 填充 | 扫描页抽空（现状） |
table_format |
markdown | 表格 markdown 进上下文 | —（不影响开关） |
enable_image_caption |
off | 图表 VLM 描述入库 | 图表元素不入库 |
vision_model |
glm-4v-plus | 看图模型 | — |
enable_voice |
off | 挂 /api/ask_voice | 端点 404 |
🎯 所有开关默认关闭，任一关掉回退纯文本行为。 这是向后兼容的硬约束——79 个原始测试始终绿，多模态是「只加不减」的增量升级。
3. 全仓课程重编号（本课定位要求）
本课在全仓课程体系中插入为「课程六」，排在 ops-lessons（课程五）之后、frontier-lessons 之前：
| 编号 | 课程 | 课次 | 定位 |
|---|---|---|---|
| 课程一 | RAG 手写 | 9 | 收敛知识 |
| 课程二 | Agent 手写 | 9 | 收敛知识 |
| 课程三 | 框架进阶 | 9 | 收敛知识 |
| 课程四 | 工作流编排 | 9 | 收敛知识 |
| 课程五 | LLMOps | 13 | 收敛知识 |
| 课程六 | 多模态文档智能 | 10 | 收敛知识（本课） |
| 课程七 | 智能体前沿 | 13 | 前沿（原课程六） |
| 课程八 | GUI Agent | 13 | 前沿（原课程七） |
理由：本课是收敛的工程知识（文档解析/OCR/表格处理业界有成熟做法），主题弧线上属于「收敛知识 1–6 → 前沿双课 7–8」；且它落地 kb-qa v3，让 kb-qa 演进线（课 1 建 → 课 5 运维 v2 → 课 6 多模态 v3）连续。
重编号改动清单（已完成 + grep 核对清零）
| 文件 | 改动 |
|---|---|
根 README.md |
七大方向→八大、课程总览表插入本课为课程六、frontier→七、gui→八、学习路径句、目录树加 doc-intelligence-lessons/、kb-qa 作品行 v2→v3、新增本课程逐课介绍章节 |
根 README.en.md |
同步以上全部（Course 6/7/8 重排 + 本课程英文章节） |
frontier-lessons 2 个 README |
「前五门课」→「前六门课」 |
gui-agent-lessons 5 个 README |
「前六门课/第六门课/课程七」相应顺延为「前七门/第七门/课程八」 |
✅ 完成后全仓 grep 核对清零：
课程六|课程七|课程八|前五门|前六门|前七门|第六门|第七门|Course 6|Course 7|Course 8逐个确认指向正确，无残留旧编号。
4. kb-qa 的三个版本演进
v1（rag-lessons） v2（ops-lessons） v3（doc-intelligence）
能跑的 RAG 运维就绪 多模态文档智能
───────────── ───────────── ─────────────
embedding+检索 + 结构化日志/追踪 + 版面感知解析
切块+混合检索 + 线上评估闭环 + 表格结构化
rerank+防幻觉 + key 鉴权限流 + 置信度 OCR
ragas 评估 + 注入攻防守护栏 + VLM 图表理解
+ MCP Server + 多模态检索
+ 语义缓存/压测 + 页码+区域引用
+ 语音入口
79 测试 79 测试（不伤老能力） 143 测试（+64 新增）
🎯 每个版本都是「只加不减」：v2 不伤 v1 的能力、v3 不伤 v2 的能力。这靠「所有新机制默认关闭 + 向后兼容测试」保证。
5. 毕业后的能力对照
| 面试官会问 | 学完后你能指着代码说 |
|---|---|
| 扫描件怎么处理？ | 置信度路由：本地 RapidOCR 打头、低置信度页升级 glm-4v 直读（L03） |
| 表格怎么进 RAG？ | 版面感知抽取 + markdown/HTML 对照实验 + 整表成块表头冗余（L01-L02） |
| 图表数字能问吗？ | 两段式：VLM 描述做索引（缓存去重）+ 命中后现场看图（L04-L05） |
| 多模态引用怎么防幻觉？ | 页码+区域引用，可回溯原图；数字给不出出处就拒答（L06） |
| 做过语音入口吗？ | ASR→RAG→TTS 全链 + 延迟拆解（L07） |
| 升级收益怎么证明？ | 逐机制收益表 + 纯文本回归 + 入库成本列（L08-L09） |
| ragas 能评多模态吗？ | 能评「答案忠于描述」，评不了「描述忠于原图」——盲区和兜底都讲得清（L08） |
🎯 面试话术（终极版）
「我的知识库经历了三个版本：能跑的 RAG → 运维就绪 v2 → 多模态文档智能 v3。扫描件用置信度路由（本地 OCR 打头、低置信度升级 VLM），表格用版面感知抽取 + markdown 表示（对照实验裁决），图表用 VLM 两段式（描述做索引 + 现场看图）。引用回溯到页码和区域，数字给不出出处就拒答。每个机制的收益有评估数字（三类杀手题从 0% 到 100%，纯文本防退化 100%），每个开关有降级路径（默认全关，137 个测试始终绿）。多模态不是赶时髦，是 L00 量化的真实失败逼出来的。」
本课产出（无代码，纯整合文档 + 全仓重编号）
| 产出 | 内容 |
|---|---|
| 端到端验收 | 全开关毒文档问答 + 收益表定稿（对照 L00 基线） |
| kb-qa v3 架构 | 五层架构图 + 每个开关的默认值与降级路径 |
| 全仓重编号 | 根 README（中英）+ frontier/gui 课内措辞顺延 + grep 清零 |
.gitignore |
多模态产物忽略（vision_cache/clips/voice_samples/chart*.png） |
🎉 恭喜！完成本课，doc-intelligence-lessons 全 10 课收官。 kb-qa 从「只吃纯文本」升级为「多模态文档智能 v3」——扫描件、表格、图表都能吃，引用可回溯，每个机制有收益数字。