Pencarian vektor - Tablestore SDK untuk Python - Tablestore

Gunakan Tablestore SDK untuk Python untuk mengambil data tetangga terdekat dari search index berdasarkan kemiripan vektor.

Prasyarat

Instal Tablestore SDK untuk Python dan inisialisasi klien.

Fitur pencarian vektor memerlukan SDK versi 5.4.4 atau lebih baru. Disarankan untuk menggunakan versi SDK terbaru.

Search index yang berisi bidang Vector telah dibuat untuk tabel data.

Deskripsi

Pencarian vektor melakukan perhitungan approximate nearest neighbor (ANN) antara vektor kueri dan vektor dalam bidang Vector, memberikan skor hasil berdasarkan metrik jarak yang dikonfigurasi pada search index, lalu mengembalikan data tetangga terdekat. Dimensi bidang harus sama dengan dimensi vektor kueri.

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

Contoh berikut mengkueri tiga baris terdekat ke vektor empat dimensi tertentu dan mengembalikannya dalam urutan skor vektor menurun.

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)

Penting

Jangan atur get_total_count ke True untuk pencarian vektor. Terdapat batasan pada jumlah dan dimensi bidang vektor serta pada top_k. Untuk informasi selengkapnya, lihat Batasan search index.

Parameter

Permintaan pencarian

Metode search mencakup parameter berikut.

Nama	Type	Deskripsi
table_name (wajib)	`str`	Nama tabel data.
index_name (wajib)	`str`	Nama search index.
search_query (wajib)	`SearchQuery`	Kondisi kueri dan konfigurasi kueri umum.
columns_to_get (opsional)	`ColumnsToGet`	Konfigurasi kolom yang dikembalikan. Jika parameter ini tidak ditentukan, hanya kolom kunci primer yang dikembalikan.
routing_keys (opsional)	`list`	Nilai kunci primer dari bidang routing kustom. Parameter ini tidak diperlukan jika routing kustom tidak dikonfigurasi.
timeout_s (opsional)	`int`	Timeout permintaan dalam detik. Jika parameter ini tidak ditentukan, timeout tingkat client akan digunakan.

Konfigurasi kueri

search_query bertipe SearchQuery dan mencakup parameter berikut.

Nama	Tipe	Deskripsi
query (wajib)	`Query`	Kondisi kueri. Atur parameter ini ke `KnnVectorQuery`.
sort (opsional)	`Sort`	Urutan pengurutan hasil. Untuk informasi selengkapnya, lihat Mengurutkan dan membagi halaman hasil.
get_total_count (opsional)	`bool`	Pencarian vektor tidak mendukung pelacakan jumlah total. Biarkan parameter ini diatur ke `False`.
next_token (opsional)	`bytes`	Token paginasi. Teruskan `next_token` dari respons sebelumnya untuk mengambil halaman berikutnya. Setiap partisi indeks sisi server mengembalikan nilai `top_k` terdekatnya sendiri, yang kemudian digabungkan oleh koordinator. Oleh karena itu, saat Anda melakukan paginasi menggunakan `next_token`, jumlah kumulatif baris yang dikembalikan bergantung pada jumlah partisi indeks sisi server.
offset (opsional)	`int`	Offset tempat kueri dimulai. Gunakan parameter ini untuk paginasi dangkal.
limit (opsional)	`int`	Jumlah maksimum baris yang dikembalikan. Jika parameter ini diatur ke `0`, tidak ada baris yang dikembalikan.
aggs (opsional)	`list[Agg]`	Konfigurasi agregasi metrik. Untuk informasi selengkapnya, lihat Agregasi.
group_bys (opsional)	`list[BaseGroupBy]`	Konfigurasi pengelompokan. Untuk informasi selengkapnya, lihat Agregasi.
collapse_field (opsional)	`Collapse`	Konfigurasi collapse hasil. Untuk informasi selengkapnya, lihat Collapse hasil kueri.

Kondisi kueri vektor

search_query.query bertipe KnnVectorQuery dan mencakup parameter berikut.

