Esegui query sugli indici di Accesso privato ai servizi (peering di reti VPC) o Private Service Connect

Una volta eseguito il deployment di un endpoint di indice di peering di rete VPC o Private Service Connect, l'esecuzione di query è leggermente diversa a seconda della modalità di deployment:

Deployment con l'automazione di Private Service Connect

Per gli IndexEndpoints di cui è stato eseguito il deployment con l'automazione di Private Service Connect, l'SDK Python mapperà automaticamente la rete Private Service Connect all'endpoint appropriato. Se non utilizzi l'SDK Python, devi connetterti direttamente all'indirizzo IP creato per l'endpoint, seguendo le istruzioni per l'esecuzione di query su un deployment manuale di Private Service Connect.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API 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

Deployment con la configurazione manuale di Private Service Connect

Per gli IndexEndpoints IndexEndpoints di Private Service Connect di cui è stato eseguito il deployment con una connessione configurata manualmente, l'endpoint viene accessibile utilizzando l'indirizzo IP dell'indirizzo di calcolo inoltrato all'allegato di servizio Private Service Connect dell'endpoint.

Se non lo conosci già, puoi ottenere l'indirizzo IP inoltrato all'URI dell'allegato di servizio utilizzando i comandi gcloud ai index-endpoints describe e gcloud compute forwarding-rules list.

Assicurati di sostituire quanto segue:

  • INDEX_ENDPOINT_ID: ID endpoint di indice completo.
  • REGION: la regione in cui è stato eseguito il deployment dell'endpoint di indice.
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}"

L'output includerà l'indirizzo IP interno da utilizzare per eseguire query su IndexEndpoint.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API 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

Riga di comando

Per eseguire query su un DeployedIndex, connettiti al relativo TARGET_IP sulla porta 10000 e chiama il metodo Match o BatchMatch. Inoltre, puoi eseguire query utilizzando un ID embedding specifico.

Gli esempi seguenti utilizzano lo strumento open source grpc_cli per inviare richieste gRPC al server di indice di cui è stato eseguito il deployment.

Nel primo esempio, invii una singola query utilizzando il metodo Match. 

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

Nel secondo esempio, combini due query separate nella stessa richiesta 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,..]}]}]'

Devi effettuare chiamate a queste API da un client in esecuzione nello stesso VPC con cui è stato eseguito il peering del servizio.

Per eseguire una query utilizzando un embedding_id, utilizza l'esempio seguente.

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

In questo esempio, invii una query utilizzando restrizioni numeriche e di token.

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

Per saperne di più, consulta la sezione Librerie client spiegate.

Console

Utilizza queste istruzioni per eseguire query su un indice VPC dalla console.

  1. Nella sezione Piattaforma agente della Google Cloud console, vai a la sezione Esegui il deployment e utilizza. Seleziona Ricerca vettoriale.

    Vai a Ricerca vettoriale

  2. Seleziona l'indice VPC su cui vuoi eseguire query. Viene visualizzata la pagina Informazioni sull'indice.
  3. Scorri verso il basso fino alla sezione Indici di cui è stato eseguito il deployment e seleziona l'indice di cui è stato eseguito il deployment su cui vuoi eseguire query. Viene visualizzata la pagina Informazioni sull'indice di cui è stato eseguito il deployment.
  4. Nella sezione Esegui query sull'indice, seleziona i parametri di query. Puoi scegliere di eseguire query in base a un vettore o a un punto dati specifico.
  5. Esegui la query utilizzando lo strumento open source grpc_cli o l'SDK della piattaforma agente per Python.

Deployment con il peering di rete VPC

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.

Nota: l'SDK Python cerca automaticamente l'indirizzo IP di un IndexEndpoint di cui è stato eseguito il deployment con il peering di rete 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

Riga di comando

Ogni DeployedIndex ha un TARGET_IP, che puoi recuperare nel tuo elenco di IndexEndpoints.

Per eseguire query su un DeployedIndex, connettiti al relativo TARGET_IP sulla porta 10000 e chiama il metodo Match o BatchMatch. Inoltre, puoi eseguire query utilizzando un ID embedding specifico.

Gli esempi seguenti utilizzano lo strumento open source grpc_cli per inviare richieste gRPC al server di indice di cui è stato eseguito il deployment.

Nel primo esempio, invii una singola query utilizzando il metodo Match. 

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

