Utilisez le SDK Tablestore pour Python pour renvoyer les données des plus proches voisins à partir d'un index de recherche, en vous basant sur la similarité vectorielle.
Prérequis
Installez le SDK Tablestore pour Python et initialisez un client.
La fonctionnalité de recherche vectorielle nécessite une version du SDK égale ou supérieure à 5.4.4. Nous vous recommandons d'utiliser la dernière version du SDK.
Un index de recherche contenant un champ Vector doit être créé pour la table de données.
Description
La recherche vectorielle calcule les plus proches voisins approximatifs (ANN) entre un vecteur de requête et les vecteurs d'un champ Vector. Elle attribue un score aux résultats selon la métrique de distance configurée pour l'index de recherche et renvoie les données les plus proches. La dimension du champ doit correspondre à celle du vecteur de requête.
KnnVectorQuery(
field_name,
top_k=None,
float32_query_vector=None,
filter=None,
weight=None,
min_score=None,
num_candidates=None,
)L'exemple suivant interroge les trois lignes les plus proches d'un vecteur quadridimensionnel spécifié et les renvoie par ordre décroissant de score vectoriel.
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)Ne définissez pas get_total_count sur True pour la recherche vectorielle. Des limites s'appliquent au nombre et aux dimensions des champs vectoriels, ainsi qu'à top_k. Pour plus d'informations, consultez la rubrique Limites des index de recherche.
Paramètres
Requête de recherche
La méthode search accepte les paramètres suivants.
|
Nom |
Type |
Description |
|
table_name (obligatoire) |
|
Nom de la table de données. |
|
index_name (obligatoire) |
|
Nom de l'index de recherche. |
|
search_query (obligatoire) |
|
Condition de requête et configurations courantes. |
|
columns_to_get (facultatif) |
|
Configuration des colonnes à renvoyer. Si ce paramètre est omis, seules les colonnes de clé primaire sont renvoyées. |
|
routing_keys (facultatif) |
|
Valeurs de clé primaire des champs de routage personnalisés. Ce paramètre n'est pas requis si le routage personnalisé n'est pas configuré. |
|
timeout_s (facultatif) |
|
Délai d'expiration de la requête en secondes. Si ce paramètre est omis, le délai d'expiration configuré au niveau du client s'applique. |
Configuration de la requête
Le paramètre search_query est de type SearchQuery et accepte les paramètres suivants.
|
Nom |
Type |
Description |
|
query (obligatoire) |
|
Condition de requête. Définissez ce paramètre sur |
|
sort (facultatif) |
|
Ordre de tri des résultats. Pour plus d'informations, consultez la rubrique Trier et paginer les résultats. |
|
get_total_count (facultatif) |
|
La recherche vectorielle ne prend pas en charge le suivi du nombre total. Laissez ce paramètre défini sur |
|
next_token (facultatif) |
|
Jeton de pagination. Transmettez le |
|
offset (facultatif) |
|
Décalage de départ de la requête. Utilisez ce paramètre pour une pagination superficielle. |
|
limit (facultatif) |
|
Nombre maximal de lignes à renvoyer. Si ce paramètre est défini sur |
|
aggs (facultatif) |
|
Configurations d'agrégation de métriques. Pour plus d'informations, consultez la rubrique Agrégation. |
|
group_bys (facultatif) |
|
Configurations de regroupement. Pour plus d'informations, consultez la rubrique Agrégation. |
|
collapse_field (facultatif) |
|
Configuration de réduction des résultats. Pour plus d'informations, consultez la rubrique Réduire les résultats de requête. |
Condition de requête vectorielle
Le paramètre search_query.query est de type KnnVectorQuery et accepte les paramètres suivants.
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Nom du champ Vector. |
|
top_k (obligatoire) |
|
Nombre de vecteurs les plus proches à interroger. Valeur maximale : |
|
float32_query_vector (obligatoire) |
|
Vecteur de requête Float32 utilisé pour calculer la similarité. Sa longueur doit correspondre à la dimension du champ vectoriel. |
|
filter (facultatif) |
|
Condition non vectorielle que les données des plus proches voisins doivent également satisfaire. Utilisez |
|
weight (facultatif) |
|
Poids de la requête vectorielle, qui doit être supérieur ou égal à |
|
min_score (facultatif) |
|
Seuil de score minimal, qui doit être supérieur ou égal à |
|
num_candidates (facultatif) |
|
Nombre de candidats examinés sur chaque partition d'index. Valeurs valides : |
Colonnes de retour
Le paramètre columns_to_get est de type ColumnsToGet et accepte les paramètres suivants.
|
Nom |
Type |
Description |
|
column_names (facultatif) |
|
Noms des colonnes d'attributs à renvoyer. Spécifiez ce paramètre uniquement lorsque |
|
return_type (facultatif) |
|
Mode de retour des colonnes. |
Réponse
La méthode search renvoie un objet SearchResponse. Le tableau suivant décrit les champs principaux.
|
Champ |
Type |
Description |
|
rows |
|
Lignes renvoyées par la requête. Leur nombre ne dépasse pas la valeur de |
|
next_token |
|
Jeton pour la page suivante. Une valeur vide indique qu'aucune autre donnée n'est disponible. |
|
total_count |
|
La recherche vectorielle ne prend pas en charge le suivi du nombre total. N'utilisez pas ce champ. |
|
is_all_succeed |
|
Indique si toutes les partitions d'index ont été interrogées. Si la valeur est |
|
agg_results |
|
Résultats d'agrégation de métriques. Ce champ est vide si |
|
group_by_results |
|
Résultats de regroupement. Ce champ est vide si |
|
search_hits |
|
Résultats de recherche, incluant des informations étendues telles que les lignes, les scores de pertinence et les mises en évidence. |
Réponse compatible avec les tuples
À partir de la version 5.2.0 du SDK Tablestore pour Python, les API de recherche renvoient des objets de réponse au lieu de tuples. Les versions 5.1.0 et antérieures renvoient directement des tuples. Dans la version 5.2.1 et ultérieure, vous pouvez appeler la méthode SearchResponse.v1_response() pour obtenir un tuple compatible avec les versions précédentes. Pour le nouveau code, accédez directement aux attributs de SearchResponse afin d'éviter les erreurs de déballage si les champs de réponse sont étendus.
(
rows,
next_token,
total_count,
is_all_succeed,
agg_results,
group_by_results,
search_hits,
) = response.v1_response()Exemples
Filtrer par une condition non vectorielle et un score
L'exemple suivant renvoie les lignes des plus proches voisins dont le champ category commence par book- et dont le score vectoriel est supérieur à 0.1. Les trois premières lignes sont sélectionnées parmi 10 candidats sur chaque partition d'index.
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)