Agent 检索设计:数据组织与分块
Agent 的检索范围比知识库问答更广。历史对话里的被接受方案、业务系统的实时状态、工具返回的中间产物,以及长期保存的技术文档,都可能是下一步需要的证据。设计检索机制,首先要明确要做什么判断、缺少什么信息、由哪个来源提供,再决定是否使用向量检索。
本文讨论查询规划与数据组织。多路融合、迭代预算和缓存放在Agent 检索优化:召回质量、预算与缓存中展开,避免把入库与在线优化混成一条过长的流程。
把 RAG 的索引与查询分开设计
知识库问答是检索设计的一种具体应用。RAG 在回答前取得外部证据,再把证据交给模型;它可以用全文搜索、结构化查询或向量检索,并不要求必须引入向量数据库。普通问答可先检索再生成,Agent 也可能在多次调用之间继续检索。
索引:文档 → 解析与清洗 → 分块和元数据 → 建立检索索引 → 校验并切换版本
查询:问题与身份 → 改写/路由 → 授权范围内召回 → 去重与重排
→ 组装带来源的证据 → 生成 → 检查断言与引用
例如教学制度写着“住宿上限 800 元”,外部资料能为金额提供依据,但“上海属于此制度的一线城市范围”仍需政策自己的城市定义,不能仅凭模型常识补全。检索相似度高也不能证明某个规则适用于当前对象。
| 需求 | 可考虑的起点 | 要评估的代价 |
|---|---|---|
| 少量完整材料,单次或低频分析 | 直接放入长上下文 | 输入成本、首字延迟、关键证据遗漏 |
| 经常更新、需要引用与访问控制的外部事实 | RAG | 索引治理、召回质量、权限与引用链 |
| 稳定的任务行为、输出风格或领域能力 | 微调 | 训练数据、评估、维护和遗忘风险 |
三者可以结合。微调不只改变格式,也可能改变任务能力和事实行为,但不能替代可更新、可撤权的事实库;长上下文能否容纳与有效使用材料,也必须在真实任务上测试。知识更新的耗时、每次检索的延迟都取决于规模和实现,不能把“几分钟”或“几十毫秒”当成承诺。
从待做判断反推信息缺口
“系统为什么变慢”并不是一个可以直接执行的查询。至少需要明确对象、环境和时间,再把宽泛问题转换为待验证判断,例如“本次发布是否引入了导致接口长尾延迟增加的变更”。接着列出完成判断所需证据,扣除已经可靠获得的部分。
用户目标:定位订单创建接口变慢的原因
已知:生产环境;异常出现在本次发布之后
待验证:耗时发生在哪一段;哪些配置改变;依赖是否同步异常
禁止推断:时间接近不等于已经证明发布导致故障
查询输出:带时间、对象、版本和来源的证据
这是教学场景,不代表实际线上故障。发布记录用于确认“改了什么”,Trace 和指标用于确认“慢在哪里”,历史复盘用于生成排查假设。相似案例可以提供方向,但不能证明当前故障原因。
没有影响当前判断的信息,可以暂缓查询;缺少会改变结论的必要证据,则不能因为已有答案看起来合理就跳过。每条查询最好绑定一个 missing_evidence 条目,方便解释查询为何发生、结果是否补齐缺口。
用数据源目录完成路由
只有一个权威来源的信息,优先通过固定业务 Action 获取。例如订单状态由订单服务查询,没必要让模型在几十个工具中猜。证据分散在日志、配置和文档中时,再使用可调整的路由策略。
数据源目录可记录用途、支持字段、查询方式、时间覆盖、更新延迟、权限与不适用场景。下面是教学结构:
{
"source_id": "deployment_records",
"purpose": "查询某服务已发生的发布及版本变化",
"not_for": ["判断发布是否导致性能下降"],
"required_filters": ["service", "environment", "time_range"],
"query_modes": ["structured"],
"freshness": "以发布平台记录的更新时间为准",
"permission": "deployment:read",
"result_fields": ["release_id", "version", "changes", "released_at"]
}
目录规模小,可以直接加载候选说明;规模大,再按业务域和权限筛选目录,必要时先检索目录再查数据。目录路由失败时,尝试不同候选源,而不是重复同一路径。新的 Observation 可以引出新的查询空间,但只能在已授权范围内扩展。
权限检查必须由服务端执行,不能依靠模型记住租户限制。源目录、数据查询、父节点展开及原文读取都需要一致的权限边界;未经授权的数据不应先进入模型再让模型“忽略”。
查询改写保留边界,拆解补齐缺口
查询改写需要补全指代、统一术语、抽取实体,并把环境、时间和版本转为可执行过滤条件。它不是替用户增加事实。例如“刚才那个错误”可以从当前状态定位到已出现的错误码;无法确认错误码时,则应保留歧义,不能生成一个听起来合理的代号。
| 改写动作 | 合格结果 | 应避免的变化 |
|---|---|---|
| 指代与实体消解 | 绑定到已确认的服务或文档 ID | 根据相似名称猜对象 |
| 保留约束 | 生产环境、指定时间、当前租户独立成字段 | 在自然语言改写中丢掉限制 |
| 术语统一 | 使用数据源实际字段和领域别名 | 造出不存在的索引字段 |
| 删除噪声 | 去掉寒暄、重复背景 | 删除否定、单位和例外条件 |
| 可执行性检查 | 检查参数类型、权限及来源支持范围 | 把不可执行 Query 直接交给底层 |
复杂查询可以用 5W1H、时间线或因果链拆解。5W1H 中的对象、参与者、时间、位置、原因和过程是候选维度,不必每次凑齐六个子问题。查询当前状态可能只需对象与身份;排障才可能需要发布前后的过程与相反证据。
当问题表达很短、文档却以解释性语言写作时,可以试验 HyDE:先生成假想文档,再用其向量召回真实材料。假想文档只作为查询中间产物,不能进入事实证据集合。 它可能带入错误实体或前提,因此需要与原查询保留的硬条件一起使用,并对比直接查询基线。HyDE 原始论文描述的是这种从假想文档定位真实文档的检索方式;多段假想答案、后续追问等属于可以实验的扩展,不保证更优。
Embedding 空间与向量索引的工程约束
Embedding 把文本编码成定长向量,用于衡量检索相关性;它不是生成模型对事实正确性的评分。保存正文及来源引用,才能在命中后取回真正用于回答的证据。文本和向量可以共存于一库,也可以通过稳定 ID 分开保存。
余弦相似度 = (A · B) / (||A|| × ||B||)
P = [1, 1],Q = [2, 2],R = [1, 0]
cos(P, Q) = 1
cos(P, R) = 1 / √2 ≈ 0.707
这组二维数值只说明计算方法,不代表真实文本向量。余弦比较方向,点积同时受模长影响,欧氏距离衡量距离;采用哪种由模型训练方式、是否归一化和索引实现决定。距离通常越小越近,相关性分数通常越大越好,接口里的 score 不能未经核对就共用阈值。
索引契约应记录模型标识及修订、向量维度、输入预处理、查询/文档前缀、归一化方式和距离度量。查询与文档必须使用兼容的编码空间;对于非对称检索模型,两侧可能需要不同任务前缀或编码接口,不能误解为完全相同的输入处理。超出输入限制时,有的实现报错,有的截断,因此要显式检查长度并观测截断。
只计算 float32 向量本体,500 万条 × 1536 维 × 4 字节约为 30.72 GB(约 28.6 GiB);这还没有计入原文、元数据、ANN 图结构、副本和备份。降维、量化与低精度存储需要模型/数据库支持,并用召回率与成本共同评估。
精确近邻可作为小规模基线;ANN 用部分召回换取速度,遗漏证据不一定是 Embedding 的问题。pgvector、既有搜索引擎的向量能力、专用向量库和托管服务都是候选,不能只按“百万/亿级”替代并发、过滤比例、延迟、成本和运维实测。pgvector 的 HNSW 还受扫描预算影响;元数据过滤可能在 ANN 扫描后应用,因此授权请求返回不足 K 条时,要检查执行计划与迭代扫描,而不是直接认定没有更多授权资料。pgvector 索引与过滤说明
入库先保留结构,再考虑切片大小
基础入库链路应包括采集、解析、清洗、分块、元数据补全、索引写入和校验。解析要保留标题、段落、表格、图片、代码和原始定位信息。页眉被混进正文、表头与数据错位后,单纯更换 Embedding 模型难以修复这些损失。
一个可追溯的 Chunk 至少需要文档 ID、Chunk ID、内容版本、标题路径、原文位置、父节点及访问范围。更新文档时,应成批生成新版本并切换可用版本,避免在线查询混到新正文与旧向量。旧节点删除、父子关系和缓存失效也属于入库流程。
分块可采用三类方法:固定长度提供可控成本;语义边界帮助聚合同一主题;文档结构保留作者的逻辑层级。实用起点是先按结构划定大边界,过长小节再按段落或语义细分,最后用 token 上限兜底。不要把“语义分块”默认理解为必须调用大模型,规则与相邻段落表示也可以参与。
怎样确定 Chunk Size
先定义最小完整知识单元:制度常是“条件、规则、例外”;API 常是“方法、参数、返回与错误”;故障手册常是“前提、操作、预期结果与停止条件”。一个只有结论、没有适用范围的片段,即使容易命中,也可能误导回答。
再按真实问题类型选择候选粒度。精确参数问题偏向细粒度,总结问题需要高层摘要或更完整片段。可以用几组大小做对照,例如 300、600、1,000 token;这些仅是教学参数,不是推荐默认值。
比较时保持测试问题与标注不变,记录版本、分块策略、Overlap、候选数量和最终上下文预算。既检查相关片段有没有召回,也检查必需条件是否完整、重复 token 多少、答案是否正确。不同粒度在相同 Top-K 下占用的 token 并不相同,因此还应在相同上下文成本下比较,避免“大块带得多”形成不公平优势。
Overlap 可以缓解切断边界,却不会自动修复所有语义缺失;重叠过多还会使候选集中于同一段。它应与检索数量和去重策略一起调节。
增量入库与删除必须属于同一条流水线
元数据有不同用途:文档标题和标题路径可以参与检索表示;租户、授权范围、生效区间、版本、页码与定位偏移作为结构字段管理。不要把整份 ACL JSON 拼进向量文本,也不要只把标题留在元数据后假定所有框架会自动嵌入它。原文和检索增强文本应能区分,以便引用仍指向真实正文。
{
"doc_id": "travel-policy",
"chunk_id": "travel-policy:v3.2:lodging:01",
"document_version": "v3.2",
"heading_path": ["差旅制度", "费用标准", "住宿"],
"source_span": {"page_start": 3, "page_end": 3, "start": 180, "end": 246},
"effective_from": "2026-01-01",
"effective_to": null,
"tenant_id": "demo-tenant",
"acl_policy_id": "staff-policy-v2",
"index_version": "split-v2_embed-v1"
}
这是教学字段结构,偏移必须声明相对于原文件、解析结果还是小节。PDF 双栏、扫描件、跨页表格和页眉页脚需要分别验收;把逐页文本合并成全文时,需保留页段到合并文本的映射,否则虽然改善跨页切块,却丢掉引用定位。
| 变化 | 可复用什么 | 必须同步更新什么 |
|---|---|---|
| 文本变化 | 未变的检索表示可复用向量 | 新片段、旧片段失效、原文与引用位置 |
| 只有权限/有效期变化 | 通常可复用正文向量 | 元数据、权限缓存、检索可见性 |
| 文档删除或撤销 | 由保留政策决定是否归档 | 所有检索通道、父节点展开与缓存 |
| Embedding 空间变化 | 原始文档与解析产物 | 受影响向量全部重算、索引与缓存命名空间 |
| 分块策略变化 | 未变片段有机会复用 | 边界、父子关系、证据标注映射与索引版本 |
按文档身份和内容哈希求差集,可避免每次全量重算;哈希还需覆盖实际参与 Embedding 的标题等字段。稳定 ID 不能只靠正文哈希:不同租户或位置的同一段文字仍然是不同证据。权限变化没有改变正文,也必须更新访问控制,不能因为文本哈希不变而跳过整条记录。
删除应有明确事件,并定期对照源文档与各索引的 ID 集合。软删除便于回滚,但是否允许保留原文由实际数据保留规则决定;历史查询要按明确版本及生效区间读取。“今年有效”不能简单写成 effective_date >= 今年元旦,因为去年生效的制度也可能仍在有效期。
索引升级可在旁路建新版本,用同一评测集核验后切换并保留回滚点。迁移期间的增量事件、撤权和删除也要同步到新索引,不能用旧快照覆盖新变更。解析、分块、Embedding、入库和校验都应记录版本,才能复现一次重建。
图片、表格、列表与代码分别组织
| 内容类型 | 用于检索的表示 | 回答时应保留的证据 |
|---|---|---|
| 架构图、流程图 | 标题、图注、节点关系及结构化描述 | 原图、箭头方向和所在章节 |
| 小表格 | 表名、表头、单位与整表内容 | 行列对应关系及备注 |
| 大表格 | 表头绑定的行组、实体或字段索引 | 原始行、单位;聚合走结构化查询 |
| 长列表 | 标题加完整列表项,必要时分组 | 序号、步骤依赖与共同前提 |
| 代码与 API | 符号、函数说明、输入输出及模块路径 | 版本、完整相关代码和错误处理 |
| FAQ | 完整的问题与答案配对 | 适用范围、更新版本及例外 |
图片中的文字可以由 OCR 提取,箭头、流程分支和趋势则需要额外解析。视觉模型生成的描述属于派生表示,应保留原图引用并抽样检查,尤其是方向、数量和单位。生成摘要帮助查找,不应替代对图中原始事实的核对。
长表若切成行组,每组都带表头和单位。跨行合并单元格需要补回实体名称,否则一行脱离原表就失去含义。求和、筛选和排序等问题,通常更适合用受控 SQL 或表格工具计算,而不是让模型从召回的若干行猜总量。
步骤列表不能为语义聚类而任意重排,代码也不能把异常处理和它保护的操作割裂。文档里“看起来相邻”的内容不一定属于同一个知识单元,反之同一条规则的前提可能位于前一节;分块后的样本审核需要包含这些边界。
父子与层次结构:让召回粒度不同于阅读粒度
父子文档把较小片段作为检索入口,再通过 parent_id 获取更完整的阅读上下文。它适用于子片段能够定位具体规则、父小节包含必要条件的情况。例如底层片段是“该操作仅限维护时段”,父节点同时给出维护时段定义、例外审批和回滚要求。
文档
└─ 章节:维护作业
└─ 小节:执行条件与回滚
├─ 条件片段
├─ 操作片段
└─ 异常与回滚片段
查询命中条件片段 → 核验版本和权限 → 按需加载完整小节
这不是“小块一定更准、大块一定更全”的保证。小片段也可能缺少语义,父节点也可能包含噪声。父节点去重、长度约束和权限复核不可省;多个子节点命中同一父节点时,不能重复注入整段。
父节点排序可从最佳子节点得分开始,再尝试多个子节点信号的聚合。一个借鉴倒数排名的教学启发式为:
parent_score(P) = Σ 1 / (k + rank(c))
c 属于 P 且出现在候选集内
它与跨多个检索列表的标准 RRF 是不同用途的聚合规则,不是父子检索的通用定理。简单求和会偏向拥有更多子节点的大父节点,也可能把多个重复片段当成多份证据。可以限制参与聚合的独立子片段数,或加上长度、重复度控制,再用覆盖率和成本检验是否优于最佳子节点基线。
层次结构还可以包含章节摘要、主题索引和事实节点。概览问题先找高层摘要,参数问题先找底层事实,解释性问题再向上补范围和理由。物理目录与逻辑主题可并存:原文按部门组织,检索可以按安装、配置、故障等主题建立另一组链接,但两者都要保留原始定位。
逐级展开时,每次明确缺的是条件、解释还是更多实体,并记录新增证据。如果父层仍没有所需信息,应切换关联材料;无止境扩大到整篇文档只会耗尽预算。多层并行召回也可以试验,但会增加索引维护、重排和去重成本,不宜默认启用。
在父子结构之外选择上下文扩展方式
父子检索已经解决“定位粒度与阅读粒度不同”的问题。另有三种相关办法,可以按文档结构试验:
| 方法 | 索引入口 | 命中后取得的证据 | 特别检查 |
|---|---|---|---|
| 句子窗口 | 句子或小片段与原文偏移 | 同一文档前后若干句 | 扩展不越过权限、版本与章节边界 |
| 摘要索引原文 | 表格、代码、图像或大段内容的摘要 | 通过稳定引用读取原始内容 | 摘要失真不能取代原文核验 |
| 多表示索引 | 原文、摘要、可能问题等多个向量 | 同一份原始证据 | 按原文身份去重,避免多表示冒充多份支持 |
Overlap 在分块时预先重复内容,窗口扩展在命中后读取相邻原文,维护位置映射才能让后者可靠。表格摘要可帮助找到“住宿费标准”,最终仍需检查表头、城市档位、单位和例外。为每块生成多个表示会增加生成、存储和更新成本,召回改善要用基线对照证明;它不是没有副作用的通用升级。
以上增补整理自 CodeCrush 15:RAG 工作原理、16:原始文档到可检索知识库、17:Embedding 和向量数据库、18:检索质量。示例与纠错为知识库整理,不代表实测性能。框架代码集中在 Spring AI 与 LangChain:RAG 工程实现。
把失败定位到入库、路由或上下文
“检索没有答对”并不是足够精确的问题描述。排查时可按如下路径检查:
| 现象 | 优先检查 | 验证方式 |
|---|---|---|
| 目标证据根本没进入库 | 解析、更新、权限标签 | 由文档 ID 检查原文与各层节点 |
| 文档在库,但查了错误来源 | 目录与 Query 路由 | 对比缺口与所选数据源能力 |
| 召回结论,遗漏条件 | 分块边界、父节点关系 | 检查最小知识单元是否完整 |
| 召回更多后答案反而变差 | 重复、旧版本和父层噪声 | 固定证据内容,比较注入差异 |
| 总结只有几个局部事实 | 问题粒度与层级选择 | 加入高层摘要并追溯原文覆盖 |
验收时可以给同一条规则设计一组互补问题:询问规则本身、询问它的适用前提、询问例外,再要求概览所在章节。前三类检查细粒度片段和必要上下文是否能配套返回,后一类检查高层摘要是否覆盖主要内容。若只有关键词直接命中题表现良好,就不能据此认定层次检索已经有效。
还应保留一条规则更新后的对照样本:新文档上线后,旧版本问题仍能在指定历史范围查询,新版本问题不会混入旧规则,被撤销的访问权也不会因父节点展开而恢复。这样才能把索引完整性与权限、版本的一致性一起验证。
在入库验收集中保留扫描文档、跨页表格、代码、例外条款和权限不同的相邻内容;在检索测试集中覆盖精确查找、概览、解释、对比和无答案问题。只有原始内容能正确落库、被路由到合适来源,并以完整证据进入上下文,后续的召回与排序优化才有可靠基础。