Table Store Python SDK 向量檢索 - 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)