Nama	Type	Deskripsi
field_name (wajib)	`str`	Nama bidang Vector.
top_k (wajib)	`int`	Jumlah vektor terdekat yang dikueri. Nilai maksimum: `1000`.
float32_query_vector (wajib)	`list[float]`	Vektor kueri Float32 yang digunakan untuk menghitung kemiripan. Panjangnya harus sama dengan dimensi bidang vektor.
filter (opsional)	`Query`	Kondisi non-vektor yang juga harus dipenuhi oleh data tetangga terdekat. Gunakan `BoolQuery` untuk menggabungkan kondisi.
weight (opsional)	`float`	Bobot kueri vektor, yang harus lebih besar atau sama dengan `0`. Nilai default: `1.0`. Ini memengaruhi skor tetapi tidak memengaruhi pencocokan.
min_score (opsional)	`float`	Ambang batas skor minimum, yang harus lebih besar atau sama dengan `0`. Hanya baris dengan skor yang secara ketat lebih besar dari nilai ini yang dikembalikan.
num_candidates (opsional)	`int`	Jumlah kandidat yang dikunjungi pada setiap partisi indeks. Nilai valid: `[top_k, 1000]`. Nilai yang lebih besar dapat meningkatkan Recall tetapi menambah latensi.

Kolom yang dikembalikan

columns_to_get bertipe ColumnsToGet dan mencakup parameter berikut.

Nama	Tipe	Deskripsi
column_names (opsional)	`list[str]`	Nama kolom atribut yang dikembalikan. Tentukan parameter ini hanya saat `return_type` adalah `SPECIFIED`.
return_type (opsional)	`ColumnReturnType`	Mode kolom yang dikembalikan. `NONE` (default) hanya mengembalikan kolom kunci primer; `SPECIFIED` mengembalikan kolom atribut yang ditentukan; `ALL` mengembalikan semua kolom atribut dalam tabel; dan `ALL_FROM_INDEX` mengembalikan semua bidang yang disimpan dalam indeks.

Respons

Metode search mengembalikan objek SearchResponse. Tabel berikut menjelaskan bidang intinya.

Bidang	Tipe	Deskripsi
rows	`list[Row]`	Baris yang dikembalikan oleh kueri. Jumlahnya tidak melebihi `limit`.
next_token	`bytes`	Token untuk halaman berikutnya. Nilai kosong menunjukkan tidak ada data tambahan yang tersedia.
total_count	`int`	Pencarian vektor tidak mendukung pelacakan jumlah total. Jangan gunakan bidang ini.
is_all_succeed	`bool`	Menunjukkan apakah semua partisi indeks telah dikueri. Jika nilainya `False`, hasil parsial dikembalikan.
agg_results	`list[AggResult]`	Hasil agregasi metrik. Bidang ini kosong jika `aggs` tidak dikonfigurasi.
group_by_results	`list[GroupByResult]`	Hasil pengelompokan. Bidang ini kosong jika `group_bys` tidak dikonfigurasi.
search_hits	`list[SearchHit]`	Hit pencarian, termasuk informasi tambahan seperti baris, skor relevansi, dan sorotan.

Respons kompatibel tupel

Mulai dari Tablestore SDK untuk Python versi 5.2.0, API pencarian mengembalikan objek respons, bukan tupel. Versi 5.1.0 dan sebelumnya langsung mengembalikan tupel. Pada versi 5.2.1 dan seterusnya, Anda dapat memanggil SearchResponse.v1_response() untuk mendapatkan tupel yang kompatibel dengan versi sebelumnya. Untuk kode baru, akses atribut SearchResponse secara langsung guna menghindari error unpacking jika bidang respons diperluas.

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

Contoh

Filter berdasarkan kondisi non-vektor dan skor

Contoh berikut mengembalikan baris tetangga terdekat yang nilai category-nya diawali dengan book- dan skor vektornya lebih besar dari 0.1. Tiga baris teratas dipilih dari 10 kandidat pada setiap partisi indeks.

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)