Consulta los índices de acceso privado a servicios (intercambio de tráfico de VPC) o Private Service Connect

Una vez que hayas implementado un extremo de índice de Private Service Connect o de intercambio de tráfico entre redes de VPC, la consulta diferirá ligeramente según cómo se haya implementado:

Implementado con la automatización de Private Service Connect

En el caso de IndexEndpoints implementado con la automatización de Private Service Connect, el SDK de Python asignará automáticamente la red de Private Service Connect al extremo adecuado. Si no usas el SDK de Python, debes conectarte directamente a la dirección IP creada para tu extremo siguiendo las instrucciones para consultar una implementación manual de Private Service Connect.

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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python. 

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

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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.
        ip_address (str): Required. The IP address of the PSC endpoint. Obtained
        from the created compute address used in the fordwarding rule to the
        endpoint's service attachment.
        psc_network (str): The network the endpoint was deployed to via PSC
        automation configuration. The format is
        projects/{project_id}/global/networks/{network_name}.

    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 matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors,
        psc_network=psc_network
    )
    return resp

Implementado con la configuración manual de Private Service Connect

En el caso de IndexEndpoints de Private Service Connect implementado con una conexión configurada de forma manual, se accede a tu extremo con la dirección IP de la dirección de procesamiento reenviado al archivo adjunto de servicio de Private Service Connect de tu extremo.

Si aún no la conoces, puedes obtener la dirección IP reenviado al URI del archivo adjunto del servicio con los comandos gcloud ai index-endpoints describe y gcloud compute forwarding-rules list.

Realiza los siguientes reemplazos:

  • INDEX_ENDPOINT_ID: Es el ID del extremo de índice completamente calificado.
  • REGION: Es la región en la que se implementa tu extremo de índice.
SERVICE_ATTACHMENT_URI=`gcloud ai index-endpoints describe INDEX_ENDPOINT_ID \
  --region=REGION \
  --format="value(deployedIndexes.privateEndpoints.serviceAttachment)"`

gcloud compute forwarding-rules list --filter="TARGET:${SERVICE_ATTACHMENT_URI}"

El resultado incluirá la dirección IP interna que se usará cuando se consulte IndexEndpoint.

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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python. 

