Résoudre les problèmes de déploiement d'un agent

Ce document explique comment résoudre les erreurs que vous pouvez rencontrer lors du déploiement d'un agent dans Agent Runtime. Il couvre divers problèmes courants, y compris les échecs de sérialisation, les erreurs d'autorisation et les cas de non-respect des limites VPC-SC.

Remarque : Pour rechercher et filtrer les journaux d'erreurs de l'agent, utilisez l'explorateur de journaux, sélectionnez RESOURCE TYPE pour "Vertex AI Reasoning Engine", puis sélectionnez la valeur RESOURCE CONTAINER correspondante (c'est-à-dire le numéro de projet) et la valeur REASONING ENGINE ID.

Erreurs de modèle prédéfini

Si vous rencontrez des problèmes avec le modèle LangchainAgent lors du déploiement, cela peut être dû à l'un des problèmes décrits dans cette section.

Erreurs internes du serveur

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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

Malheureusement, il s'agit d'une erreur généralisée pour tout problème lié au conteneur au moment de l'exécution. La cause possible est l'une des nombreuses erreurs pouvant se produire.

Causes possibles :

  • État modifié sur LangchainAgent. Cela peut se produire si .set_up() a été appelé sur un LangchainAgent avant le déploiement de l'agent.
  • Versions de package incohérentes. Cela peut se produire si les packages installés dans l'environnement de développement sont différents de ceux installés dans l'environnement distant d'Agent Runtime.

Solutions recommandées :

  • État modifié sur LangchainAgent. Instanciez une nouvelle instance de LangchainAgent ou supprimez agent.set_up() du code avant de déployer l'agent.
  • Spécifications de package incohérentes. Consultez la section sur le dépannage des erreurs de sérialisation.

Erreurs de sérialisation

En général, il est important de s'assurer que les environnements "local" et "distant" sont synchronisés lors du déploiement de l'agent. Pour ce faire, spécifiez requirements= lorsque vous déployez l'agent.

