Vector search - Tablestore SDK for Python - Tablestore - Centro de documentación de Alibaba Cloud

Utilice Tablestore SDK for Python para obtener datos de vecinos más cercanos desde un índice de búsqueda según la similitud vectorial.

Requisitos previos

Instale Tablestore SDK for Python e inicialice un cliente.

La función de búsqueda vectorial requiere la versión 5.4.4 del SDK o posterior. Se recomienda utilizar la versión más reciente del SDK.

Debe haber creado un search index que contenga un campo Vector para la tabla de datos.

Descripción

La búsqueda vectorial realiza un cálculo de vecino más cercano aproximado (ANN) entre un vector de consulta y los vectores de un campo Vector. Los resultados se puntúan mediante la métrica de distancia configurada en el índice de búsqueda y se devuelven los datos de los vecinos más cercanos. La dimensión del campo debe coincidir con la dimensión del vector de consulta.

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

En el siguiente ejemplo se consultan las tres filas más cercanas a un vector especificado de cuatro dimensiones y se devuelven en orden descendente según la puntuación vectorial.

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)

Importante

No establezca get_total_count en True para la búsqueda vectorial. Existen límites aplicables al número y las dimensiones de los campos vectoriales, así como a top_k. Para obtener más información, consulte Search index limits.

Parámetros

Solicitud de búsqueda

El método search incluye los siguientes parámetros.

Nombre	Tipo	Descripción
table_name (obligatorio)	`str`	Nombre de la tabla de datos.
index_name (obligatorio)	`str`	Nombre del índice de búsqueda.
search_query (obligatorio)	`SearchQuery`	Condición de consulta y configuraciones generales de la misma.
columns_to_get (opcional)	`ColumnsToGet`	Configuración de columnas a devolver. Si no se especifica este parámetro, solo se devuelven las columnas de clave principal.
routing_keys (opcional)	`list`	Valores de clave principal de los campos de enrutamiento personalizado. Este parámetro no es necesario si no se ha configurado el enrutamiento personalizado.
timeout_s (opcional)	`int`	Tiempo de espera de la solicitud en segundos. Si no se especifica este parámetro, se utiliza el tiempo de espera definido a nivel de cliente.

Configuración de la consulta

search_query es de tipo SearchQuery e incluye los siguientes parámetros.

Nombre	Tipo	Descripción
query (obligatorio)	`Query`	Condición de consulta. Establezca este parámetro en `KnnVectorQuery`.
sort (opcional)	`Sort`	Orden de clasificación de los resultados. Para obtener más información, consulte Sort and paginate results.
get_total_count (opcional)	`bool`	La búsqueda vectorial no admite el recuento total. Mantenga este parámetro establecido en `False`.
next_token (opcional)	`bytes`	Token de paginación. Pase el valor de `next_token` de la respuesta anterior para recuperar la página siguiente. Cada partición de índice del lado del servidor devuelve sus propios valores más cercanos según `top_k`, los cuales son fusionados por el coordinador. Por lo tanto, al paginar mediante `next_token`, la cantidad acumulada de filas devueltas depende del número de particiones de índice del lado del servidor.
offset (opcional)	`int`	Desplazamiento desde el cual comienza la consulta. Utilice este parámetro para una paginación superficial.
limit (opcional)	`int`	Número máximo de filas a devolver. Si este parámetro se establece en `0`, no se devuelve ninguna fila.
aggs (opcional)	`list[Agg]`	Configuraciones de agregación de métricas. Para obtener más información, consulte Aggregation.
group_bys (opcional)	`list[BaseGroupBy]`	Configuraciones de agrupamiento. Para obtener más información, consulte Aggregation.
collapse_field (opcional)	`Collapse`	Configuración de colapso de resultados. Para obtener más información, consulte Collapse query results.

Condición de consulta vectorial

search_query.query es de tipo KnnVectorQuery e incluye los siguientes parámetros.

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Nombre del campo Vector.
top_k (obligatorio)	`int`	Cantidad de vectores más cercanos a consultar. Valor máximo: `1000`.
float32_query_vector (obligatorio)	`list[float]`	Vector de consulta Float32 utilizado para calcular la similitud. Su longitud debe ser igual a la dimensión del campo vectorial.
filter (opcional)	`Query`	Condición no vectorial que también deben cumplir los datos de vecinos más cercanos. Utilice `BoolQuery` para combinar condiciones.
weight (opcional)	`float`	Peso de la consulta vectorial, que debe ser mayor o igual a `0`. Valor predeterminado: `1.0`. Afecta las puntuaciones pero no la coincidencia.
min_score (opcional)	`float`	Umbral de puntuación mínima, que debe ser mayor o igual a `0`. Solo se devuelven las filas con puntuaciones estrictamente mayores a este valor.
num_candidates (opcional)	`int`	Número de candidatos visitados en cada partición de índice. Valores válidos: `[top_k, 1000]`. Un valor mayor puede mejorar la recuperación, pero también incrementar la latencia.

Columnas a devolver

columns_to_get es de tipo ColumnsToGet e incluye los siguientes parámetros.

Nombre	Tipo	Descripción
column_names (opcional)	`list[str]`	Nombres de las columnas de atributos a devolver. Especifique este parámetro únicamente cuando `return_type` sea `SPECIFIED`.
return_type (opcional)	`ColumnReturnType`	Modo de devolución de columnas. `NONE` (predeterminado) devuelve solo columnas de clave principal; `SPECIFIED` devuelve las columnas de atributos especificadas; `ALL` devuelve todas las columnas de atributos de la tabla; y `ALL_FROM_INDEX` devuelve todos los campos almacenados en el índice.

Respuesta

El método search devuelve SearchResponse. En la siguiente tabla se describen los campos principales.

Campo	Tipo	Descripción
rows	`list[Row]`	Filas devueltas por la consulta. La cantidad no supera el valor de `limit`.
next_token	`bytes`	Token para la página siguiente. Un valor vacío indica que no hay más datos disponibles.
total_count	`int`	La búsqueda vectorial no admite el recuento total. No utilice este campo.
is_all_succeed	`bool`	Indica si se consultaron todas las particiones de índice. Si el valor es `False`, se devuelven resultados parciales.
agg_results	`list[AggResult]`	Resultados de la agregación de métricas. Este campo está vacío si no se configura `aggs`.
group_by_results	`list[GroupByResult]`	Resultados del agrupamiento. Este campo está vacío si no se configura `group_bys`.
search_hits	`list[SearchHit]`	Coincidencias de búsqueda, que incluyen información extendida como filas, puntuaciones de relevancia y resaltados.

Respuesta compatible con tuplas

A partir de la versión 5.2.0 de Tablestore SDK for Python, las API de búsqueda devuelven objetos de respuesta en lugar de tuplas. Las versiones 5.1.0 y anteriores devuelven tuplas directamente. En la versión 5.2.1 y posteriores, puede llamar a SearchResponse.v1_response() para obtener una tupla compatible con versiones anteriores. Para código nuevo, acceda directamente a los atributos de SearchResponse y evite errores de desempaquetado si se amplían los campos de respuesta.

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

Ejemplos

Filtrar por condición no vectorial y puntuación

En el siguiente ejemplo se devuelven las filas vecinas más cercanas cuyo campo category comienza con book- y cuya puntuación vectorial es mayor que 0.1. Se seleccionan las tres filas principales de entre 10 candidatos en cada partición de índice.

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)