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. Copre una serie di problemi comuni, tra cui errori di serializzazione, errori di autorizzazione e violazioni del perimetro dei Controlli di servizio VPC.

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

Errori dei modelli predefiniti

Se riscontri problemi con il template LangchainAgent durante il deployment, il motivo potrebbe essere 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, si tratta di un errore generico per qualsiasi problema con il container in fase di runtime e la possibile causa è uno dei tanti errori che potrebbero verificarsi.

Possibili cause:

  • Stato non aggiornato su LangchainAgent. Questo potrebbe accadere se .set_up() è stato chiamato su un LangchainAgent prima di eseguire il deployment dell'agente.
  • Versioni dei pacchetti incoerenti. Questo potrebbe accadere se i pacchetti installati nell'ambiente di sviluppo sono diversi da quelli installati nell'ambiente remoto in Agent Runtime.

Soluzioni consigliate:

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= quando esegui il deployment dell'agente.

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

Versione 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:

Questo potrebbe accadere se il pacchetto pydantic è precedente alla versione 2.6.4. Per verificare 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 che stai utilizzando la versione 2.6.4 o una versione successiva:

pip show pydantic

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

Versione 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:

Questo potrebbe accadere se la versione del pacchetto cloudpickle è diversa nel tuo ambiente di sviluppo e nel tuo ambiente di deployment. Per controllare quale versione utilizzi in fase di 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 remoto, specificando requirements= quando esegui il 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 il 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 gestione temporanea di Cloud Storage utilizzato al momento del deployment per raccogliere e caricare l'agente, il motivo potrebbe essere uno dei seguenti:

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 l'accesso Storage Admin al bucket e concedi le autorizzazioni al service account.

In alternativa, puoi specificare un nuovo bucket durante il 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:

Questo è probabilmente dovuto a un problema con l'interpolazione di stringhe nelle versioni di google-cloud-aiplatform precedenti alla versione 1.49.0. Questo problema è stato risolto nelle versioni successive. Per verificare quale versione di google-cloud-aiplatform stai utilizzando, 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 successiva di google-cloud-aiplatform eseguendo questo comando nel terminale:

pip show google-cloud-aiplatform

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

Errori di violazione dei Controlli di servizio VPC

Se riscontri problemi con i Controlli di servizio VPC, 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'accesso dall'agente di servizio del motore di ragionamento (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) al servizio storage.googleapis.com e al servizio artifactregistry.googleapis.com.

Errori dei account di servizio personalizzati

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

Agisci 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 multi-agente in cui sono presenti più service account personalizzati, un autore o un deployer di agenti può agire come alcuni dei service account. Se utilizzi l'account di servizio 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 esegui il deployment dell'agente e la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage viene applicata nel progetto del account di servizio.

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

Soluzione consigliata:

