Risolvere i problemi relativi al deployment di un agente

Questo documento descrive come risolvere gli errori che potresti riscontrare durante il deployment di un agente in Agent Runtime. Vengono trattati una serie di problemi comuni, tra cui errori di serializzazione, errori di autorizzazione e violazioni dei limiti VPC-SC.

Nota: per cercare e filtrare i log degli errori dell'agente, utilizza Esplora log, seleziona RESOURCE TYPE per "Vertex AI Reasoning Engine" e seleziona il valore RESOURCE CONTAINER corrispondente (ovvero il numero di progetto) e il valore REASONING ENGINE ID.

Errori nei modelli predefiniti

Se riscontri problemi con il template LangchainAgent durante il deployment, il motivo potrebbe essere attribuito a uno dei problemi descritti in questa sezione.

Errori interni del server

Problema:

Ricevi un messaggio di errore simile al seguente:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Purtroppo, questo è un errore generico per qualsiasi problema con il contenitore in fase di runtime e la possibile causa è uno dei tanti errori che potrebbero verificarsi.

Possibili cause:

  • Stato modificato il giorno LangchainAgent. Ciò potrebbe accadere se .set_up() è stato chiamato su un LangchainAgent prima del deployment dell'agente.
  • Versioni del pacchetto incoerenti. Ciò potrebbe accadere se i pacchetti installati nell'ambiente di sviluppo sono diversi da quelli installati nell'ambiente remoto in Agent Runtime.

Soluzioni consigliate:

  • Stato modificato il giorno LangchainAgent. Crea un'istanza nuova di LangchainAgent o rimuovi agent.set_up() dal codice prima di implementare l'agente.
  • Specifiche del pacchetto non coerenti. Consulta la sezione sulla risoluzione dei problemi relativi agli errori di serializzazione.

Errori di serializzazione

In generale, è importante assicurarsi che gli ambienti "locale" e "remoto" siano sincronizzati durante il deployment dell'agente. Puoi assicurarti che ciò avvenga specificando requirements= durante il deployment dell'agente.

Se riscontri problemi di serializzazione (gli errori relativi a "pickle" o "pickling" sono sinonimi di errori di "serializzazione"), il motivo potrebbe essere attribuito a uno dei problemi descritti in questa sezione.

Versione di Pydantic

Problema:

Ricevi un messaggio di errore simile al seguente:

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

Possibile causa:

Ciò può accadere se il pacchetto pydantic è precedente alla versione 2.6.4. Per controllare la versione in uso, esegui questo comando nel terminale:

pip show pydantic

Soluzione consigliata:

Aggiorna il pacchetto eseguendo questo comando nel terminale:

pip install pydantic --upgrade

Esegui questo comando nel terminale per verificare di utilizzare la versione 2.6.4 o successive:

pip show pydantic

Se ti trovi in un'istanza notebook (ad esempio Jupyter, Colab o Workbench), potresti dover riavviare il runtime per utilizzare i pacchetti aggiornati.

Versione di Cloudpickle

Problema:

Ricevi un messaggio di errore simile al seguente:

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

Possibile causa:

Ciò può accadere se la versione del pacchetto cloudpickle è diversa nell'ambiente di sviluppo e nell'ambiente di deployment. Per controllare quale versione utilizzi durante lo sviluppo, esegui questo comando nel terminale:

pip show cloudpickle

Soluzione consigliata:

Esegui il deployment della stessa versione di cloudpickle in entrambi gli ambienti, ad esempio l'ambiente di sviluppo locale e l'agente di cui è stato eseguito il deployment da remoto, specificando requirements= durante l'esecuzione del deployment dell'agente.

Errori interni del server

Problema:

Ricevi un messaggio di errore simile al seguente:

InternalServerError: 500 Revision YYY is not ready and cannot serve traffic.

Possibile causa:

Ciò potrebbe accadere se sys_version= è diverso dall'ambiente di sviluppo durante la deployment dell'agente.

Soluzione consigliata:

Dopo aver eseguito il deployment dell'agente, valuta la possibilità di rimuovere sys_version= dagli argomenti di input. Se i problemi persistono, invia una segnalazione di bug.

Errori del bucket Cloud Storage

Se riscontri problemi con il bucket di staging Cloud Storage utilizzato al momento del deployment per raccogliere e caricare l'agente, il problema potrebbe essere dovuto a uno dei seguenti motivi:

Errori di autorizzazione

Soluzione consigliata:

Se vuoi utilizzare un bucket preesistente, assicurati che l'entità autenticata per utilizzare Agent Platform (tu o un account di servizio) abbia accesso Storage Admin al bucket e concedi le autorizzazioni al service account.

In alternativa, puoi specificare un nuovo bucket durante la deployment dell'agente e l'SDK creerà il bucket con le autorizzazioni necessarie.

Se i problemi persistono, invia una segnalazione di bug.

