Risolvere i problemi relativi al deployment di un agente

Questo documento descrive come risolvere gli errori che potresti riscontrare quando esegui 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.

Errori dei modelli predefiniti

Se riscontri problemi con il modello 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, questo è un errore generico per qualsiasi problema con il container in fase di runtime e la causa possibile è uno dei tanti errori che potrebbero verificarsi.

Possibili cause:

  • Stato modificato su LangchainAgent. Questo potrebbe accadere se .set_up() è stato chiamato su un LangchainAgent prima di distribuire l'agente.
  • Versioni dei pacchetti non coerenti. 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= durante 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 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:

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

Questo potrebbe accadere se la versione del pacchetto cloudpickle è diversa nell'ambiente di sviluppo e nell'ambiente di deployment. Per controllare la versione che stai utilizzando 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 nell'ambiente di sviluppo locale e nell'agente di cui è stato eseguito il deployment in remoto, specificando requirements= durante 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:

Questo potrebbe accadere se sys_version= è diverso dall'ambiente di sviluppo quando si esegue il deployment dell'agente.

Soluzione consigliata:

Dopo il deployment dell'agente, valuta la possibilità di rimuovere sys_version= dagli argomenti di input. Se continui a riscontrare problemi, invia una segnalazione di bug.

Errori del bucket Cloud Storage

Se riscontri problemi con il bucket gestione temporanea Cloud Storage utilizzato durante il 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 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 continui a riscontrare problemi, 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 inesistente.)

Possibile causa:

Questo è probabilmente dovuto a un problema di interpolazione delle stringhe nelle versioni di google-cloud-aiplatform precedenti alla versione 1.49.0. Questo problema è stato risolto nelle versioni successive. Per controllare la versione di google-cloud-aiplatform che 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 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, il motivo potrebbe essere uno dei seguenti:

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:

Questo è probabilmente dovuto alla mancanza delle regole di ingresso richieste nel perimetro VPC-SC.

Soluzione consigliata:

Se utilizzi Agent Platform in un ambiente VPC-SC, devi creare una regola di ingresso 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 dei account di servizio personalizzati

Se riscontri problemi con i service account, il motivo potrebbe essere uno dei seguenti:

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 avere l'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 il 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 se la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage è applicata nel progetto del account di servizio.

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

Soluzione consigliata:

Assicurati di utilizzare il account di servizio previsto. Verifica di avere il ruolo Utente account di servizio (roles/iam.serviceAccountUser) su questo service account. In caso contrario, chiedi all'amministratore di concederti il ruolo su 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 caso affermativo, chiedi all'amministratore di disattivare la policy.

Server dei metadati non disponibile

Problema:

Ricevi un messaggio di errore simile al seguente:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

oppure

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 se l'agente di servizio AI Platform Reasoning Engine non ha l'autorizzazione iam.serviceAccounts.getAccessToken sul account di servizio personalizzato.

Per l'elenco completo delle configurazioni richieste per questo scenario, consulta la sezione 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 account di servizio (roles/iam.serviceAccountTokenCreator) sul service account personalizzato.

L'agente di servizio AI Platform Reasoning Engine deve trovarsi nello stesso progetto che utilizzi per il deployment dell'agente. L'associazione IAM della concessione del ruolo deve essere nel progetto in cui risiede il service account personalizzato.

Errori di esaurimento delle risorse o di limite 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 delle 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 Google Cloud pagina Quote per l'"API Agent Platform".
  • Riduci la frequenza dei deployment simultanei.

Risorse di assistenza

Se il problema non è ancora stato risolto, consulta la nostra guida all'assistenza per ricevere aiuto.