在使用智能问答系统或知识库类产品时，“检索接口”是非常关键的一环。理解其请求参数，能够帮助我们更高效地精准获取答案，提升系统性能和用户体验。本文将详细解读知识库检索接口中可控参数的含义、使用场景与建议配置。

---

1. 基础标识类参数

name（知识库名称）

• 类型：string | 是否必填：否

• 说明：定义知识库的名称，仅允许英文、数字、下划线，并且必须以字母开头，1-64个字符。

• 示例：my_knowledge_base

project（所属项目）

• 类型：string | 默认值：default

• 说明：用于区分不同项目的知识库资源，便于权限和数据隔离。

resource_id（知识库ID）

• 类型：string | 说明：如果你已知道知识库的唯一ID，可直接传它。否则可以通过 name + project 定位。

---

2. 核心检索内容

query（检索内容）⭐

• 类型：string | 是否必填：是

• 说明：你想要检索的问题/文本，最长8000字符。如果超出限制，会报错。

• 注意：最终有效长度也受所选 Embedding 模型的支持长度影响，过长会被截断。

---

3. 检索结果控制

limit（返回条数）

• 类型：int | 默认值：10 | 范围：1-200

• 说明：设置返回结果数量。推荐值在10-50之间平衡性能与准确率。

---

4. 检索过滤与增强参数

query_param.doc_filter（过滤条件）

• 类型：json（Map）

• 说明：指定对哪些文档进行过滤，如通过 doc_id 限定文档。

• 示例：

  {
    "op": "must",
    "field": "doc_id",
    "conds": ["doc_123", "doc_456"]
  }
  

dense_weight（稠密向量权重）

• 类型：float | 默认值：0.5 | 范围：0.2 ~ 1

• 说明：控制“向量检索”和“关键词匹配”的融合比重。

  • 1.0：纯向量匹配（语义相似）；

  • 0.0：纯关键词检索（字面匹配）；

  • 推荐值：0.5~0.8，根据你的场景权衡。

---

5. 检索预处理相关

need_instruction（拼接提示词）

• 类型：bool | 默认值：false

• 说明：是否自动在 query 前拼接一段引导词，以增强语义理解。

rewrite（问题改写）

• 类型：bool | 默认值：false

• 说明：用于多轮对话中，是否自动改写 query（避免省略/模糊问题）。

messages（多轮对话历史）

• 类型：json | 是否必填：仅当 rewrite=true 时

• 格式示例：

  [
    {"role": "system", "content": "你是一个智能助手。"},
    {"role": "user", "content": "介绍一下你"},
    {"role": "assistant", "content": "我是一个AI助手。"}
  ]
  

---

6. 检索后处理配置

post_processing.rerank_switch（开启重排）

• 类型：bool | 默认值：false

• 说明：是否根据语义再做一次排序（比 embedding 更精细的排序逻辑）。

  • 开启后必须设置 retrieve_count ≥ limit

post_processing.rerank_model（重排模型）

• 选项：

  • base-multilingual-rerank（推荐）：多语言长文本支持

  • m3-v2-rerank：多语言支持好，泛用性强

post_processing.retrieve_count

• 类型：int | 默认值：25

• 说明：参与重排的候选数量。值越大，精度越高但耗时更多。

post_processing.rerank_only_chunk

• 类型：bool

• 说明：只用 chunk 内容做重排，还是用 chunk 的 title + 内容 一起排序。

---

7. 其他扩展功能

chunk_diffusion_count（上下文片段扩散）

• 类型：int | 默认值：0 | 范围：0 ~ 5

• 说明：命中的文本上下是否也返回上下文邻近片段，有助于上下文理解。

chunk_group（文本聚合）

• 类型：bool | 默认值：false

• 说明：是否将命中的多个切片做聚合处理，更接近原文档逻辑顺序。

get_attachment_link

• 类型：bool | 默认值：false

• 说明：如果知识库中有图片、附件等，是否生成临时链接返回（用于前端展示）。

---

总结推荐配置场景

场景	推荐配置
纯语义检索	dense_weight=1.0, rerank_switch=true
精准关键字匹配	dense_weight=0.2, 关闭 rerank
多轮对话+智能改写	rewrite=true, 配置 messages
需要上下文增强	chunk_diffusion_count=2, chunk_group=true
图文混合文档展示	get_attachment_link=true

---