知识检索

POST /openapi/paas/v1/knowledge/retrieval

该接口返回知识来源和命中段落，不生成大模型答案。需要直接生成回答时，使用 Chat Completion。

请求头为 Authorization: Bearer tk-... 和 Content-Type: application/json，平台密钥要求 knowledge_search=READ。

请求参数

字段	类型	必填	默认值与说明
`q`	string	是	检索文本，传非空内容
`containerId`	array[string]	是	非空的知识库 code 列表
`alpha`	number	否	默认 `0.7`；使用 0～1，0 为关键词，1 为向量，中间值为混合检索
`mode`	string	否	历史模式字段；当前实际检索模式由 `alpha` 决定，不应仅修改 mode
`knowledgeScope`	string	否	默认 `ALL`；常用 `QA`（问答库）、`KNOWLEDGE`（知识内容）
`rerank`	boolean	否	默认 `true`，是否重排序
`rerankerModel`	string	否	重排序模型编码；启用重排序且未填写时使用租户配置
`top_k`	integer	否	默认 `25`，使用正整数
`score_threshold`	number	否	默认 `0.5`，相关度过滤阈值
`rrf`	boolean	否	默认 `false`，是否文档聚合排序
`dataIds`	array[string]	否	限定文件 code，应属于指定知识库
`metadataFilter`	object	否	标准或自定义元数据过滤，见过滤规则

alpha 为实际默认值 0.7，不是早期注释中的 0.5。containerId 不可省略；接口不会自动把空列表展开成全部知识库。

请求示例

curl --request POST "${BASE_URL}/openapi/paas/v1/knowledge/retrieval" \
  --header "Authorization: Bearer ${AIS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "q": "产品支持哪些部署方式？",
    "containerId": ["partner_kb_001"],
    "alpha": 0.7,
    "rerank": true,
    "top_k": 10,
    "score_threshold": 0.5,
    "metadataFilter": {
      "logicalOperator": "AND",
      "conditions": [
        {"field": "suffix", "operator": "IN", "values": ["pdf", "docx"]}
      ]
    }
  }'

响应

成功为 code=8200，data.references 为引用来源，data.paragraphs 为命中片段。返回对象与字段如下：

字段	JSON 类型	说明
`data`	object	检索结果，不是答案文本
`data.references`	array[object]	文件级来源，完整字段见 Reference
`data.paragraphs`	array[object]	命中段落，完整字段见 ReferenceParagraph

来源与命中片段常用字段

字段	JSON 类型	说明
`containerId`	string	来源知识库 code
`containerName`	string / null	来源知识库名称
`dataSetId`	string	来源文件 code，用于去重和来源关联
`dataSetName`	string	文件名称
`dataSetUrl`	string / null	来源地址；优先从 references 读取
`suffix`	string / null	文件后缀
`paragraphs[].content`	string	片段文本
`paragraphs[].page`	integer / null	页码，无分页来源可空
`paragraphs[].score`	number / null	检索/重排相关分数，不是回答正确率
`paragraphs[].metadata`	object / null	来源相关元数据，无固定键集合

响应示例

示例省略可选分数与版本字段：

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "references": [
      {
        "containerId": "partner_kb_001",
        "containerName": "产品知识库",
        "dataSetId": "partner_file_001",
        "dataSetName": "产品白皮书.pdf",
        "dataSetUrl": "https://example.com/files/product.pdf",
        "suffix": "pdf"
      }
    ],
    "paragraphs": [
      {
        "containerId": "partner_kb_001",
        "containerName": "产品知识库",
        "dataSetId": "partner_file_001",
        "dataSetName": "产品白皮书.pdf",
        "page": 1,
        "content": "支持按项目约定进行部署。",
        "suffix": "pdf"
      }
    ]
  }
}

文件引用编码字段为 dataSetId，不能沿用旧示例中的 dataId 来读取引用对象。分片列表接口的 dataId 是另一响应结构中的字段。相关分数、元数据等扩展字段按实际结果返回，不保证所有来源都有值。

无命中时可以返回空列表；若增加过滤后无结果，检查字段值、知识库范围和文档状态。非法字段或不支持的过滤操作符会返回错误，不会自动忽略过滤条件。查询失败按错误编码处理。

请求参数​

请求示例​

响应​

来源与命中片段常用字段​

响应示例​

请求参数

请求示例

响应

来源与命中片段常用字段

响应示例