Ce document explique comment résoudre les erreurs que vous pouvez rencontrer lors du déploiement d'un agent sur Agent Runtime. Il couvre divers problèmes courants, y compris les échecs de sérialisation, les erreurs d'autorisation et les violations de périmètre VPC-SC.
Remarque : Pour rechercher et filtrer les journaux d'erreurs de l'agent, utilisez l'explorateur de journaux, sélectionnez RESOURCE TYPE pour "Moteur de raisonnement Vertex AI", 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 unLangchainAgentavant 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 deLangchainAgentou supprimezagent.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 pydanticSolution recommandée :
Mettez à jour votre package en exécutant la commande suivante dans le terminal :
pip install pydantic --upgradeExé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 pydanticSi 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 cloudpickleSolution recommandée :
Déployez la même version de cloudpickle dans les deux environnements, par exemple 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-aiplatformSolution recommandée :
Mettez à jour votre package en exécutant la commande suivante dans le terminal :
pip install google-cloud-aiplatform --upgradeVé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-aiplatformSi 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 Moteur de raisonnement (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) dans le service storage.googleapis.com et le service 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 :
Vous ne disposez peut-être 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-agent comportant 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 un compte de service incorrect, cette erreur est le comportement attendu.
En outre, vous pouvez rencontrer cette erreur si le compte de service personnalisé se trouve dans un projet différent de celui où vous déployez l'agent, et que la règle d'administration iam.disableCrossProjectServiceAccountUsage est appliquée dans le projet du compte de service.
Consultez Compte de service personnalisé inter-projets pour obtenir la liste complète des configurations requises pour ce scénario.
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) sur ce compte de service. Si ce n'est pas le cas, demandez à votre administrateur de vous attribuer le rôle sur ce compte de service.
Si vous êtes dans le scénario multiprojet, 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 que l'agent de service AI Platform Reasoning Engine ne dispose pas de l'autorisation iam.serviceAccounts.getAccessToken sur le compte de service personnalisé.
Consultez Compte de service personnalisé multiprojet pour obtenir la liste complète des configurations requises pour ce scénario.
Solution recommandée :
Demandez à votre administrateur d'accorder à l'agent de service AI Platform Reasoning Engine du projet d'agent le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) 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émenter une stratégie d'intervalle exponentiel entre les tentatives et de nouvelle tentative dans les scripts de déploiement.
- Vérifiez l'utilisation actuelle par rapport aux limites sur la page Cloud de Confiance Quotas de l'API Agent Platform.
- Réduisez la fréquence des déploiements simultanés.
Région temporairement saturée
Problème :
Le déploiement échoue avec l'état 429, RESOURCE_EXHAUSTED et un message indiquant que la région a temporairement atteint sa capacité maximale 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 en votre nom 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. Elle n'apparaît pas sur la page Cloud de Confiance Quotas et ne peut pas être augmentée en demandant une augmentation de quota.
Solutions recommandées :
- Déployez dans une autre région prise en charge. C'est le moyen le plus rapide de débloquer un déploiement.
- Vous devrez réessayer plus tard. Une région ayant atteint sa capacité maximale est un problème temporaire qui se résout généralement de lui-même.
- Demandez une quantité de mémoire ou de CPU inférieure 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 rapports nous aident à orienter la capacité là où elle est nécessaire.
Solutions non applicables :
- 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 l'état 429, 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 la zone 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 la valeur cpu ou memory configurée par instance.
Solutions recommandées :
- Définissez
spec.deployment_spec.max_instancessur la valeur maximale indiquée dans le message d'erreur (ou moins). - Réduisez la valeur
cpuoumemorypar instance dansspec.deployment_spec.resource_limits. - Déployez l'agent dans une autre région prise en charge avec une limite plus élevée.
Solutions non applicables :
- Demander une augmentation de quota sur la page Cloud de Confiance Quotas de votre projet n'a aucun effet, car cette limite est appliquée au projet de diffusion géré par Google, et non à votre projet.
- La suppression d'autres agents de votre projet ou une nouvelle tentative sans modifier
max_instancesouresource_limitsne résout 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 l'é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é danssecret_envn'existe pas dans Secret Manager dans le même projet que l'agent déployé, ou contient une faute de frappe.DESTROYEDouDISABLED: 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,DESTROYEDouDISABLED:- Sur la page Secret Manager du projet dans lequel vous déployez l'agent, vérifiez que chaque
SECRET_IDetVERSION_IDréférencé danssecret_envexiste et est à l'état Activé. - Si une version référencée a été désactivée ou détruite, activez une version valide ou mettez à jour
secret_envpour référencer une version activée.
- Sur la page Secret Manager du projet dans lequel vous déployez l'agent, vérifiez que chaque
- Pour
PERMISSION_DENIED: attribuez 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.s3ns-system.iam.gserviceaccount.com). - Compte de service personnalisé : attribuez le rôle au compte de service personnalisé configuré sur l'agent.
- Compte de service par défaut : attribuez le rôle à l'agent de service AI Platform Reasoning Engine (
La création de l'image de conteneur a expiré
Problème :
Le déploiement échoue avec l'état 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) et un message indiquant que la création de l'image de conteneur de l'agent n'a pas été terminée à temps.
Causes possibles :
Lorsque vous déployez à partir de fichiers sources, Agent Runtime crée une image de conteneur qui installe votre code et ses dépendances. Le déploiement échoue si la compilation est toujours en cours d'exécution lorsque le délai imparti est écoulé. Les builds prennent généralement trop de temps en raison des dépendances qu'ils installent, par exemple :
- Une longue liste de packages dans
requirements, y compris ceux que l'agent n'utilise pas. - Packages sans wheels prédéfinis pour l'environnement de compilation, qui sont compilés à partir de la source lors de la compilation.
- Versions non épinglées ou épinglées de manière lâche, ce qui ralentit la résolution des dépendances.
Solutions recommandées :
- Consultez les journaux de compilation associés au champ
logs_urldes métadonnées d'erreur pour voir quelle étape était en cours d'exécution lorsque la compilation s'est arrêtée. - Supprimez les dépendances inutiles et épinglez les versions de tous les packages requis.
- Donnez la priorité aux packages et aux versions qui publient des wheels prédéfinis, afin que rien ne soit compilé pendant la compilation.
- Relancez le déploiement. Une compilation peut parfois prendre plus de temps que d'habitude pour des raisons non liées à votre code.
Le conteneur n'a pas démarré à temps
Problème :
Le déploiement échoue avec l'état 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) et un message indiquant que le conteneur de l'agent n'a pas commencé à diffuser à temps.
Causes possibles :
Une fois l'image créée, Agent Runtime démarre le conteneur de l'agent et attend qu'il soit prêt à diffuser des requêtes. Le déploiement échoue si le conteneur est toujours en cours de démarrage lorsque le délai imparti est écoulé. Voici quelques causes courantes :
- Travail lent au moment de l'importation, par exemple lors du chargement de modèles ou de fichiers volumineux lorsque les modules de l'agent sont importés.
- Travail lent ou bloquant dans la méthode
set_up()de l'agent, comme les appels réseau qui attendent un service inaccessible.
Solutions recommandées :
- Vérifiez les journaux de conteneur associés au champ
logs_urldes métadonnées d'erreur pour voir où le démarrage s'est arrêté. - Déplacez l'initialisation coûteuse en dehors du temps d'importation du module et réduisez le nombre d'étapes dans
set_up(). Différez les tâches qui ne sont pas nécessaires pour diffuser la première requête. - Assurez-vous que tous les services appelés par l'agent au démarrage sont accessibles depuis l'agent, et définissez des délais avant expiration pour ces appels afin qu'ils ne puissent pas bloquer le démarrage indéfiniment.
- Si les journaux du conteneur indiquent que l'agent a démarré normalement, relancez le déploiement. Le démarrage peut parfois prendre plus de temps que d'habitude pour des raisons sans rapport avec votre code.
Ressources d'assistance
Si le problème persiste, consultez notre guide d'assistance pour obtenir de l'aide.