def vector_search_match_psc_manual(
    project: str,
    location: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    queries: List[List[float]],
    num_neighbors: int,
    ip_address: str,
) -> List[List[aiplatform.matching_engine.matching_engine_index_endpoint.MatchNeighbor]]:
    """Query the vector search index deployed with PSC manual configuration.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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.
        ip_address (str): Required. The IP address of the PSC endpoint. Obtained
        from the created compute address used in the forwarding rule to the
        endpoint's service attachment.

    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
    )

    # Set the IP address of the PSC endpoint.
    my_index_endpoint.private_service_connect_ip_address = ip_address

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=queries,
        num_neighbors=num_neighbors
    )
    return resp

Línea de comandos

Para consultar un DeployedIndex, conéctate a su TARGET_IP en el puerto 10000 y llama a los métodos Match o BatchMatch. Además, puedes realizar consultas con un ID de incorporación específico.

En los siguientes ejemplos, se usa la herramienta de código abierto grpc_cli para enviar solicitudes de gRPC al servidor de índice implementado.

En el primer ejemplo, envías una sola consulta con el método Match. 

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]'

En el segundo ejemplo, combina dos consultas separadas en la misma solicitud BatchMatch. 

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}, {deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.2,..]}]}]'

Debes realizar llamadas a estas APIs desde un cliente que se ejecute en la misma [VPC con la que el servicio intercambia tráfico](#vpc-network-peering-setup).

Para ejecutar una consulta con un embedding_id, usa el siguiente ejemplo.

./grpc_cli call ${TARGET_IP}:10000  google.cloud.aiplatform.container.v1.MatchService.Match "deployed_index_id:'"test_index1"',embedding_id: '"606431"'"

En este ejemplo, envías una consulta con restricciones numéricas y de tokens.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{name: "double-ns", value_double: 0.3, op: LESS_EQUAL}, {name: "double-ns", value_double: -1.2, op: GREATER}, {name: "double-ns", value_double: 0., op: NOT_EQUAL}], restricts: [{name: "color", allow_tokens: ["red"]}]'

Para obtener más información, consulta Explicación de las bibliotecas cliente.

Console

Usa estas instrucciones para consultar un índice de VPC desde la consola.

  1. En la sección de Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Elige Vector Search

    Ir a Búsqueda de vectores

  2. Selecciona el índice de VPC 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 los parámetros de consulta. Puedes elegir hacer una consulta por vector o por dato específico.
  5. Ejecuta la consulta con la herramienta de código abierto grpc_cli o a través del SDK de Vertex AI para Python.

Implementado con el intercambio de tráfico entre redes de VPC

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. Si deseas obtener más información, consulta la documentación de referencia de la API de Python.

Nota: El SDK de Python busca automáticamente la dirección IP de un IndexEndpoint implementado con el intercambio de tráfico entre redes de VPC.

def vector_search_match_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.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        index_endpoint_name (str): Required. Index endpoint to run the query
        against. The endpoint must be a private endpoint.
        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
    )

    # Example queries containing 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]
        ),
    ]

    # Query the index endpoint for matches.
    resp = my_index_endpoint.match(
        deployed_index_id=deployed_index_id,
        queries=hybrid_queries,
        num_neighbors=num_neighbors,
    )
    return resp

Línea de comandos

Cada DeployedIndex tiene un TARGET_IP que puedes recuperar en tu lista de IndexEndpoints.

Para consultar un DeployedIndex, conéctate a su TARGET_IP en el puerto 10000 y llama a los métodos Match o BatchMatch. Además, puedes realizar consultas con un ID de incorporación específico.

En los siguientes ejemplos, se usa la herramienta de código abierto grpc_cli para enviar solicitudes de gRPC al servidor de índice implementado.

En el primer ejemplo, envías una sola consulta con el método Match. 

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]'

En el segundo ejemplo, combina dos consultas separadas en la misma solicitud BatchMatch. 

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", requests: [{deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.1,..]}, {deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [-0.2,..]}]}]'

Debes realizar llamadas a estas APIs desde un cliente que se ejecute en la misma [VPC con la que el servicio intercambia tráfico](#vpc-network-peering-setup).

Para ejecutar una consulta con un embedding_id, usa el siguiente ejemplo.

./grpc_cli call ${TARGET_IP}:10000  google.cloud.aiplatform.container.v1.MatchService.Match "deployed_index_id:'"test_index1"',embedding_id: '"606431"'"

En este ejemplo, envías una consulta con restricciones numéricas y de tokens.

./grpc_cli call ${TARGET_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.Match 'deployed_index_id: "${DEPLOYED_INDEX_ID}", float_val: [1, 1], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}, numeric_restricts: [{name: "double-ns", value_double: 0.3, op: LESS_EQUAL}, {name: "double-ns", value_double: -1.2, op: GREATER}, {name: "double-ns", value_double: 0., op: NOT_EQUAL}], restricts: [{name: "color", allow_tokens: ["red"]}]'

Para obtener más información, consulta Explicación de las bibliotecas cliente.

Console

Usa estas instrucciones para consultar un índice de VPC desde la consola.

  1. En la sección de Vertex AI de la consola de Google Cloud, ve a la sección Implementación y uso. Elige Vector Search

    Ir a Búsqueda de vectores

  2. Selecciona el índice de VPC 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 los parámetros de consulta. Puedes elegir hacer una consulta por vector o por dato específico.
  5. Ejecuta la consulta con la herramienta de código abierto grpc_cli o a través del SDK de Vertex AI para Python.

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.

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.

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.

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

¿Qué sigue?