表格存储知识库混合检索与Rerank排序策略配置（向量、全文、元数据过滤）-阿里云帮助中心

通过 Retrieve 接口在知识库中执行语义检索，返回与查询文本最相关的切片列表。支持向量检索、全文检索及混合检索，支持元数据过滤和多种排序（Rerank）策略。

检索配置优先级

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

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

最简单的检索请求只需传 knowledgeBaseName 和 retrievalQuery，系统自动使用知识库配置或默认值。

检索类型

类型	说明	适用场景
`DENSE_VECTOR`	向量检索，基于语义相似度	用自然语言描述需求，需要理解语义。如"怎么安装"能匹配到"部署步骤"
`FULL_TEXT`	全文检索，基于关键词匹配	输入精确关键词、专有名词或编号

向量检索和全文检索在召回上具有互补能力：向量检索擅长语义理解，全文检索擅长精确匹配。建议同时开启两种检索类型，通过 Rerank 融合结果。

Rerank 排序策略

Rerank 将向量检索和全文检索的结果融合排序，返回最终结果。

WEIGHT（加权融合）

按比例加权向量与全文检索得分。适合需要精细控制两路检索贡献比例的场景。推荐作为默认选择。

配置参数：

参数	类型	默认值	说明
`denseVectorSearchWeight`	double	0.7	向量检索加权比例
`fullTextSearchWeight`	double	0.3	全文检索加权比例

RRF（Reciprocal Rank Fusion）

按排名倒数加权融合多路检索结果。无需额外模型调用，延迟低，效果稳定。

配置参数：

参数	类型	默认值	说明
`denseVectorSearchWeight`	double	1.0	向量检索权重
`fullTextSearchWeight`	double	1.0	全文检索权重
`k`	int	60	RRF 算法参数，必须大于 0

配置示例：

{
  "rerankingConfiguration": {
    "type": "RRF",
    "numberOfResults": 5,
    "rrfConfiguration": {
      "denseVectorSearchWeight": 0.6,
      "fullTextSearchWeight": 0.4,
      "k": 20
    }
  }
}

MODEL（模型 Rerank）

调用 Rerank 模型（如 gte-rerank-v2）对候选结果重排序。排序质量最高，但会引入额外延迟和计算成本。

配置参数：

参数	类型	默认值	说明
`provider`	string	`bailian`	Rerank 模型提供方，当前仅支持百炼
`model`	string	`gte-rerank-v2`	Rerank 模型名称

策略选择建议

场景	推荐策略
通用场景，对延迟敏感	RRF
需要精细控制向量与全文检索的比例	WEIGHT
对排序质量要求极高，可接受额外延迟	MODEL

元数据过滤

在检索时通过 filter 参数按元数据条件过滤结果，缩小候选范围。过滤字段必须在创建知识库时通过 metadata 定义。

比较算子

算子	符号	说明	适用类型
`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支持嵌套，可构建复杂的组合过滤逻辑。

过滤示例

查询 category 为 “technology” 或 “science”，且 score ≥ 60，且 title 以“产品”开头的文档：

{
  "filter": {
    "andAll": [
      {"in": {"key": "category", "value": ["technology", "science"]}},
      {"greaterThanOrEquals": {"key": "score", "value": 60}},
      {"startsWith": {"key": "title", "value": "产品"}}
    ]
  }
}

使用 orAll 实现“或”逻辑：查询 status 为 “active” 或 score > 90 的文档：

{
  "filter": {
    "orAll": [
      {"equals": {"key": "status", "value": "active"}},
      {"greaterThan": {"key": "score", "value": 90}}
    ]
  }
}

Retrieve 接口

请求参数

参数	类型	说明
`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	元数据过滤条件

响应说明

响应字段

字段	类型	说明
`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	文档元数据

代码示例

最简示例

请求里面不设置检索参数，使用知识库级别配置或系统默认值：

resp = client.retrieve({
    "knowledgeBaseName": "product_docs_kb",
    "retrievalQuery": {"type": "TEXT", "text": "产品的安装步骤是什么"}
})

for r in resp["data"]["retrievalResults"]:
    print(f"[{r['score']:.4f}] {r['content'][:80]}...")

完整示例

检索请求里面设置全部或部分检索参数，覆盖知识库级别配置：

resp = client.retrieve({
    "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": [
                {"in": {"key": "category", "value": ["产品文档"]}}
            ]
        }
    }
})

for result in resp["data"]["retrievalResults"]:
    print(f"[score={result['score']:.4f}] {result['content'][:100]}...")
    print(f"  来源: {result['ossKey']}, chunkId: {result['chunkId']}")

Model 类方式

使用 Model 类构建请求，获得更好的 IDE 代码补全和类型检查：

from tablestore_agent_storage.models import (
    RetrieveRequest, RetrievalQuery, RetrievalQueryType
)

resp = client.retrieve(RetrieveRequest(
    knowledge_base_name="product_docs_kb",
    retrieval_query=RetrievalQuery(
        text="产品的安装步骤是什么",
        type=RetrievalQueryType.TEXT
    )
))

响应示例

{
  "code": "SUCCESS",
  "data": {
    "retrievalResults": [
      {
        "ossKey": "oss://example-bucket/docs/product_manual.pdf",
        "docId": "96fb386e-...",
        "chunkId": 3,
        "subspace": "default",
        "score": 0.85,
        "content": "第一步：下载安装包...",
        "metadata": {"author": "张三", "category": "产品文档"}
      }
    ]
  },
  "message": "succeed"
}

注意事项

问题	说明
检索文本过长	`text` 最长 128 字符或汉字，超过会报错说明如有业务需求请提交工单或加入表格存储技术交流群36165029092后联系技术支持。
Filter 字段未定义	过滤字段必须在创建知识库时已定义为 metadata
RRF 的 k 值为 0	`k` 必须大于 0，否则报 `VALIDATION_ERROR`
文档未索引完成	`Pending` 或 `Indexing` 状态的文档无法被检索
未传 subspace	知识库开启 subspace 后必须传此参数

检索调优

numberOfResults 参数关系

检索流程中有三层 numberOfResults，理解它们的关系是调优的关键：

denseVectorSearchConfiguration.numberOfResults = N1  ← 向量检索召回数
fullTextSearchConfiguration.numberOfResults         = N2  ← 全文检索召回数
rerankingConfiguration.numberOfResults           = N3  ← Rerank 后最终返回数

N1 和 N2 决定候选池大小，越大召回率越高，但计算成本也越高。
N3 决定最终返回的结果数，通常 N3 < N1 且 N3 < N2。
推荐起始配置：N1 = N2 = 20，N3 = 5–10。根据实际效果逐步调整。

检索类型选择

场景	推荐检索类型	说明
用自然语言提问	`DENSE_VECTOR` + `FULL_TEXT`	向量捕捉语义，全文保障关键词命中
输入精确关键词或编号	优先 `FULL_TEXT`	向量检索对精确匹配不敏感
纯语义理解场景	优先 `DENSE_VECTOR`	如"怎么安装"匹配"部署步骤"

Metadata Filter 使用建议

Filter 在检索前缩小候选范围，同时提升检索精度和性能。
过滤字段必须在创建知识库时定义为 metadata，运行时无法新增。
对于日期范围过滤，使用 date 类型而非 string 类型，以支持范围比较算子。