Vector search - Tablestore SDK for Python - Tablestore - Alibaba Cloud Dokümantasyon Merkezi

Önkoşullar

Tablestore SDK for Python yükleyin ve bir istemci başlatın.

Vektör arama özelliği için SDK sürüm 5.4.4 veya üzeri gerekir. En son SDK sürümünü kullanmanızı öneririz.

Veri tablosu için Vector alanı içeren bir arama dizini oluşturulmuş olmalıdır.

Açıklama

Vektör araması, bir sorgu vektörü ile Vector alanındaki vektörler arasında yaklaşık en yakın komşu (ANN) hesaplaması yapar, sonuçları arama dizini için yapılandırılan uzaklık metriğini kullanarak puanlar ve en yakın komşu verilerini döndürür. Alan boyutu, sorgu vektörü boyutuna eşit olmalıdır.

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

Aşağıdaki örnek, belirtilen dört boyutlu bir vektöre en yakın üç satırı sorgular ve bunları vektör puanına göre azalan sırada döndürür.

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)

Önemli

Vektör araması için get_total_count değerini True olarak ayarlamayın. Vektör alanlarının sayısı ve boyutları ile top_k üzerinde sınırlamalar bulunur. Daha fazla bilgi için bkz. Arama dizini sınırlamaları.

Parametreler

Arama isteği

search yöntemi aşağıdaki parametreleri içerir.

Ad	Tür	Açıklama
table_name (gerekli)	`str`	Veri tablosunun adı.
index_name (gerekli)	`str`	Arama dizininin adı.
search_query (gerekli)	`SearchQuery`	Sorgu koşulu ve genel sorgu yapılandırmaları.
columns_to_get (isteğe bağlı)	`ColumnsToGet`	Döndürülecek sütun yapılandırması. Bu parametre belirtilmezse yalnızca birincil anahtar sütunları döndürülür.
routing_keys (isteğe bağlı)	`list`	Özel yönlendirme alanlarının birincil anahtar değerleri. Özel yönlendirme yapılandırılmamışsa bu parametre gerekli değildir.
timeout_s (isteğe bağlı)	`int`	Saniye cinsinden istek zaman aşımı. Bu parametre belirtilmezse istemci düzeyindeki zaman aşımı kullanılır.

Sorgu yapılandırması

search_query, SearchQuery türündedir ve aşağıdaki parametreleri içerir.

Ad	Tür	Açıklama
query (gerekli)	`Query`	Sorgu koşulu. Bu parametreyi `KnnVectorQuery` olarak ayarlayın.
sort (isteğe bağlı)	`Sort`	Sonuçların sıralama düzeni. Daha fazla bilgi için bkz. Sonuçları sıralama ve sayfalara bölme.
get_total_count (isteğe bağlı)	`bool`	Vektör araması toplam sayı izlemeyi desteklemez. Bu parametreyi `False` olarak bırakın.
next_token (isteğe bağlı)	`bytes`	Sayfalama belirteci. Sonraki sayfayı almak için önceki yanıttaki `next_token` değerini iletin. Her sunucu tarafı dizin bölümü kendi `top_k` en yakın değerlerini döndürür ve bunlar koordinatör tarafından birleştirilir. Bu nedenle, `next_token` kullanarak sayfalama yaptığınızda döndürülen kümülatif satır sayısı sunucu tarafı dizin bölümlerinin sayısına bağlıdır.
offset (isteğe bağlı)	`int`	Sorgunun başladığı ofset. Sığ sayfalama için bu parametreyi kullanın.
limit (isteğe bağlı)	`int`	Döndürülecek maksimum satır sayısı. Bu parametre `0` olarak ayarlanırsa hiçbir satır döndürülmez.
aggs (isteğe bağlı)	`list[Agg]`	Metrik toplama yapılandırmaları. Daha fazla bilgi için bkz. Toplama.
group_bys (isteğe bağlı)	`list[BaseGroupBy]`	Gruplama yapılandırmaları. Daha fazla bilgi için bkz. Toplama.
collapse_field (isteğe bağlı)	`Collapse`	Sonuç daraltma yapılandırması. Daha fazla bilgi için bkz. Sorgu sonuçlarını daraltma.

Vektör sorgu koşulu

