启用文档级去重与聚合可将同一pdf的多个检索片段自动合并为一条结果；需确保知识库版本≥v2.4.0、上传时指定metadata.document_id、检索请求中设置"group_by_document": true，并验证返回结果中source一致、content含[sep]分隔、score取最高分。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在火山引擎RAG企业知识库中搜索一个宽泛问题，比如“客户退款政策”，系统可能从同一份《售后服务手册V3.2.pdf》里抽出5个不同段落，分散显示为5条独立结果，导致信息割裂、阅读效率低下。要让这些来自同一文档的检索片段自动归并成一条聚合结果，必须启用并正确配置文档级去重与聚合机制。
确认知识库已开启文档聚合能力
登录火山引擎控制台 → 进入「RAG企业知识库」服务 → 选择对应知识库实例 → 点击「配置管理」→ 查看「检索增强设置」区域。若「文档结果聚合」开关为灰色不可用状态，说明当前知识库版本低于支持该功能的最低要求（需v2.4.0+），必须先升级知识库引擎版本。
【必须确保知识库实例运行在2026年8月后发布的镜像版本上】
上传文档时指定唯一文档标识
聚合的前提是系统能识别“哪些切片属于同一原始文档”。上传PDF/DOCX等文件时，不能仅靠文件名判断——因为《退款政策.docx》和《退款政策_2024修订版.docx》可能是同一份文档的不同版本。
必须在调用Files API上传时，显式传入metadata.document_id字段：
```bash
curl https://ark.cn-beijing.volces.com/api/v3/files \
-H "Authorization: Bearer $ARK_API_KEY" \
-F 'purpose=user_data' \
-F 'file=@./refund_policy_v3.2.pdf' \
-F 'metadata={"document_id": "DOC-REFUND-2024-V3.2"}'
```
这个document_id值将被写入所有由该PDF切分出的chunk元数据中，成为后续聚合的唯一依据。
配置检索请求的聚合参数
方法一：使用Chat API时在请求体中添加聚合指令
在发送自然语言查询的JSON payload中，于retriever_config对象内加入"group_by_document": true：
```json
{
"model": "doubao-seed-2-1-pro-260915",
"input": [{"role": "user", "content": "客户退货需要提供哪些凭证？"}],
"retriever_config": {
"top_k": 10,
"group_by_document": true,
"rerank_enabled": true
}
}
```
方法二：通过RAGFlow CLI本地调试时启用聚合
执行命令时追加--group-by-doc参数：ragflow query --query "发票丢失如何补开" --group-by-doc
注意：若同时启用了Volcengine Reranker，聚合操作发生在重排序之后，确保最终返回的是每个文档中最相关的1个片段，而非简单合并所有片段。
验证聚合效果与结果结构
第一步：发起一次带聚合参数的检索请求，获取返回的JSON响应。
第二步：检查响应体中retrieval_results数组长度是否明显少于未聚合时的数量（例如从12条变为3条）。
第三步：逐条查看每条结果的source字段，确认document_id值完全一致，且content字段内已拼接多个原始chunk文本，并用[SEP]符号分隔。
第四步：重点核对score字段——聚合后每条结果的分数取自该文档下所有片段的最高分，不是平均分或总分。这保证了最相关文档仍排在前面。