Si vous rencontrez des problèmes de sérialisation (les erreurs liées au "pickle" ou au "pickling" sont synonymes d'erreurs de "sérialisation"), cela peut être dû à l'un des problèmes décrits dans cette section.

Version Pydantic

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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

Cause possible :

Cela peut se produire si votre package pydantic est antérieur à la version 2.6.4. Pour vérifier la version que vous utilisez, exécutez la commande suivante dans votre terminal :

pip show pydantic

Solution recommandée :

Mettez à jour votre package en exécutant la commande suivante dans le terminal :

pip install pydantic --upgrade

Exécutez la commande suivante dans votre terminal pour vérifier que vous utilisez la version 2.6.4 ou une version ultérieure :

pip show pydantic

Si vous êtes dans une instance de notebook (par exemple, Jupyter, Colab ou Workbench), vous devrez peut-être redémarrer votre environnement d'exécution pour utiliser les packages mis à jour.

Version Cloudpickle

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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

Cause possible :

Cela peut se produire si la version de votre package cloudpickle est différente dans votre environnement de développement et votre environnement de déploiement. Pour vérifier quelle version vous utilisez en développement, exécutez la commande suivante dans votre terminal :

pip show cloudpickle

Solution recommandée :

Déployez la même version de Cloudpickle dans les deux environnements (votre environnement de développement local et l'agent déployé à distance) en spécifiant requirements= lors du déploiement de l'agent.

Erreurs internes du serveur

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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

Cause possible :

Cela peut se produire si sys_version= est différent de l'environnement de développement lors du déploiement de l'agent.

Solution recommandée :

Après avoir déployé l'agent, envisagez de supprimer sys_version= des arguments d'entrée. Si le problème persiste, envoyez un rapport de bug.

Erreurs du bucket Cloud Storage

Si vous rencontrez des problèmes avec le bucket de préproduction Cloud Storage utilisé au moment du déploiement pour collecter et importer votre agent, cela peut être dû à l'une des raisons suivantes :

Erreurs liées aux autorisations

Solution recommandée :

Si vous souhaitez utiliser un bucket préexistant, assurez-vous que le compte principal authentifié pour utiliser Agent Platform (vous-même ou un compte de service) dispose d'un accès Storage Admin au bucket, et accordez des autorisations au compte de service.

Vous pouvez également spécifier un nouveau bucket lors du déploiement de l'agent afin que le SDK crée le bucket avec les autorisations nécessaires.

Si le problème persiste, envoyez un rapport de bug.

Le sous-répertoire du bucket Cloud Storage n'est pas créé

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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'erreur 404 se produit lorsque le système tente de copier dans un dossier qui n'existe pas.)

Cause possible :

Ce problème est probablement dû à un problème d'interpolation de chaîne dans les versions de google-cloud-aiplatform antérieures à la version 1.49.0. Ce problème est corrigé dans les versions ultérieures. Pour vérifier la version de google-cloud-aiplatform que vous utilisez, exécutez la commande suivante dans votre terminal :

pip show google-cloud-aiplatform

Solution recommandée :

Mettez à jour votre package en exécutant la commande suivante dans le terminal :

pip install google-cloud-aiplatform --upgrade

Vérifiez que vous utilisez la version 1.49.0 ou une version ultérieure de google-cloud-aiplatform en exécutant la commande suivante dans votre terminal :

pip show google-cloud-aiplatform

Si vous utilisez une instance de notebook (par exemple, Jupyter, Colab ou Workbench), vous devrez peut-être redémarrer votre environnement d'exécution avant de pouvoir utiliser les packages mis à jour.

Erreurs de non-respect de VPC-SC

Si vous rencontrez des problèmes avec VPC-SC, l'un des problèmes suivants peut en être la cause :

Erreurs liées aux autorisations

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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

ou :

Request is prohibited by organization's policy.

Cause possible :

Cela est probablement dû à l'absence de règles d'entrée requises dans le périmètre VPC-SC.

Solution recommandée :

Si vous utilisez Agent Platform dans un environnement VPC-SC, vous devez créer une règle d'entrée dans votre périmètre pour autoriser l'entrée de l'agent de service Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) dans les services storage.googleapis.com et artifactregistry.googleapis.com.

Erreurs liées aux comptes de service personnalisés

Si vous rencontrez des problèmes avec les comptes de service, l'un des problèmes suivants peut en être la cause :

Agir en tant que compte de service

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

You do not have permission to act as service_account.

Cause possible :

Il est possible que vous ne disposiez pas de l'autorisation iam.serviceAccounts.actAs sur le compte de service personnalisé utilisé pour le déploiement. Notez que dans un système multi-agents où il existe plusieurs comptes de service personnalisés, un auteur ou un déployeur d'agent peut agir en tant que certains des comptes de service. Si vous utilisez le mauvais compte de service, cette erreur est le comportement attendu.

Vous pouvez également rencontrer cette erreur si le compte de service personnalisé se trouve dans un projet différent de celui dans lequel vous déployez l'agent et si la règle d'administration iam.disableCrossProjectServiceAccountUsage est appliquée dans le projet du compte de service.

Pour obtenir la liste complète des configurations requises pour ce scénario, consultez Compte de service personnalisé multiprojet.

Solution recommandée :

Assurez-vous d'utiliser le compte de service prévu. Vérifiez si vous disposez du rôle Utilisateur du compte de service (roles/iam.serviceAccountUser) pour ce compte de service. Si ce n'est pas le cas, demandez à votre administrateur de vous attribuer le rôle pour ce compte de service.

Si vous êtes dans le scénario multi-projets, vérifiez si la règle d'administration iam.disableCrossProjectServiceAccountUsage est appliquée à votre projet de compte de service. Si c'est le cas, demandez à votre administrateur de désactiver la règle.

Serveur de métadonnées indisponible

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

ServiceUnavailable: 503 Getting metadata from plugin failed with error

ou

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

Cause possible :

Cela peut se produire si le compte de service personnalisé et votre agent se trouvent dans des projets différents, et si l'agent de service AI Platform Reasoning Engine ne dispose pas de l'autorisation iam.serviceAccounts.getAccessToken sur le compte de service personnalisé.

Pour obtenir la liste complète des configurations requises pour ce scénario, consultez Compte de service personnalisé multiprojet.

Solution recommandée :

Demandez à votre administrateur d'attribuer le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) à l'agent de service AI Platform Reasoning Engine du projet d'agent sur le compte de service personnalisé.

L'agent de service AI Platform Reasoning Engine doit se trouver dans le même projet que celui que vous utilisez pour déployer votre agent. La liaison IAM de l'attribution de rôle doit se trouver dans le projet où réside le compte de service personnalisé.

Erreurs d'épuisement des ressources ou de limitation du débit (erreur 429)

Problème :

Le déploiement échoue avec l'état Error 429 ou RESOURCE_EXHAUSTED.

Cause possible :

Le projet a dépassé ses limites de débit d'API ou ses quotas de requêtes simultanées.

Solutions recommandées :

  • Implémentez une stratégie d'intervalle exponentiel entre les tentatives dans les scripts de déploiement.
  • Vérifiez l'utilisation actuelle par rapport aux limites sur la page Google Cloud Quotas de l'API Agent Platform.
  • Réduisez la fréquence des déploiements simultanés.

Capacité maximale temporairement atteinte dans la région

Problème :

Le déploiement échoue avec un état 429 ou RESOURCE_EXHAUSTED et un message indiquant que la région est temporairement à pleine capacité pour une quantité totale de mémoire ou de processeur autorisée.

Cause possible :

Les déploiements d'agents dans une région s'appuient sur un pool de capacité de diffusion qu'Agent Runtime gère pour vous et que tous les clients de cette région partagent. Lorsque le pool est épuisé, les nouveaux déploiements dans cette région échouent jusqu'à ce que de la capacité se libère.

Cette limite ne fait pas partie des quotas de votre projet. Il n'apparaît pas sur la pageGoogle Cloud Quotas et ne peut pas être augmenté en demandant une augmentation de quota.

Solutions recommandées :

  • Déployez-le dans une autre région prise en charge. Il s'agit du moyen le plus rapide de débloquer un déploiement.
  • Vous devrez réessayer plus tard. Une région à pleine capacité est un problème temporaire qui se résout généralement de lui-même.
  • Demandez une quantité de mémoire ou de processeur plus petite pour votre agent. Un déploiement plus petit peut s'adapter à la capacité restante.
  • Contactez l'assistance si les déploiements dans une région continuent d'échouer de cette manière. Bien que nous ne puissions pas augmenter la limite, vos signalements nous aident à allouer la capacité là où elle est nécessaire.

Solutions qui ne s'appliquent pas :

  • La suppression de vos agents existants ne libère pas de capacité pour cette limite, car la capacité n'est pas consommée par votre projet seul.
  • Demander une augmentation de quota n'a aucun effet, car la limite n'est pas un quota de projet.

Le nombre maximal d'instances dépasse la limite régionale

Problème :

Le déploiement échoue avec un état 429 ou RESOURCE_EXHAUSTED et un message indiquant que spec.deployment_spec.max_instances dépasse le nombre maximal d'instances compatibles avec le processeur ou la mémoire demandés dans le resource_limits de la région.

Cause possible :

Lorsque vous déployez un agent, Agent Runtime multiplie spec.deployment_spec.max_instances par les valeurs cpu et memory par instance dans spec.deployment_spec.resource_limits, puis vérifie que l'allocation maximale de cet agent unique respecte la limite régionale du projet de diffusion sous-jacent. Si vous ne spécifiez pas max_instances, Agent Runtime applique une valeur par défaut (telle que 200), qui, dans les régions où les limites sont plus basses, peut dépasser le nombre maximal d'instances acceptées lorsqu'elle est multipliée par les valeurs cpu ou memory configurées par instance.

Solutions recommandées :

  • Définissez spec.deployment_spec.max_instances sur la valeur maximale indiquée dans le message d'erreur (ou une valeur inférieure).
  • Réduisez la valeur cpu ou memory par instance dans spec.deployment_spec.resource_limits.
  • Déployez l'agent dans une autre région prise en charge avec une limite plus élevée.

Solutions qui ne s'appliquent pas :

  • Demander une augmentation de quota sur la page "Quotas" de votre projet Google Cloud n'a aucun effet, car cette limite est appliquée au projet de diffusion géré par Google plutôt qu'à votre projet.
  • La suppression d'autres agents dans votre projet ou la nouvelle tentative sans modifier max_instances ni resource_limits ne résolvent pas cette erreur, car la vérification évalue l'allocation maximale du déploiement unique par rapport à une limite statique.

Erreurs d'accès à Secret Manager

Problème :

Le déploiement échoue avec un état 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) et un message semblable à celui-ci :

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).

