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

Una vez que hayas creado y desplegado el índice, podrás ejecutar consultas para obtener los vecinos más cercanos.

A continuación, se muestran algunos ejemplos de consultas de coincidencia para encontrar los vecinos más cercanos mediante el algoritmo de k vecinos más cercanos (k-NN).

Consultas de ejemplo para el endpoint público

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API 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

Los publicEndpointDomainName que se indican a continuación se encuentran en Implementar y tienen 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 http(s), aunque el endpoint público admite el protocolo dual 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 hacer 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"]}]}}]}'
  

Consola

Sigue estas instrucciones para consultar un índice desplegado en un endpoint público desde la consola.

1. En la sección Vertex AI de la Google Cloud consola, ve a la sección Desplegar y usar. Selecciona Búsqueda vectorial.

   Ir a Vector Search

2. Selecciona el índice que quieras consultar. Se abrirá la página Información del índice.
3. Desplázate hacia abajo hasta la sección Índices implementados y selecciona el índice implementado que quieras consultar. Se abrirá la página Información del índice implementado.
4. En la sección Indexación de consultas, seleccione si quiere hacer consultas por un valor de embedding denso, un valor de embedding disperso, un valor de embedding híbrido (embeddings densos y dispersos) o un punto de datos específico.
5. Introduce los parámetros de consulta del tipo de consulta que hayas seleccionado. Por ejemplo, si vas a hacer una consulta por una incrustación densa, introduce el vector de incrustación por el que quieres hacer la consulta.
6. Ejecuta la consulta con el comando curl proporcionado o ejecutándola con Cloud Shell.
7. Si usas Cloud Shell, selecciona Ejecutar en Cloud Shell.
8. Ejecuta el comando en Cloud Shell.
9. Los resultados devuelven los vecinos más cercanos.

Consultas híbridas

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

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API 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 filtros y aglomeraciones

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

Los límites por vecino de agrupamiento pueden aumentar la diversidad de los resultados limitando el número de resultados devueltos de cualquier etiqueta de agrupamiento de sus datos de índice.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API 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,
    )

Ajustes de tiempo de consulta que influyen en el rendimiento

Los siguientes parámetros de tiempo de consulta pueden afectar a la latencia, la disponibilidad y el coste al usar la búsqueda vectorial. Estas directrices se aplican a la mayoría de los casos. Sin embargo, siempre debes experimentar con tus configuraciones para asegurarte de que funcionan en tu caso práctico.

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

Parámetro	Información	Impacto en el rendimiento
approximateNeighborsCount	Indica al algoritmo el número de resultados aproximados que se deben obtener de cada fragmento. El valor de approximateNeighborsCount siempre debe ser mayor que el valor de setNeighborsCount. Si el valor de setNeighborsCount es pequeño, se recomienda que el valor de approximateNeighborsCount sea 10 veces mayor. Para valores de setNeighborsCount más grandes, se puede usar un multiplicador más pequeño. El nombre de la API REST correspondiente a este campo es approximate_neighbor_count.	Si aumentas el valor de approximateNeighborsCount, el rendimiento puede verse afectado de las siguientes formas: Recuperación: aumentada Latencia: puede aumentar Disponibilidad: sin impacto Coste: puede aumentar porque se procesan más datos durante una búsqueda. Si reduces el valor de approximateNeighborsCount, el rendimiento puede verse afectado de las siguientes formas: Recuperación: disminuida Latencia: puede disminuir Disponibilidad: sin impacto Coste: puede reducir el coste porque se procesan menos datos durante una búsqueda.
setNeighborCount	Especifica el número de resultados que quieres que devuelva la consulta. El nombre de la API REST correspondiente a este campo es neighbor_count.	Los valores inferiores o iguales a 300 siguen siendo eficaces en la mayoría de los casos prácticos. Si los valores son más altos, haz pruebas para tu caso práctico específico.
fractionLeafNodesToSearch	Controla el porcentaje de nodos hoja que se visitarán al buscar los vecinos más cercanos. Esto está relacionado con el leafNodeEmbeddingCount, ya que cuantos más embeddings haya por nodo hoja, más datos se examinarán por hoja. El nombre de la API REST correspondiente a este campo es fraction_leaf_nodes_to_search_override.	Aumentar el valor de fractionLeafNodesToSearch puede afectar al rendimiento de las siguientes formas: Recuperación: aumentada Latencia: aumentada Disponibilidad: sin impacto Coste: puede aumentar porque una latencia más alta ocupa más recursos de la máquina. Disminuir el valor de fractionLeafNodesToSearch puede afectar al rendimiento de las siguientes formas: Recuperación: disminuida Latencia: se ha reducido Disponibilidad: sin impacto Coste: puede disminuir porque una latencia más baja ocupa menos recursos de la máquina.