Indexe für den Zugriff auf private Dienste (VPC-Netzwerk-Peering) oder Private Service Connect abfragen

Nachdem Sie einen VPC-Netzwerk-Peering- oder Private Service Connect-Indexendpunkt bereitgestellt haben, unterscheidet sich die Abfrage je nach Bereitstellungsmethode:

Mit Private Service Connect-Automatisierung bereitgestellt

Bei IndexEndpoints die mit der Private Service Connect-Automatisierung bereitgestellt wurden, ordnet das Python SDK das Private Service Connect Netzwerk automatisch dem entsprechenden Endpunkt zu. Wenn Sie das Python SDK nicht verwenden, müssen Sie direkt eine Verbindung zur erstellten IP-Adresse für Ihren Endpunkt herstellen. Folgen Sie dazu der Anleitung zum Abfragen einer manuellen Private Service Connect-Bereitstellung.

Python

Informationen zur Installation des Vertex AI SDK for Python finden Sie unter Vertex AI SDK for Python installieren. Weitere Informationen finden Sie in der Python API-Referenzdokumentation. 

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

Mit manueller Private Service Connect-Konfiguration bereitgestellt

Bei Private Service Connect IndexEndpoints die mit einer manuell konfigurierten Verbindung bereitgestellt wurden, wird auf Ihren Endpunkt über die IP-Adresse der Compute-Adresse zugegriffen, die an den Private Service Connect-Dienstanhang Ihres Endpunkts weitergeleitet wird.

Wenn Sie die IP-Adresse noch nicht kennen, können Sie sie mit den gcloud ai index-endpoints describe und gcloud compute forwarding-rules list Befehlen abrufen.

Ersetzen Sie die folgenden Werte:

  • INDEX_ENDPOINT_ID: Voll qualifizierte Indexendpunkt-ID.
  • REGION: Die Region, in der Ihr Indexendpunkt bereitgestellt wird.
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}"

Die Ausgabe enthält die interne IP-Adresse, die beim Abfragen des IndexEndpoint verwendet werden soll.

Python

Informationen zur Installation des Vertex AI SDK for Python finden Sie unter Vertex AI SDK for Python installieren. Weitere Informationen finden Sie in der Python API-Referenzdokumentation. 

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

Befehlszeile

Zum Abfragen eines DeployedIndex stellen Sie eine Verbindung zu seiner TARGET_IP an Port 10000 her und rufen die Methode Match oder BatchMatch auf. Außerdem können Sie mit einer bestimmten Einbettungs-ID abfragen.

In den folgenden Beispielen wird das Open-Source-Tool grpc_cli verwendet, um gRPC -Anfragen an den bereitgestellten Indexserver zu senden.

Im ersten Beispiel senden Sie eine einzelne Abfrage mit der Methode Match. 

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

Im zweiten Beispiel kombinieren Sie zwei separate Abfragen in derselben BatchMatch-Anfrage. 

./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,..]}]}]'

Sie müssen diese APIs von einem Client aus aufrufen, der in derselben VPC ausgeführt wird, zu der eine Peering-Verbindung des Dienstes hergestellt wurde.

Verwenden Sie das folgende Beispiel, um eine Abfrage mit einer embedding_id auszuführen.

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

In diesem Beispiel senden Sie eine Abfrage mit Token- und numerischen Einschränkungen.

./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"]}]'

Weitere Informationen finden Sie unter Erläuterung zu Clientbibliotheken.

Console

Folgen Sie dieser Anleitung, um einen VPC-Index über die Console abzufragen.

  1. Wechseln Sie im Abschnitt „Agent Platform“ der Google Cloud Console zum Abschnitt Bereitstellen und verwenden. Wählen Sie Vektorsuche aus.

    Zur Vektorsuche

  2. Wählen Sie den VPC-Index aus, den Sie abfragen möchten. Die Seite Indexinformationen wird geöffnet.
  3. Scrollen Sie nach unten zum Bereich Bereitgestellte Indexe und wählen Sie den bereitgestellten Index aus, den Sie abfragen möchten. Die Seite Informationen zum bereitgestellten Index wird geöffnet.
  4. Wählen Sie im Bereich Index abfragen Ihre Suchparameter aus. Sie können nach einem Vektor oder einem bestimmten Datenpunkt abfragen.
  5. Führen Sie die Abfrage mit dem Open-Source-Tool grpc_cli oder mit dem Agent Platform SDK for Python aus.

Mit VPC-Netzwerk-Peering bereitgestellt

Python

Informationen zur Installation des Vertex AI SDK for Python finden Sie unter Vertex AI SDK for Python installieren. Weitere Informationen finden Sie in der Python API-Referenzdokumentation.

Hinweis:Das Python SDK sucht automatisch die IP-Adresse für einen IndexEndpoint, der mit VPC-Netzwerk-Peering bereitgestellt wurde.

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

Befehlszeile

Jeder DeployedIndex hat eine TARGET_IP, die Sie in Ihrer Liste der IndexEndpoints abrufen können.

Zum Abfragen eines DeployedIndex stellen Sie eine Verbindung zu seiner TARGET_IP an Port 10000 her und rufen die Methode Match oder BatchMatch auf. Außerdem können Sie mit einer bestimmten Einbettungs-ID abfragen.