La sottodirectory del bucket Cloud Storage non viene creata

Problema:

Ricevi un messaggio di errore simile al seguente:

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

L'errore 404 si verifica quando il sistema tenta di copiare in una cartella che non esiste.

Possibile causa:

Ciò è probabilmente dovuto a un problema di interpolazione di stringhe nelle versioni di google-cloud-aiplatform precedenti alla versione 1.49.0. Questo problema è risolto nelle versioni successive. Per controllare la versione di google-cloud-aiplatform che utilizzi, esegui questo comando nel terminale:

pip show google-cloud-aiplatform

Soluzione consigliata:

Aggiorna il pacchetto eseguendo questo comando nel terminale:

pip install google-cloud-aiplatform --upgrade

Verifica di utilizzare la versione 1.49.0 o successive di google-cloud-aiplatform eseguendo questo comando nel terminale:

pip show google-cloud-aiplatform

Se utilizzi un'istanza notebook (ad esempio Jupyter, Colab o Workbench), potresti dover riavviare il runtime prima di poter utilizzare i pacchetti aggiornati.

Errori di violazione VPC-SC

Se riscontri problemi con VPC-SC, la causa potrebbe essere uno dei seguenti problemi:

Errori di autorizzazione

Problema:

Ricevi un messaggio di errore simile al seguente:

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

oppure:

Request is prohibited by organization's policy.

Possibile causa:

Ciò è probabilmente dovuto alla mancanza delle regole in entrata richieste nel perimetro VPC-SC.

Soluzione consigliata:

Se utilizzi Agent Platform in un ambiente VPC-SC, devi creare una regola in entrata nel perimetro per consentire l'ingresso dall'agente di servizio Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) nel servizio storage.googleapis.com e nel servizio artifactregistry.googleapis.com.

Errori del account di servizio personalizzato

Se riscontri problemi con i service account, la causa potrebbe essere uno dei seguenti problemi:

Agire come account di servizio

Problema:

Ricevi un messaggio di errore simile al seguente:

You do not have permission to act as service_account.

Possibile causa:

Potresti non disporre dell'autorizzazione iam.serviceAccounts.actAs sul account di servizio personalizzato utilizzato per il deployment. Tieni presente che in un sistema multiagente in cui sono presenti più service account personalizzati, un autore o un deployer di agenti può agire come alcuni dei service account. Se utilizzi ilaccount di serviziot sbagliato, questo errore è il comportamento previsto

Inoltre, potresti riscontrare questo errore se il account di servizio personalizzato si trova in un progetto diverso da quello in cui viene eseguito il deployment dell'agente e se il criterio dell'organizzazione iam.disableCrossProjectServiceAccountUsage è applicato nel progetto del account di servizio.

Per l'elenco completo delle configurazioni richieste per questo scenario, consulta Service account personalizzato tra progetti.

Soluzione consigliata:

Assicurati di utilizzare il account di servizio previsto. Verifica di disporre del ruolo Utente service account (roles/iam.serviceAccountUser) per questo service account. In caso contrario, chiedi all'amministratore di concederti il ruolo per questo service account.

Se ti trovi nello scenario cross-project, verifica se nel progetto del account di servizio è applicata la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. In questo caso, chiedi all'amministratore di disattivare il criterio.

Server di metadati non disponibile

Problema:

Ricevi un messaggio di errore simile al seguente:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

o

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

Possibile causa:

Ciò può verificarsi se il account di servizio personalizzato e l'agente si trovano in progetti diversi e l'agente di servizio AI Platform Reasoning Engine non dispone dell'autorizzazione iam.serviceAccounts.getAccessToken sul account di servizio personalizzato.

Per l'elenco completo delle configurazioni richieste per questo scenario, consulta Service account personalizzato tra progetti.

Soluzione consigliata:

Chiedi all'amministratore di concedere all'agente di servizio AI Platform Reasoning Engine del progetto dell'agente il ruolo Creatore token service account (roles/iam.serviceAccountTokenCreator) sul account di servizio personalizzato.

L'agente di servizio del motore di ragionamento di AI Platform deve trovarsi nello stesso progetto che utilizzi per il deployment dell'agente. Il binding IAM della concessione del ruolo deve trovarsi nel progetto in cui risiede il service account personalizzato.

Errori relativi all'esaurimento delle risorse o alla limitazione della frequenza (errore 429)

Problema:

Il deployment non riesce con lo stato Error 429 o RESOURCE_EXHAUSTED.

Possibile causa:

Il progetto ha superato i limiti di frequenza API o le quote di richiesta in parallelo.

Soluzioni consigliate:

  • Implementa una strategia di backoff esponenziale e di nuovi tentativi negli script di deployment.
  • Verifica l'utilizzo attuale rispetto ai limiti nella pagina Google Cloud Quote dell'API Agent Platform.
  • Riduci la frequenza dei deployment simultanei.