Assicurati di utilizzare il account di servizio previsto. Verifica di disporre del ruolo Service Account User (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 tra progetti, verifica se nel progetto del account di servizio è applicata la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. In questo caso, chiedi all'amministratore di disattivare la policy.

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:

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

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

Soluzione consigliata:

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

L'agente di servizio del motore di ragionamento della piattaforma AI deve trovarsi nello stesso progetto che utilizzi per eseguire il deployment dell'agente. L'associazione IAM dell'assegnazione del ruolo deve trovarsi nel progetto in cui si trova il service account personalizzato.

Errori di esaurimento delle risorse o di limitazione di frequenza (errore 429)

Problema:

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

Possibile causa:

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

Soluzioni consigliate:

  • Implementa una strategia di backoff esponenziale e nuovi tentativi negli script di deployment.
  • Verifica l'utilizzo attuale rispetto ai limiti nella pagina Quote Cloud de Confiance per l'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 esaurito la capacità per una quantità totale consentita di memoria o CPU.

Possibile causa:

I deployment degli agenti in una regione attingono a un pool di capacità di gestione 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é non si libera capacità.

Questo limite non è una delle quote del progetto. Non viene visualizzato nella paginaCloud de Confiance 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ù rapido per sbloccare un deployment.
  • Riprova più tardi. Una regione con capacità esaurita è 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, le tue segnalazioni ci aiutano a indirizzare la capacità dove è necessaria.

Soluzioni non applicabili:

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

Il numero massimo di istanze supera il limite regionale

Problema:

Il deployment non riesce con uno 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 nella 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 distribuzione 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 configurati 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 più elevato.

Soluzioni non applicabili:

  • La richiesta di un aumento della quota nella pagina Quote Cloud de Confiance del tuo progetto non ha alcun effetto, perché questo limite viene applicato al progetto di gestione di Google, non al tuo.
  • L'eliminazione di altri agenti nel progetto o un 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 uno 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 si fa riferimento in Secret Manager è in stato di eliminazione o disabilitazione.
  • PERMISSION_DENIED: il account di servizio utilizzato dall'agente non dispone del ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) per il secret di 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 di riferimento è stata disabilitata o eliminata, abilita una versione valida o aggiorna secret_env in modo che faccia riferimento a una versione abilitata.
  • Per PERMISSION_DENIED: concedi il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul secret (o sul progetto contenente il secret) al account di servizio che recupera il secret:
    • Service account predefinito: concedi il ruolo all'agente di servizio del motore di ragionamento della piattaforma AI (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com).
    • Service account personalizzato: concedi il ruolo al service account personalizzato configurato sull'agente.

Timeout della build dell'immagine container

Problema:

Il deployment non riesce con uno stato 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) e un messaggio che indica che la creazione dell'immagine container dell'agente non è stata completata in tempo.

Possibili cause:

Quando esegui il deployment dai file di origine, Agent Runtime crea un'immagine container che installa il codice e le relative dipendenze. Il deployment non riesce se la build è ancora in esecuzione quando scade il tempo consentito. In genere, le build richiedono troppo tempo a causa delle dipendenze che installano, ad esempio:

  • Un lungo elenco di pacchetti in requirements, inclusi quelli che l'agente non utilizza.
  • Pacchetti senza wheel predefinite per l'ambiente di build, che vengono compilati dall'origine durante la build.
  • Versioni non bloccate o bloccate in modo approssimativo, che rallentano la risoluzione delle dipendenze.

Soluzioni consigliate:

  • Controlla i log di build collegati nel campo logs_url dei metadati di errore per vedere quale passaggio era in esecuzione quando la build è stata interrotta.
  • Rimuovi le dipendenze non necessarie e blocca le versioni di tutti i pacchetti richiesti.
  • Dai la priorità ai pacchetti e alle versioni che pubblicano wheel predefinite, in modo che non venga compilato nulla durante la build.
  • Riprova a eseguire il deployment. A volte una build può richiedere più tempo del solito per motivi non correlati al tuo codice.

Il container non è stato avviato in tempo

Problema:

Il deployment non riesce con uno stato 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) e un messaggio che indica che il container dell'agente non ha iniziato la pubblicazione in tempo.

Possibili cause:

Dopo aver creato l'immagine, Agent Runtime avvia il container dell'agente e attende che sia pronto per gestire le richieste. Il deployment non va a buon fine se il container è ancora in fase di avvio quando il tempo consentito si esaurisce. Le cause più comuni possono includere:

  • Lavoro lento al momento dell'importazione, ad esempio il caricamento di modelli o file di grandi dimensioni quando vengono importati i moduli dell'agente.
  • Attività lente o bloccanti nel metodo set_up() dell'agente, ad esempio chiamate di rete che attendono un servizio non raggiungibile.

Soluzioni consigliate:

  • Controlla i log del container collegati nel campo logs_url dei metadati dell'errore per vedere dove si è bloccato l'avvio.
  • Sposta l'inizializzazione costosa fuori dal tempo di importazione del modulo e riduci al minimo il numero di passaggi in set_up() fast. Rimanda il lavoro non necessario per gestire la prima richiesta.
  • Assicurati che tutti i servizi chiamati dall'agente durante l'avvio siano raggiungibili dall'agente e imposta i timeout per queste chiamate in modo che non possano bloccare l'avvio a tempo indeterminato.
  • Se i log del container mostrano che l'agente è stato avviato normalmente, riprova il deployment. A volte l'avvio può richiedere più tempo del solito per motivi non correlati al tuo codice.

Risorse di assistenza

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