search_query.query, KnnVectorQuery türündedir ve aşağıdaki parametreleri içerir.

Ad	Tür	Açıklama
field_name (gerekli)	`str`	Vector alanının adı.
top_k (gerekli)	`int`	Sorgulanacak en yakın vektör sayısı. Maksimum değer: `1000`.
float32_query_vector (gerekli)	`list[float]`	Benzerliği hesaplamak için kullanılan Float32 sorgu vektörü. Uzunluğu vektör alanı boyutuna eşit olmalıdır.
filter (isteğe bağlı)	`Query`	En yakın komşu verilerinin de karşılaması gereken vektör dışı koşul. Koşulları birleştirmek için `BoolQuery` kullanın.
weight (isteğe bağlı)	`float`	Vektör sorgusu ağırlığı; `0` değerine eşit veya büyük olmalıdır. Varsayılan değer: `1.0`. Eşleşmeyi değil, puanları etkiler.
min_score (isteğe bağlı)	`float`	Minimum puan eşiği; `0` değerine eşit veya büyük olmalıdır. Yalnızca puanları bu değerden kesinlikle daha yüksek olan satırlar döndürülür.
num_candidates (isteğe bağlı)	`int`	Her dizin bölümünde ziyaret edilen aday sayısı. Geçerli değerler: `[top_k, 1000]`. Daha büyük bir değer geri çağırmayı iyileştirebilir ancak gecikme süresini artırabilir.

Dönüş sütunları

columns_to_get, ColumnsToGet türündedir ve aşağıdaki parametreleri içerir.

Ad	Tür	Açıklama
column_names (isteğe bağlı)	`list[str]`	Döndürülecek nitelik sütunlarının adları. Bu parametreyi yalnızca `return_type` değeri `SPECIFIED` olduğunda belirtin.
return_type (isteğe bağlı)	`ColumnReturnType`	Döndürme sütunu modu. `NONE` (varsayılan) yalnızca birincil anahtar sütunlarını döndürür; `SPECIFIED` belirtilen nitelik sütunlarını döndürür; `ALL` tablodaki tüm nitelik sütunlarını döndürür ve `ALL_FROM_INDEX` dizindeki tüm depolanan alanları döndürür.

Yanıt

search yöntemi SearchResponse döndürür. Aşağıdaki tabloda temel alanlar açıklanmaktadır.

Alan	Tür	Açıklama
rows	`list[Row]`	Sorgu tarafından döndürülen satırlar. Sayı `limit` değerini aşmaz.
next_token	`bytes`	Sonraki sayfa için belirteç. Boş bir değer, başka veri olmadığını gösterir.
total_count	`int`	Vektör araması toplam sayı izlemeyi desteklemez. Bu alanı kullanmayın.
is_all_succeed	`bool`	Tüm dizin bölümlerinin sorgulanıp sorgulanmadığını gösterir. Değer `False` ise kısmi sonuçlar döndürülür.
agg_results	`list[AggResult]`	Metrik toplama sonuçları. `aggs` yapılandırılmamışsa bu alan boştur.
group_by_results	`list[GroupByResult]`	Gruplama sonuçları. `group_bys` yapılandırılmamışsa bu alan boştur.
search_hits	`list[SearchHit]`	Satırlar, alaka puanları ve vurgulamalar gibi genişletilmiş bilgileri içeren arama isabetleri.

Tuple uyumlu yanıt

Tablestore SDK for Python 5.2.0 sürümünden itibaren arama API'leri tuple yerine yanıt nesneleri döndürür. 5.1.0 ve önceki sürümler doğrudan tuple döndürür. 5.2.1 ve sonraki sürümlerde, önceki sürümlerle uyumlu bir tuple elde etmek için SearchResponse.v1_response() çağırabilirsiniz. Yeni kodlarda, yanıt alanları genişletildiğinde paket açma hatalarından kaçınmak için SearchResponse özniteliklerine doğrudan erişin.

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

Örnekler

Vektör dışı bir koşula ve puana göre filtreleme

Aşağıdaki örnek, category değeri book- ile başlayan ve vektör puanı 0.1 değerinden büyük olan en yakın komşu satırları döndürür. Her dizin bölümündeki 10 adaydan en iyi üç satır seçilir.

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)