ベクトル検索 - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化しておきます。

ベクトル検索機能には、SDK バージョン 5.4.4 以降が必要です。最新バージョンの SDK を使用することを推奨します。

データテーブルに対して、ベクトルフィールドを含む検索インデックスが作成されている必要があります。

説明

ベクトル検索は、クエリベクトルとベクトルフィールド内のベクトルとの間で近似最近傍 (ANN) 計算を実行し、検索インデックスに設定された距離メトリックを使用して結果をスコアリングし、最近傍データを返します。フィールドのディメンションは、クエリベクトルのディメンションと同じである必要があります。

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

次の例では、指定された 4 次元ベクトルに最も近い 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`	ベクトルフィールドの名前。
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]`	検索ヒット。行、関連性スコア、ハイライトなどの拡張情報を含みます。

タプル互換のレスポンス

Tablestore SDK for Python 5.2.0 以降、検索 API はタプルの代わりにレスポンスオブジェクトを返します。バージョン 5.1.0 以前はタプルを直接返していました。バージョン 5.2.1 以降では、SearchResponse.v1_response() を呼び出して、以前のバージョンと互換性のあるタプルを取得できます。新しいコードでは、レスポンスフィールドが拡張された場合にアンパックエラーを避けるため、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)