Consulta un índice público para obtener los vecinos más cercanos

Después de crear e implementar el índice, puedes ejecutar consultas para obtener los vecinos más cercanos.

Estos son algunos ejemplos de una consulta de coincidencia para encontrar los vecinos más cercanos mediante el algoritmo de k-vecinos más cercanos (k-NN).

Ejemplos de consultas para el extremo público

Python

Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API de Python.

def vector_search_find_neighbors(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """Query the vector search index.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        queries (List[List[float]]): Required. A list of queries. Each query is
        a list of floats, representing a single embedding.
        num_neighbors (int): Required. The number of neighbors to return.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query the index endpoint for the nearest neighbors.
    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
    )

Línea de comandos

El publicEndpointDomainName que aparece a continuación se encuentra en Implementar y tiene el formato <number>.<region>-<number>.vdb.vertexai.goog.


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://1957880287.us-central1-181224308459.vdb.vertexai.goog/v1/projects/181224308459/locations/us-central1/indexEndpoints/3370566089086861312:findNeighbors -d '{deployed_index_id: "test_index_public1", queries: [{datapoint: {datapoint_id: "0", feature_vector: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]}, neighbor_count: 5}]}'
  

En este ejemplo de curl, se muestra cómo llamar desde clientes de http(s), aunque el extremo público admite el protocolo doble para RESTful y grpc_cli.


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://1957880287.us-central1-181224308459.vdb.vertexai.goog/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}:readIndexDatapoints -d '{deployed_index_id:"test_index_public1", ids: ["606431", "896688"]}'
  

En este ejemplo de curl, se muestra cómo realizar consultas con restricciones de token y numéricas.


  $ curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors -d '{deployed_index_id:"${DEPLOYED_INDEX_ID}", queries: [{datapoint: {datapoint_id:"x", feature_vector: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{namespace: "int-ns", value_int: -2, op: "GREATER"}, {namespace: "int-ns", value_int: 4, op: "LESS_EQUAL"}, {namespace: "int-ns", value_int: 0, op: "NOT_EQUAL"}], restricts: [{namespace: "color", allow_list: ["red"]}]}}]}'
  

Console

Usa estas instrucciones para consultar un índice implementado en un extremo público desde la consola.

  1. En la sección Vertex AI de la consola de Google Cloud , ve a la sección Implementación y uso. Selecciona Búsqueda de vectores.

    Ir a Búsqueda de vectores

  2. Selecciona el índice que deseas consultar. Se abrirá la página Index info.
  3. Desplázate hacia abajo hasta la sección Índices implementados y selecciona el índice implementado que deseas consultar. Se abrirá la página Deployed index info.
  4. En la sección Query index, selecciona si deseas realizar la búsqueda por un valor de incorporación denso, un valor de incorporación disperso, un valor de incorporación híbrido (incorporaciones densas y dispersas) o un dato específico.
  5. Ingresa los parámetros de la consulta para el tipo de consulta que seleccionaste. Por ejemplo, si realizas una consulta por un embedding denso, ingresa el vector de embedding por el que deseas realizar la consulta.
  6. Ejecuta la consulta con el comando curl proporcionado o a través de la ejecución con Cloud Shell.
  7. Si usas Cloud Shell, selecciona Ejecutar en Cloud Shell.
  8. Ejecuta en Cloud Shell.
  9. Los resultados muestran los vecinos más cercanos.

Consultas híbridas

La búsqueda híbrida usa embeddings densos y dispersos para las búsquedas basadas en una combinación de búsqueda de palabras clave y búsqueda semántica.

Python

Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API de Python.

def vector_search_find_neighbors_hybrid_queries(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    num_neighbors: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """Query the vector search index using example hybrid queries.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        num_neighbors (int): Required. The number of neighbors to return.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query hybrid datapoints, sparse-only datapoints, and dense-only datapoints.
    hybrid_queries = [
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            dense_embedding=[1, 2, 3],
            sparse_embedding_dimensions=[10, 20, 30],
            sparse_embedding_values=[1.0, 1.0, 1.0],
            rrf_ranking_alpha=0.5,
        ),
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            dense_embedding=[1, 2, 3],
            sparse_embedding_dimensions=[10, 20, 30],
            sparse_embedding_values=[0.1, 0.2, 0.3],
        ),
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            sparse_embedding_dimensions=[10, 20, 30],
            sparse_embedding_values=[0.1, 0.2, 0.3],
        ),
        aiplatform.matching_engine.matching_engine_index_endpoint.HybridQuery(
            dense_embedding=[1, 2, 3]
        ),
    ]

    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=hybrid_queries,
        num_neighbors=num_neighbors,
    )

Consultas con filtrado y amontonamiento

Filtrar coincidencias de vectores te permite restringir los resultados de los vecinos más cercanos a categorías específicas. Los filtros también pueden designar categorías para excluir de tus resultados.

