表格存储 Python SDK 向量检索-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

向量检索功能需要使用 5.4.4 及以上版本，建议使用最新版本的 SDK。

已在数据表上创建多元索引并配置 Vector 字段。

功能说明

向量检索将查询向量与多元索引 Vector 字段中的向量进行近似最近邻（ANN）计算，按创建索引时配置的距离度量算法为结果评分，并返回最邻近的数据。向量字段维度必须与查询向量维度相同。

KnnVectorQuery(
    field_name,
    top_k=None,
    float32_query_vector=None,
    filter=None,
    weight=None,
    min_score=None,
    num_candidates=None,
)

以下示例查询与指定四维向量最邻近的 3 行数据，并按向量得分降序返回。

query = KnnVectorQuery(
    "embedding",
    top_k=3,
    float32_query_vector=[1.0, 0.0, 0.0, 0.0],
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(
        query,
        sort=Sort([ScoreSort()]),
        limit=3,
        get_total_count=False,
    ),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
for hit in response.search_hits:
    print(hit.score, hit.row)

重要

向量检索不支持将 get_total_count 设置为 True。向量字段数量、维度和 top_k 存在限制，具体请参见多元索引使用限制。

参数说明

查询请求

search 方法包含以下参数。

名称	类型	说明
table_name（必选）	`str`	数据表名称。
index_name（必选）	`str`	多元索引名称。
search_query（必选）	`SearchQuery`	查询条件和通用查询配置。
columns_to_get（可选）	`ColumnsToGet`	返回列配置。未设置时只返回主键列。
routing_keys（可选）	`list`	自定义路由字段对应的主键值列表。未配置自定义路由时无需设置。
timeout_s（可选）	`int`	请求级超时时间，单位为秒。未设置时使用客户端默认超时时间。

查询配置

search_query 的类型为 SearchQuery，包含以下参数。

名称	类型	说明
query（必选）	`Query`	查询条件。设置为 `KnnVectorQuery`。
sort（可选）	`Sort`	返回结果的排序方式。有关配置方法，请参见排序和翻页。
get_total_count（可选）	`bool`	向量检索不支持统计匹配总行数，必须保持为 `False`。
next_token（可选）	`bytes`	翻页凭证。将上一次响应的 `next_token` 设置到下一次请求中可继续读取。服务端每个索引分区会返回各自最邻近的 `top_k` 个值并在协调节点汇总，因此使用 `next_token` 翻页时，累计返回行数与服务端索引分区数有关。
offset（可选）	`int`	本次查询的起始位置，适用于浅翻页。
limit（可选）	`int`	本次查询返回的最大行数。设置为 `0` 时不返回具体行。
aggs（可选）	`list[Agg]`	指标聚合配置。有关配置方法，请参见统计聚合。
group_bys（可选）	`list[BaseGroupBy]`	分组配置。有关配置方法，请参见统计聚合。
collapse_field（可选）	`Collapse`	结果折叠配置。有关配置方法，请参见折叠（去重）。

向量查询条件

search_query.query 的类型为 KnnVectorQuery，包含以下参数。

名称	类型	说明
field_name（必选）	`str`	Vector 类型索引字段名称。
top_k（必选）	`int`	要查询的最邻近向量数量，最大值为 `1000`。
float32_query_vector（必选）	`list[float]`	用于计算相似度的 Float32 查询向量，长度必须与向量字段维度相同。
filter（可选）	`Query`	近邻数据还必须满足的非向量查询条件，可使用 `BoolQuery` 组合多个条件。
weight（可选）	`float`	向量查询权重，必须大于或等于 `0`。默认值为 `1.0`；影响得分，不改变匹配范围。
min_score（可选）	`float`	最小得分阈值，必须大于或等于 `0`。仅返回得分严格大于该值的数据。
num_candidates（可选）	`int`	每个索引分区计算近邻时访问的候选数，取值范围为 `[top_k, 1000]`。值越大，召回率可能提高，但查询耗时也可能增加。

返回列

columns_to_get 的类型为 ColumnsToGet，包含以下参数。

名称	类型	说明
column_names（可选）	`list[str]`	要返回的属性列名称。仅 `return_type` 为 `SPECIFIED` 时设置。
return_type（可选）	`ColumnReturnType`	返回列模式。`NONE`（默认）仅返回主键列；`SPECIFIED` 返回指定属性列；`ALL` 返回数据表全部属性列；`ALL_FROM_INDEX` 返回索引中已存储的全部属性列。

返回值

search 方法返回 SearchResponse。核心字段如下。

字段	类型	说明
rows	`list[Row]`	本次查询返回的行数据，数量不超过 `limit`。
next_token	`bytes`	下一页凭证。值为空时表示没有更多数据。
total_count	`int`	向量检索不支持统计匹配总行数，不应使用该字段。
is_all_succeed	`bool`	是否已成功查询全部索引分区。值为 `False` 时返回的是部分结果。
agg_results	`list[AggResult]`	指标聚合结果。未配置 `aggs` 时为空。
group_by_results	`list[GroupByResult]`	分组结果。未配置 `group_bys` 时为空。
search_hits	`list[SearchHit]`	查询命中结果，包含行数据、相关性得分和高亮结果等扩展信息。

兼容 Tuple 返回格式

Tablestore Python SDK 5.2.0 开始将查询接口的返回值由 Tuple 调整为响应对象，5.1.0 及以下版本直接返回 Tuple。5.2.1 及以上版本可调用 SearchResponse.v1_response() 获取与旧版本兼容的 Tuple。新代码建议直接访问 SearchResponse 的属性，避免返回字段扩展后解包数量不匹配。

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()

场景示例

按非向量条件和得分过滤

以下示例仅返回 category 以 book- 开头且向量得分大于 0.1 的近邻数据，并从每个索引分区的 10 个候选中选取前 3 个。

query = KnnVectorQuery(
    "embedding",
    top_k=3,
    float32_query_vector=[1.0, 0.0, 0.0, 0.0],
    filter=PrefixQuery("category", "book-"),
    min_score=0.1,
    num_candidates=10,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=3, get_total_count=False),
)
for hit in response.search_hits:
    print(hit.score, hit.row)