Nel secondo esempio, combini due query separate nella stessa richiesta 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,..]}]}]'

Devi effettuare chiamate a queste API da un client in esecuzione nello stesso VPC con cui è stato eseguito il peering del servizio.

Per eseguire una query utilizzando un embedding_id, utilizza l'esempio seguente.

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

In questo esempio, invii una query utilizzando restrizioni numeriche e di token.

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

Per saperne di più, consulta la sezione Librerie client spiegate.

Console

Utilizza queste istruzioni per eseguire query su un indice VPC dalla console.

  1. Nella sezione Piattaforma agente della Google Cloud console, vai a la sezione Esegui il deployment e utilizza. Seleziona Ricerca vettoriale.

    Vai a Ricerca vettoriale

  2. Seleziona l'indice VPC su cui vuoi eseguire query. Viene visualizzata la pagina Informazioni sull'indice.
  3. Scorri verso il basso fino alla sezione Indici di cui è stato eseguito il deployment e seleziona l'indice di cui è stato eseguito il deployment su cui vuoi eseguire query. Viene visualizzata la pagina Informazioni sull'indice di cui è stato eseguito il deployment.
  4. Nella sezione Esegui query sull'indice, seleziona i parametri di query. Puoi scegliere di eseguire query in base a un vettore o a un punto dati specifico.
  5. Esegui la query utilizzando lo strumento open source grpc_cli o l'SDK della piattaforma agente per Python.

Impostazioni del tempo di query che influiscono sulle prestazioni

I seguenti parametri del tempo di query possono influire su latenza, disponibilità e costi quando utilizzi la ricerca vettoriale. Queste indicazioni si applicano alla maggior parte dei casi. Tuttavia, sperimenta sempre le tue configurazioni per assicurarti che funzionino per il tuo caso d'uso.

Per le definizioni dei parametri, consulta Parametri di configurazione dell'indice .

Parametro Informazioni Impatto sulle prestazioni
approximateNeighborsCount

Indica all'algoritmo il numero di risultati approssimativi da recuperare da ogni shard.

Il valore di approximateNeighborsCount deve essere sempre maggiore di il valore di setNeighborsCount. Se il valore di setNeighborsCount è piccolo, per approximateNeighborsCount è consigliato un valore 10 volte superiore. Per valori setNeighborsCount più grandi, è possibile utilizzare un moltiplicatore più piccolo.

Il nome dell'API REST corrispondente per questo campo è approximate_neighbor_count.

L'aumento del valore di approximateNeighborsCount può influire sulle prestazioni nei seguenti modi:

  • Richiamo: maggiore
  • Latenza: potenzialmente aumentata
  • Disponibilità: nessun impatto
  • Costo: può aumentare perché durante una ricerca vengono elaborati più dati

La riduzione del valore di approximateNeighborsCount può influire sulle prestazioni nei seguenti modi:

  • Richiamo: ridotto
  • Latenza: potenzialmente ridotta
  • Disponibilità: nessun impatto
  • Costo: può diminuire perché durante una ricerca vengono elaborati meno dati
setNeighborCount

Specifica il numero di risultati che vuoi che la query restituisca.

Il nome dell'API REST corrispondente per questo campo è neighbor_count.

I valori inferiori o uguali a 300 rimangono efficienti nella maggior parte dei casi d'uso. Per valori più grandi, esegui il test per il tuo caso d'uso specifico.

fractionLeafNodesToSearch Controlla la percentuale di nodi foglia da visitare durante la ricerca dei vicini più prossimi. Questo è correlato a leafNodeEmbeddingCount in che più embedding per nodo foglia, più dati esaminati per foglia.

Il nome dell'API REST corrispondente per questo campo è fraction_leaf_nodes_to_search_override.

L'aumento del valore di fractionLeafNodesToSearch può influire sulle prestazioni nei seguenti modi:

  • Richiamo: maggiore
  • Latenza: aumentata
  • Disponibilità: nessun impatto
  • Costo: può aumentare perché una latenza maggiore occupa più risorse macchina

La riduzione del valore di fractionLeafNodesToSearch può influire sulle prestazioni nei seguenti modi:

  • Richiamo: ridotto
  • Latenza: ridotta
  • Disponibilità: nessun impatto
  • Costo: può diminuire perché una latenza inferiore occupa meno risorse macchina

Passaggi successivi