Los límites de vecinos por multiplicidad pueden aumentar la diversidad de los resultados, ya que limitan la cantidad de resultados que se muestran a partir de una sola etiqueta de multiplicidad en los datos de tu índice.

Python

Si deseas obtener información para instalar o actualizar el SDK de Vertex AI para Python, consulta Instala el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API de Python.

def vector_search_find_neighbors_filtering_crowding(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    filter: List[aiplatform.matching_engine.matching_engine_index_endpoint.Namespace],
    numeric_filter: List[
        aiplatform.matching_engine.matching_engine_index_endpoint.NumericNamespace
    ],
    per_crowding_attribute_neighbor_count: int,
) -> List[
    List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]
]:
    """Query the vector search index with filtering and crowding.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against.
        deployed_index_id (str): Required. The ID of the DeployedIndex to run
        the queries against.
        queries (List[List[float]]): Required. A list of queries. Each query is
        a list of floats, representing a single embedding.
        num_neighbors (int): Required. The number of neighbors to return.
        filter (List[Namespace]): Required. A list of Namespaces for filtering
        the matching results. For example,
        [Namespace("color", ["red"], []), Namespace("shape", [], ["square"])]
        will match datapoints that satisfy "red color" but not include
        datapoints with "square shape".
        numeric_filter (List[NumericNamespace]): Required. A list of
        NumericNamespaces for filtering the matching results. For example,
        [NumericNamespace(name="cost", value_int=5, op="GREATER")] will limit
        the matching results to datapoints with cost greater than 5.
        per_crowding_attribute_neighbor_count (int): Required. The maximum
        number of returned matches with the same crowding tag.

    Returns:
        List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]] - A list of nearest neighbors for each query.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index endpoint instance from an existing endpoint.
    my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Query the index endpoint for the nearest neighbors.
    return my_index_endpoint.find_neighbors(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        filter=filter,
        numeric_filter=numeric_filter,
        per_crowding_attribute_neighbor_count=per_crowding_attribute_neighbor_count,
    )

Configuración del tiempo de consulta que afecta el rendimiento

Los siguientes parámetros de tiempo de consulta pueden afectar la latencia, la disponibilidad y el costo cuando se usa Vector Search. Esta guía se aplica en la mayoría de los casos. Sin embargo, siempre experimenta con tus opciones de configuración a fin de asegurarte de que funcionen para tu caso de uso.

Para ver las definiciones de parámetros, consulta Parámetros de configuración de índices.

Parámetro Acerca de Impacto en el rendimiento
approximateNeighborsCount

Indica al algoritmo la cantidad de resultados aproximados que se recuperarán de cada fragmentación.

El valor de approximateNeighborsCount siempre debe ser mayor que el de setNeighborsCount. Si el valor de setNeighborsCount es pequeño, se recomienda usar 10 veces ese valor para approximateNeighborsCount. Para valores setNeighborsCount mayores, se puede usar un multiplicador más pequeño.

El nombre de la API de REST correspondiente a este campo es approximate_neighbor_count.

Aumentar el valor de approximateNeighborsCount puede afectar el rendimiento de las siguientes maneras:

  • Recuperación: Aumentada
  • Latencia: Posiblemente mayor
  • Disponibilidad: Sin impacto
  • Costo: Puede aumentar porque se procesan más datos durante una búsqueda

Disminuir el valor de approximateNeighborsCount puede afectar el rendimiento de las siguientes maneras:

  • Recuperación: Disminuida
  • Latencia: Posibles disminuciones
  • Disponibilidad: Sin impacto
  • Costo: puede disminuir el costo porque se procesan menos datos durante una búsqueda
setNeighborCount

Especifica la cantidad de resultados que deseas que muestre la consulta.

El nombre de la API de REST correspondiente a este campo es neighbor_count.

Los valores inferiores o iguales a 300 siguen teniendo un rendimiento en la mayoría de los casos de uso. Para valores más altos, prueba tu caso de uso específico.

fractionLeafNodesToSearch Controla el porcentaje de nodos de hoja que se visitarán cuando se busquen vecinos más cercanos. Esto se relaciona con leafNodeEmbeddingCount, ya que cuantas más incorporaciones por nodo de hoja, más datos se examinan por hoja.

El nombre de la API de REST correspondiente a este campo es fraction_leaf_nodes_to_search_override.

Aumentar el valor de fractionLeafNodesToSearch puede afectar el rendimiento de las siguientes maneras:

  • Recuperación: Aumentada
  • Latencia: Mayor
  • Disponibilidad: Sin impacto
  • Costo: Puede aumentar porque una latencia más alta ocupa más recursos de máquina

Disminuir el valor de fractionLeafNodesToSearch puede afectar el rendimiento de las siguientes maneras:

  • Recuperación: Disminuida
  • Latencia: Disminuida
  • Disponibilidad: Sin impacto
  • Costo: Puede disminuir porque una latencia más baja ocupa menos recursos de máquina