Monitora le operazioni a lunga esecuzione

Questa pagina descrive come gestire il ciclo di vita di un'operazione a lunga esecuzione (LRO) in Vertex AI Agent Builder.

Un oggetto operazione a lunga esecuzione viene restituito quando una chiamata a un metodo potrebbe richiedere molto tempo per essere completata. Ad esempio, l'API Vertex AI Agent Builder crea un'operazione a lunga esecuzione quando chiami documents.import tramite l'API o le librerie client. L'operazione monitora lo stato del job di elaborazione.

Puoi utilizzare i metodi per le operazioni a lungo termine forniti dall'API Vertex AI Agent Builder per controllare lo stato delle operazioni. Puoi anche elencare o eseguire il polling delle operazioni.

Il record di un'operazione viene conservato per circa 30 giorni dal suo completamento, il che significa che non puoi visualizzare o elencare un'operazione dopo questo periodo di tempo.

Visualizzare i dettagli di un'operazione a lunga esecuzione

Di seguito viene mostrato come recuperare i dettagli di un'operazione.

REST

Per conoscere lo stato e visualizzare i dettagli di un'operazione a lunga esecuzione, segui questi passaggi:

  1. Trova il nome dell'operazione in due modi:

    • Dopo aver eseguito una chiamata a un metodo che restituisce un'operazione di lunga durata, esamina la risposta.

      Ad esempio, se chiami documents.import, l'inizio della risposta sarà simile al seguente:

      {
  "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportDocumentsMetadata"
  }
}

      Il valore name nella risposta fornisce il nome dell'operazione, che può essere utilizzato per eseguire query sullo stato dell'operazione. Non includere le virgolette quando copi il nome dell'operazione.

    • Ottieni il nome dell'operazione elencando le operazioni a lunga esecuzione.

  2. Chiama il metodo operations.get sulla risorsa che ha creato l'operazione:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1beta/OPERATION_NAME"

    OPERATION_NAME: il nome dell'operazione del passaggio precedente.

    Le prime righe della risposta del comando GET sono simili alle seguenti:

    {
  "operations": [
    {
      "name": "projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.ImportDocumentsMetadata",
      }
    }
  ]
}

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def get_operation_sample(operation_name: str) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)
    operation = client.get_operation(request=request)

    # Print the Operation Information
    print(operation)

    return operation

Elenca le operazioni a lunga esecuzione

Di seguito viene mostrato come elencare le operazioni per una risorsa Google Cloud.

REST

Per elencare le operazioni a lungo termine per una risorsa Google Cloud, segui questo passaggio:

  • Chiama il metodo operations.list:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/operations"

    DATA_STORE_ID: l'ID del datastore di Vertex AI Agent Builder creato con il tuo motore. Nell'URL della console Google Cloud, l'ID del datastore viene visualizzato dopo engines/ e prima di /data.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from typing import Optional

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION"  # Options: "global"
# search_engine_id = "YOUR_SEARCH_ENGINE_ID"

# Create filter in https://google.aip.dev/160 syntax
# operations_filter = "YOUR_FILTER"


def list_operations_sample(
    project_id: str,
    location: str,
    search_engine_id: str,
    operations_filter: Optional[str] = None,
) -> operations_pb2.ListOperationsResponse:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # The full resource name of the search engine branch.
    name = f"projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{search_engine_id}"

    # Make ListOperations request
    request = operations_pb2.ListOperationsRequest(
        name=name,
        filter=operations_filter,
    )

    # Make ListOperations request
    response = client.list_operations(request=request)

    # Print the Operation Information
    for operation in response.operations:
        print(operation)

    return response

Eseguire il polling di un'operazione a lunga esecuzione

Di seguito viene mostrato come eseguire il polling dello stato di un'operazione.

REST

Per eseguire il polling dell'operazione a lunga esecuzione termine fino al completamento:

  1. Esegui il seguente comando, che chiama ripetutamente il metodo operations.get, utilizzando un backoff di 10 secondi tra ogni richiesta:

    while true; \
    do curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://discoveryengine.googleapis.com/v1beta/OPERATION_NAME"; \
    sleep 10; \
    done

    OPERATION_NAME: il nome dell'operazione, disponibile in Ottenere dettagli su un'operazione a lunga esecuzione. Ad esempio: projects/12345/locations/global/collections/default_collection/dataStores/my-datastore_4321/branches/0/operations/import-documents-56789

  2. Interrompi il job di polling (Control+Z) quando lo stato è "done": true.

Python

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from time import sleep

from google.cloud import discoveryengine
from google.longrunning import operations_pb2

# TODO(developer): Uncomment these variables before running the sample.
# Example: `projects/{project}/locations/{location}/collections/{default_collection}/dataStores/{search_engine_id}/branches/{0}/operations/{operation_id}`
# operation_name = "YOUR_OPERATION_NAME"


def poll_operation_sample(
    operation_name: str, limit: int = 10
) -> operations_pb2.Operation:
    # Create a client
    client = discoveryengine.DocumentServiceClient()

    # Make GetOperation request
    request = operations_pb2.GetOperationRequest(name=operation_name)

    for _ in range(limit):
        operation = client.get_operation(request=request)
        # Print the Operation Information
        print(operation)

        # Stop polling when Operation is no longer running
        if operation.done:
            break

        # Wait 10 seconds before polling again
        sleep(10)

    return operation