RAG 与 Agent¶

RAG 解决“回答时需要访问外部知识”，Agent 解决“需要多步使用工具完成目标”。二者都不是给模型无限上下文或无限权限。

RAG 生产链路¶

数据源
  -> 解析与结构恢复
  -> 权限/版本/来源元数据
  -> 切分与索引
  -> 查询理解
  -> 关键词 + 向量混合检索
  -> 重排与去重
  -> 上下文组装
  -> 带引用生成
  -> 检索评测 + 回答评测

数据准备¶

保留标题、章节、表格、代码、图片说明和页码关系。
每个 chunk 带文档 ID、版本、权限、更新时间和原始位置。
语义单元优先，固定字符数只是兜底。
为版本替换和删除设计可追踪的索引更新流程。

检索技巧¶

同时保留 BM25/关键词与向量召回，专有名词、编号和错误码常依赖精确匹配。
召回阶段追求覆盖，重排阶段控制最终精度。
对重复片段和同一父章节做去重或合并。
Query rewrite 必须保留实体、版本、时间和否定条件。
TopK 不是越大越好。无关上下文会增加成本并稀释证据。

上下文组装¶

每段材料应清楚标记来源、标题、位置和权限。告诉模型材料可能不完整或冲突，并要求：

只回答材料支持的事实。
区分事实、推断和缺失信息。
引用能够直接支持该句的片段。
冲突时展示冲突，不自行混合成新结论。

引用存在不代表引用正确，需要单独评测 citation correctness。

RAG 错误定位¶

答案错
  -> 关键证据是否在语料库？ 否：数据覆盖问题
  -> 是否被召回？ 否：查询/索引/召回问题
  -> 是否进入最终上下文？ 否：重排/TopK/去重问题
  -> 上下文是否包含冲突？ 是：版本与来源治理问题
  -> 模型是否正确使用证据？ 否：生成/提示/模型问题

必须把检索质量和回答质量分开，否则团队会用换模型掩盖数据问题。

Agent 的最小结构¶

Goal
  -> Planner/Policy
  -> Tool selection
  -> Permission check
  -> Execute
  -> Observe
  -> Stop / Ask / Continue

工具设计¶

工具名和描述明确，参数使用严格 schema。
返回结构化状态、结果、错误类型和可重试性。
每个写操作支持幂等键、dry run 或 preview。
不向模型暴露不需要的字段、权限和通用执行器。
工具结果是外部数据，不自动提升为高优先级指令。

控制循环¶

设置最大步数、最大 token、总超时和总成本。
重复同类失败后停止或换策略，不无限反思。
高风险动作展示具体参数，让人确认。
记录每一步输入、工具、结果和终止原因。

先工作流，后自治 Agent¶

固定流程能覆盖时，优先用确定性编排：分类 -> 检索 -> 生成 -> 审批 -> 写回。只有步骤无法预先确定，且模型选择工具确实提升结果时，才增加 Agent 自主性。

评测¶

RAG 至少测：文档覆盖、Recall@K、重排后证据覆盖、无关上下文比例、引用正确性、回答完整性。

Agent 至少测：任务完成率、无效步骤、工具选择、参数正确性、越权动作、恢复能力、每成功任务成本和人工接管率。

一个切分实例¶

处理产品手册时，不要把标题、适用版本和命令拆开：

差的 chunk："使用 --mode fast 启动。"

好的 chunk：
文档：Deployment Guide 5.3
章节：离线批处理 / Linux
适用版本：5.3.0-5.3.2
正文：使用 --mode fast 启动；Windows 不支持该选项。
来源位置：page 47
权限：team=platform

好的 chunk 能独立判断适用范围，也保留回到原文的锚点。表格和代码块应优先整体保留，过长时建立父子结构而不是任意截断。

检索实验矩阵¶

实验	召回	重排	最终上下文	要回答的问题
A	BM25 Top20	无	Top10	精确错误码是否更好
B	向量 Top20	无	Top10	语义改写是否更好
C	混合 Top40	reranker	Top10	覆盖提升是否抵消时延
D	混合 + query rewrite	reranker	Top10	改写是否丢失版本/否定词
E	D + 父章节扩展	reranker	token 预算内	跨段证据是否完整

分别报告“关键证据进入召回”“关键证据进入最终上下文”和“回答使用证据”。只看最终回答分数无法判断应该改哪一层。

工具契约示例¶

{
  "name": "create_change_request",
  "description": "创建变更草稿，不会执行变更",
  "input_schema": {
    "type": "object",
    "properties": {
      "service": {"type": "string", "enum": ["search", "gateway"]},
      "summary": {"type": "string", "maxLength": 240},
      "idempotency_key": {"type": "string"}
    },
    "required": ["service", "summary", "idempotency_key"],
    "additionalProperties": false
  }
}

工具命名直接说明副作用。“提交草稿”和“执行生产变更”必须是不同工具，具有不同权限和审批路径。

Agent 故障注入集¶

至少覆盖以下 12 种情况：参数缺失、参数类型错误、权限拒绝、限流、超时、服务端错误、成功但空结果、部分成功、未知状态、重复请求、工具结果包含恶意指令、多个工具返回冲突事实。

对每种情况定义预期动作：重试、修改参数、换工具、询问用户、降级或停止。没有停止条件的 Agent 在故障中会把一次小错误放大为成本或安全事故。

权限设计¶

风险级别	例子	默认策略
只读低风险	搜索公开资料、查询状态	自动执行，仍记录审计
只读敏感	查询客户、财务或内部文档	用户身份透传，检索前鉴权
可逆写入	创建草稿、添加标签	展示 preview，幂等，可撤销
高风险写入	发款、删数据、生产变更	强审批、范围上限、双人或策略引擎确认

架构原则：模型提出意图，确定性系统决定权限。任何外部文本都只能作为数据进入，不能因为出现在检索结果或工具返回中就获得系统指令级别。