Regione temporaneamente al completo

Problema:

Il deployment non riesce con uno stato 429, RESOURCE_EXHAUSTED e un messaggio che indica che la regione ha temporaneamente raggiunto la capacità per una quantità totale consentita di memoria o CPU.

Possibile causa:

I deployment degli agenti in una regione utilizzano un pool di capacità di servizio che Agent Runtime gestisce per tuo conto e che tutti i clienti di quella regione condividono. Quando il pool è esaurito, i nuovi deployment in quella regione non vanno a buon fine finché la capacità non viene liberata.

Questo limite non fa parte delle quote del tuo progetto. Non viene visualizzato nella paginaGoogle Cloud Quote e non può essere aumentato richiedendo un aumento della quota.

Soluzioni consigliate:

  • Esegui il deployment in un'altra regione supportata. Questo è il modo più veloce per sbloccare un deployment.
  • Riprova più tardi. Una regione al massimo della capacità è un problema temporaneo che di solito si risolve da solo.
  • Richiedi una quantità inferiore di memoria o CPU per l'agente. Un deployment più piccolo potrebbe rientrare nella capacità rimanente.
  • Contatta l'assistenza se i deployment in una regione continuano a non riuscire in questo modo. Anche se non possiamo aumentare il limite, i tuoi report ci aiutano a indirizzare la capacità dove è necessaria.

Soluzioni che non si applicano:

  • L'eliminazione degli agenti esistenti non libera capacità per questo limite, perché la capacità non viene consumata solo dal tuo progetto.
  • La richiesta di aumento della quota non ha effetto perché il limite non è una quota del progetto.

Il numero massimo di istanze supera il limite regionale

Problema:

Il deployment non riesce con lo stato 429, RESOURCE_EXHAUSTED e un messaggio che indica che spec.deployment_spec.max_instances supera il numero massimo di istanze supportate per la CPU o la memoria richieste in resource_limits della regione.

Possibile causa:

Quando esegui il deployment di un agente, Agent Runtime moltiplica spec.deployment_spec.max_instances per cpu e memory per istanza in spec.deployment_spec.resource_limits e verifica che l'allocazione di picco di questo singolo agente rientri nel limite regionale del progetto di pubblicazione sottostante. Se non specifichi max_instances, Agent Runtime applica un valore predefinito (ad esempio 200), che nelle regioni con limiti inferiori può superare il numero massimo di istanze supportate se moltiplicato per cpu o memory configurato per istanza.

Soluzioni consigliate:

  • Imposta spec.deployment_spec.max_instances sul valore massimo mostrato nel messaggio di errore (o su un valore inferiore).
  • Riduci il valore cpu o memory per istanza in spec.deployment_spec.resource_limits.
  • Esegui il deployment dell'agente in un'altra regione supportata con un limite superiore.

Soluzioni che non si applicano:

  • La richiesta di aumento della quota nella pagina Quote del progetto Google Cloud non ha effetto, perché questo limite viene applicato al progetto di pubblicazione gestito da Google anziché al tuo progetto.
  • L'eliminazione di altri agenti nel progetto o il nuovo tentativo senza modificare max_instances o resource_limits non risolve questo errore, perché il controllo valuta l'allocazione di picco del singolo deployment rispetto a un limite statico.

Errori di accesso a Secret Manager

Problema:

Il deployment non riesce con stato 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) e un messaggio simile al seguente:

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

Possibili cause:

  • NOT_FOUND: l'ID secret o l'ID versione specificato in secret_env non esiste in Secret Manager nello stesso progetto dell'agente di cui è stato eseguito il deployment o contiene un errore di battitura.
  • DESTROYED o DISABLED: la versione del secret a cui viene fatto riferimento in Secret Manager è in uno stato distrutto o disabilitato.
  • PERMISSION_DENIED: il account di servizio utilizzato dall'agente non ha il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) per il secret a cui viene fatto riferimento.

Soluzioni consigliate:

  • Per NOT_FOUND, DESTROYED o DISABLED:
    1. Nella pagina Secret Manager del progetto in cui stai eseguendo il deployment dell'agente, verifica che ogni SECRET_ID e VERSION_ID a cui viene fatto riferimento in secret_env esista e sia nello stato Abilitato.
    2. Se una versione a cui viene fatto riferimento è stata disattivata o eliminata, attiva una versione valida o aggiorna secret_env in modo che faccia riferimento a una versione attiva.
  • Per PERMISSION_DENIED: Concedi il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) al secret (o al progetto che contiene il secret) al account di servizio che recupera il secret:
    • Service account predefinito: concedi il ruolo al service agent AI Platform Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com).
    • Service account personalizzato: concedi il ruolo al service account personalizzato configurato sull'agente.

Risorse di assistenza

Se il problema persiste, consulta la nostra guida all'assistenza per ricevere aiuto.