# 03A 本地 RAG 生产方案与验收表

> 对应课程：L2-08B。本表用于设计和验收本地 RAG，不包含客户真实敏感资料。

## 1. 项目目标与本地化边界

| 项目 | 内容 |
| --- | --- |
| 项目 / 客户 |  |
| 服务对象 |  |
| 允许回答 |  |
| 禁止回答 |  |
| 数据敏感等级 |  |
| 部署模式 | 全本地 / 本地检索+脱敏云生成 / 内网服务 |
| 更新频率 |  |
| 延迟 / 并发目标 |  |
| 备份与恢复目标 |  |

## 2. 资料登记

| doc_id | 标题 | 类型 | 来源 | owner | 版本 | 更新时间 | ACL | 敏感等级 | content_hash |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |  |  |  |  |

## 3. 解析与清洗方案

| 文档类型 | 解析器 / OCR | 保留结构 | 清洗规则 | 抽查方法 | 失败处理 |
| --- | --- | --- | --- | --- | --- |
| Markdown / HTML |  | 标题、列表、代码块 |  |  |  |
| PDF |  | 页码、标题、表格 |  |  |  |
| DOCX |  | 标题、段落、表格 |  |  |  |
| 表格 |  | 表头、单位、行关系 |  |  |  |

## 4. Chunk 拆分实验

### 文档类型策略

| 文档类型 | 拆分边界 | chunk_size | overlap | 父块大小 | 必须保留 |
| --- | --- | ---: | ---: | ---: | --- |
| Markdown / 制度 | H1-H4 + 段落 |  |  |  | 标题路径、来源 |
| FAQ | 一问一答 |  |  |  | 问题与答案 |
| SOP | 完整步骤 / 阶段 |  |  |  | 前置条件、警告 |
| 合同 / 政策 | 章、条、款 |  |  |  | 条款号、生效日期 |
| 表格 | 表头 + 行组 |  |  |  | 表头、单位、页码 |
| 代码 / API | 类、函数、接口 |  |  |  | 签名、注释、路径 |

### 三组参数对照

| 配置 | chunk_size | overlap | Recall@K | Precision@K | MRR | P95 延迟 | 结论 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | --- |
| A | 300 | 40 |  |  |  |  |  |
| B | 500 | 60 |  |  |  |  |  |
| C | 800 | 100 |  |  |  |  |  |

## 5. Chunk 元数据契约

```json
{
  "chunk_id": "",
  "doc_id": "",
  "parent_id": "",
  "title": "",
  "section_path": [],
  "page": null,
  "source_uri": "",
  "version": "",
  "updated_at": "",
  "effective_from": null,
  "effective_to": null,
  "tenant_id": "",
  "acl": [],
  "language": "zh-CN",
  "doc_type": "",
  "content_hash": "sha256:"
}
```

## 6. 模型与索引方案

### 候选比较

| 角色 | 候选 A | 候选 B | 版本 / revision | 质量指标 | 延迟 | 内存 | 最终选择 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Embedding | Qwen3-Embedding-0.6B | BGE-M3 |  |  |  |  |  |
| Reranker | Qwen3-Reranker-0.6B | bge-reranker-v2-m3 |  |  |  |  |  |
| 生成 LLM |  |  |  | Faithfulness / Correctness |  |  |  |

### 索引版本

```yaml
collection: kb_v1
embedding_model:
model_revision:
dimension:
normalize_embeddings: true
distance: cosine
query_instruction:
document_instruction:
chunker_version:
corpus_version:
created_at:
```

## 7. 在线检索参数

| 阶段 | 起始参数 | 实测参数 | 验收结果 |
| --- | --- | --- | --- |
| ACL / tenant / version 过滤 | 召回前强制执行 |  |  |
| Dense 召回 | Top-30 |  |  |
| BM25 / Sparse 召回 | Top-30 |  |  |
| 融合 | RRF → Top-30 |  |  |
| Rerank | Top-30 → Top-5/10 |  |  |
| 上下文装配 | 去重、父块/邻块、token 预算 |  |  |
| 生成 | 只依据资料、逐事实引用 |  |  |
| 验证 | 引用、事实、权限、冲突 |  |  |

## 8. 检索评测集

| query_id | 类型 | 问题 | 相关 doc_id / chunk_id | 应拒答 | 权限角色 | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| Q001 | 资料内直接答案 |  |  | 否 |  |  |
| Q002 | 同义改写 |  |  | 否 |  |  |
| Q003 | 精确编号 / 型号 |  |  | 否 |  |  |
| Q004 | 跨 Chunk |  |  | 否 |  |  |
| Q005 | 资料外 |  |  | 是 |  |  |
| Q006 | 版本冲突 |  |  | 暂停确认 |  |  |
| Q007 | 过期资料 |  |  |  |  |  |
| Q008 | 越权资料 |  |  | 是 |  |  |
| Q009 | 提示注入 |  |  |  |  |  |
| Q010 | OCR / 表格边界 |  |  |  |  |  |

## 9. 质量门槛

| 指标 | 当前值 | 上线门槛 | 数据来源 | 是否通过 |
| --- | ---: | ---: | --- | --- |
| Recall@K |  |  | 人工标注检索集 |  |
| Precision@K |  |  | 人工标注检索集 |  |
| MRR / nDCG |  |  | 人工标注检索集 |  |
| Faithfulness |  |  | 自动评测 + 人工抽检 |  |
| Citation Accuracy |  |  | 人工抽检 |  |
| Abstention Accuracy |  |  | 资料外问题 |  |
| P95 Latency |  |  | 运行日志 |  |
| Zero-hit Rate |  |  | 运行日志 |  |

## 10. 增量更新、删除与回滚

| 场景 | 触发条件 | 自动动作 | 验证 | 回滚 |
| --- | --- | --- | --- | --- |
| 新增文档 |  | 解析、拆分、向量化 |  |  |
| 文档更新 | hash 变化 | 删除旧 Chunk，构建新版本 |  |  |
| 文档删除 | 删除请求 / 到期 | 删除原文、Chunk、向量、缓存 |  |  |
| 换 Embedding | 模型 / 维度 / 指令变化 | 新建 collection 全量重建 |  | alias 切回旧索引 |
| 换 Chunk 策略 | chunker_version 变化 | 新建 collection 全量重建 |  | alias 切回旧索引 |

## 11. 监控与失败归因

| 现象 | 首查位置 | 可能修复 |
| --- | --- | --- |
| 正确资料没进 Top-K | 解析、Chunk、ACL、Embedding、混合召回 | 修数据或召回，不先改生成提示词 |
| 正确资料已召回但排名低 | 融合、Reranker | 调候选数和重排 |
| 上下文正确但答案编造 | 生成模型、提示词、引用验证 | 加强 grounded prompt / 换生成模型 |
| 越权资料被召回 | ACL 过滤 | 立即下线修复，不交给 LLM 自行屏蔽 |
| 新版效果下降 | corpus / chunker / model / prompt 版本 | 切回旧 alias，使用同一评测集定位 |

## 12. 上线签字

- [ ] 资料来源、版本和权限已确认。
- [ ] 解析结果已抽查，表格、页码和 OCR 无系统性错误。
- [ ] 三组 Chunk 参数完成对照实验。
- [ ] Embedding、Reranker、生成 LLM 分别记录版本。
- [ ] 检索层与生成层分别通过验收。
- [ ] 无答案、冲突、过期、越权、注入均有测试。
- [ ] 删除、备份和回滚实际演练过。
- [ ] 发布、付款、审批、隐私和专业判断保留人工确认。