Causes possibles :

  • NOT_FOUND : L'ID de secret ou l'ID de version spécifié dans secret_env n'existe pas dans Secret Manager dans le même projet que l'agent déployé, ou contient une faute de frappe.
  • DESTROYED ou DISABLED : la version du secret référencée dans Secret Manager est détruite ou désactivée.
  • PERMISSION_DENIED : le compte de service utilisé par l'agent ne dispose pas du rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le secret référencé.

Solutions recommandées :

  • Pour NOT_FOUND, DESTROYED ou DISABLED :
    1. Sur la page Secret Manager du projet dans lequel vous déployez l'agent, vérifiez que chaque SECRET_ID et VERSION_ID référencés dans secret_env existent et sont à l'état Activé.
    2. Si une version référencée a été désactivée ou détruite, activez une version valide ou mettez à jour secret_env pour référencer une version activée.
  • Pour PERMISSION_DENIED : Accordez le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le secret (ou le projet contenant le secret) au compte de service qui récupère le secret :
    • Compte de service par défaut : attribuez le rôle à l'agent de service AI Platform Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com).
    • Compte de service personnalisé : attribuez le rôle au compte de service personnalisé configuré sur l'agent.

Ressources d'assistance

Si votre problème n'est toujours pas résolu, consultez notre guide d'assistance pour obtenir de l'aide.