Risolvere i problemi di implementazione di un agente

Questo documento mostra come risolvere gli errori che potresti riscontrare durante l'implementazione di un agente.

Errori nei modelli predefiniti

Se riscontri problemi con il template LangchainAgent durante l'implementazione, 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 XXX 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 sporco il giorno LangchainAgent. Ciò potrebbe accadere se .set_up() è stato chiamato su un LangchainAgent prima del deployment dell'agente.
  • Versioni del pacchetto non coerenti. Ciò potrebbe accadere se i pacchetti installati nell'ambiente di sviluppo sono diversi da quelli installati nell'ambiente remoto in Vertex AI Agent Engine.

Soluzione o soluzioni consigliate:

  • Stato sporco 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 relativa alla risoluzione dei problemi degli 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 sia così specificando requirements= quando esegui 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ò potrebbe 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 la versione che 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 XXX is not ready and cannot serve traffic.

Possibile causa:

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

Soluzione consigliata:

Dopo aver deployato l'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 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 Vertex AI (tu o un account di servizio) disponga dell'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 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 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), potrebbe essere necessario 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 di traffico in entrata richieste nel perimetro VPC-SC.

Soluzione consigliata:

Se utilizzi Vertex AI Agent Engine 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 relativi al account di servizio personalizzato

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 per ilaccount di serviziot 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 responsabile del deployment 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 l'account di servizio personalizzato si trova in un progetto diverso da quello in cui viene eseguito il deployment dell'agente e i criteri dell'organizzazione iam.disableCrossProjectServiceAccountUsage sono applicati nel progetto dell'account di servizio.

Consulta la pagina 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 Utente service account (roles/iam.serviceAccountUser) in questo service account. In caso contrario, chiedi all'amministratore di concederti il ruolo su 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 le norme.

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ò accadere 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 per ilaccount di serviziot personalizzato.

Consulta la pagina 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 service account (roles/iam.serviceAccountTokenCreator) sul account di servizio personalizzato.

L'agente di servizio AI Platform Reasoning Engine 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.

Risorse di assistenza

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