Retrieve 检索知识-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Retrieve 接口在知识库中执行语义检索，返回与查询文本最相关的切片列表。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
待检索的知识库已存在，且其中已有状态为 completed 的文档。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	list<string>	子空间列表，最多 32 个。开启 subspace 时必填
`retrievalQuery`	object	检索查询（必填）
`retrievalQuery.type`	string	查询类型（必填）。当前仅支持 `TEXT
`retrievalQuery.text`	string	检索文本（必填）。最长 128 字符
`retrievalConfiguration`	object	检索配置，不传时使用知识库级别配置或系统默认值
`retrievalConfiguration.searchType`	list<string>	检索类型
`retrievalConfiguration.denseVectorSearchConfiguration.numberOfResults`	int	向量检索返回数量，最大 100
`retrievalConfiguration.fullTextSearchConfiguration.numberOfResults`	int	全文检索返回数量，最大 100
`retrievalConfiguration.rerankingConfiguration`	object	Rerank 配置
`retrievalConfiguration.filter`	object	元数据过滤条件

检索配置优先级

Retrieve 接口的检索配置（retrievalConfiguration）按以下优先级确定最终生效的参数：

优先级	来源	说明
1（最高）	Retrieve 接口参数	本次请求中传入的 `retrievalConfiguration`，仅对当次生效
2	知识库级别配置	创建知识库时设定，可通过 UpdateKnowledgeBase 随时修改
3（最低）	系统默认值	向量 + 全文混合检索，WEIGHT 加权融合（向量 0.7 : 全文 0.3），返回 20 条结果

未开启子空间时，最简检索请求只需传 knowledgeBaseName 和 retrievalQuery；开启子空间时还必须传入 subspace。未显式传入检索配置时，系统使用知识库配置或默认值。

filter 支持的算子

比较算子

算子	符号	说明	适用类型
`equals`	=	等于	所有类型
`notEquals`	≠	不等于	所有类型
`greaterThan`	>	大于	long, double, date
`greaterThanOrEquals`	≥	大于等于	long, double, date
`lessThan`	<	小于	long, double, date
`lessThanOrEquals`	≤	小于等于	long, double, date

集合与匹配算子

算子	说明	适用类型
`in`	值在给定集合中	所有类型
`notIn`	值不在给定集合中	所有类型
`startsWith`	字符串前缀匹配	string
`stringContains`	字符串包含匹配	string
`listContains`	列表字段包含指定元素	list 类型

逻辑组合算子

算子	说明
`andAll`	所有条件同时满足
`orAll`	任一条件满足
`notAll`	所有条件都不满足

andAll、orAll和notAll支持嵌套，可构建复杂的组合过滤逻辑。

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

curl -X POST https://<endpoint>/Retrieve \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": ["default"],
  "retrievalQuery": {"type": "TEXT", "text": "产品的安装步骤是什么"},
  "retrievalConfiguration": {
    "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
    "denseVectorSearchConfiguration": {"numberOfResults": 10},
    "fullTextSearchConfiguration": {"numberOfResults": 10},
    "rerankingConfiguration": {
      "type": "RRF",
      "numberOfResults": 5,
      "rrfConfiguration": {"denseVectorSearchWeight": 0.6, "fullTextSearchWeight": 0.4, "k": 60}
    },
    "filter": {
      "andAll": [
        {"greaterThanOrEquals": {"key": "score", "value": 60}}
      ]
    }
  }
}'

响应

字段	类型	说明
`retrievalResults`	list<object>	检索结果列表，按相关性得分降序排列
`retrievalResults[].docId`	string	所属文档 ID
`retrievalResults[].chunkId`	int	切片 ID
`retrievalResults[].ossKey`	string	所属文档 OSS 路径
`retrievalResults[].score`	float	相关性得分，越高越相关
`retrievalResults[].content`	string	切片原文内容
`retrievalResults[].subspace`	string	所属子空间
`retrievalResults[].metadata`	object	文档元数据

{
    "code": "SUCCESS",
    "data": {
        "retrievalResults": [
            {
                "ossKey": "oss://example-bucket/docs/manual.pdf",
                "docId": "fc6ed97f-28ad-4dc0-9b73-bf4a7d67ab65",
                "chunkId": 0,
                "chunkType": "TEXT",
                "subspace": "default",
                "score": 0.6630394798989444,
                "content": "产品安装步骤：1. 下载并解压安装包。2. 按安装向导完成安装。3. 启动产品，确认显示安装成功页面。", "metadata": {"author": "张三", "date": "2026-01-22 10:00:59", "score": 80}
            }
        ]
    },
    "message": "success"
}