In den folgenden Beispielen wird das Open-Source-Tool grpc_cli verwendet, um gRPC -Anfragen an den bereitgestellten Indexserver zu senden.

Im ersten Beispiel senden Sie eine einzelne Abfrage mit der Methode Match. 

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

Im zweiten Beispiel kombinieren Sie zwei separate Abfragen in derselben BatchMatch-Anfrage. 

./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,..]}]}]'

Sie müssen diese APIs von einem Client aus aufrufen, der in derselben VPC ausgeführt wird, zu der eine Peering-Verbindung des Dienstes hergestellt wurde.

Verwenden Sie das folgende Beispiel, um eine Abfrage mit einer embedding_id auszuführen.

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

In diesem Beispiel senden Sie eine Abfrage mit Token- und numerischen Einschränkungen.

./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"]}]'

Weitere Informationen finden Sie unter Erläuterung zu Clientbibliotheken.

Console

Folgen Sie dieser Anleitung, um einen VPC-Index über die Console abzufragen.

  1. Wechseln Sie im Abschnitt „Agent Platform“ der Google Cloud Console zum Abschnitt Bereitstellen und verwenden. Wählen Sie Vektorsuche aus.

    Zur Vektorsuche

  2. Wählen Sie den VPC-Index aus, den Sie abfragen möchten. Die Seite Indexinformationen wird geöffnet.
  3. Scrollen Sie nach unten zum Bereich Bereitgestellte Indexe und wählen Sie den bereitgestellten Index aus, den Sie abfragen möchten. Die Seite Informationen zum bereitgestellten Index wird geöffnet.
  4. Wählen Sie im Bereich Index abfragen Ihre Suchparameter aus. Sie können nach einem Vektor oder einem bestimmten Datenpunkt abfragen.
  5. Führen Sie die Abfrage mit dem Open-Source-Tool grpc_cli oder mit dem Agent Platform SDK for Python aus.

Einstellungen beim Abfragezeitpunkt, die sich auf die Leistung auswirken

Die folgenden Parameter für die Abfragezeit können sich bei der Verwendung der Vektorsuche auf Latenz, Verfügbarkeit und Kosten auswirken. Diese Empfehlung gilt in den meisten Fällen. Testen Sie jedoch immer mit Ihren Konfigurationen, ob sie sich für Ihren Anwendungsfall eignen.

Informationen zu Parameterdefinitionen finden Sie unter Parameter für die Indexkonfiguration.

Parameter Info Auswirkungen auf die Leistung
approximateNeighborsCount

Gibt dem Algorithmus die Anzahl der ungefähren Ergebnisse an, die von jedem Shard abgerufen werden sollen.

Der Wert von approximateNeighborsCount muss immer größer als der Wert von setNeighborsCount sein. Wenn der Wert von setNeighborsCount klein ist, wird für approximateNeighborsCount das 10-Fache dieses Werts empfohlen. Bei größeren setNeighborsCount Werten kann ein kleinerer Multiplikator verwendet werden.

Der entsprechende REST API-Name für dieses Feld ist approximate_neighbor_count.

Wenn Sie den Wert von approximateNeighborsCount erhöhen, kann sich das so auf die Leistung auswirken:

  • Recall: Erhöht
  • Latenz: Möglicherweise erhöht
  • Verfügbarkeit: Keine Auswirkung
  • Kosten: Kann steigen, da während einer Suche mehr Daten verarbeitet werden

Wenn Sie den Wert von approximateNeighborsCount verringern, kann sich das so auf die Leistung auswirken:

  • Recall: Verringert
  • Latenz: Verringert sich möglicherweise
  • Verfügbarkeit: Keine Auswirkung
  • Kosten: Kann die Kosten senken, da während einer Suche weniger Daten verarbeitet werden
setNeighborCount

Gibt die Anzahl der Ergebnisse an, die durch die Abfrage zurückgegeben werden sollen.

Der entsprechende REST API-Name für dieses Feld ist neighbor_count.

Werte unter oder gleich 300 bleiben in den meisten Anwendungsfällen leistungsfähig. Bei größeren Werten sollten Sie für Ihren spezifischen Anwendungsfall testen.

fractionLeafNodesToSearch Steuert den Prozentsatz der Blattknoten, die bei der Suche nach nächsten Nachbarn besucht werden. Dies steht in Bezug auf die leafNodeEmbeddingCount in insofern, als je mehr Einbettungen pro Blattknoten umso mehr Daten pro Blatt untersucht werden.

Der entsprechende REST API-Name für dieses Feld ist fraction_leaf_nodes_to_search_override.

Wenn Sie den Wert von fractionLeafNodesToSearch erhöhen, kann sich das so auf die Leistung auswirken:

  • Recall: Erhöht
  • Latenz: Erhöht
  • Verfügbarkeit: Keine Auswirkung
  • Kosten: Kann steigen, da eine höhere Latenz mehr Maschinenressourcen belegt

Das Verringern des Werts von fractionLeafNodesToSearch kann sich auf folgende Weise auf die Leistung auswirken:

  • Recall: Verringert
  • Latenz: Verringert
  • Verfügbarkeit: Keine Auswirkung
  • Kosten: Kann sich verringern, da eine geringere Latenz weniger Maschinenressourcen belegt

Nächste Schritte