Fehlerbehebung bei der Bereitstellung eines Agents

In diesem Dokument wird beschrieben, wie Sie Fehler beheben können, die beim Bereitstellen eines KI-Agenten in Agent Runtime auftreten können. Es werden verschiedene häufige Probleme behandelt, darunter Serialisierungsfehler, Berechtigungsfehler und Verstöße gegen VPC-SC-Grenzen.

Hinweis: Wenn Sie Agentenfehlerprotokolle suchen und filtern möchten, verwenden Sie den Log-Explorer, wählen Sie RESOURCE TYPE für „Vertex AI Reasoning Engine“ aus und wählen Sie den entsprechenden RESOURCE CONTAINER-Wert (d.h. die Projektnummer) und den REASONING ENGINE ID-Wert aus.

Fehler bei vordefinierten Vorlagen

Wenn während der Bereitstellung Probleme mit der LangchainAgent-Vorlage auftreten, kann dies an einem der Probleme in diesem Abschnitt liegen.

Interne Serverfehler

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

Leider ist dies ein Sammelfehler für alle Probleme mit dem Container zur Laufzeit. Die mögliche Ursache ist einer von vielen möglichen Fehlern.

Mögliche Ursache(n)

  • Dirty-Status auf LangchainAgent. Dies kann passieren, wenn .set_up() auf einem LangchainAgent aufgerufen wurde, bevor der Agent bereitgestellt wurde.
  • Inkonsistente Paketversionen. Dies kann auftreten, wenn sich die in der Entwicklungsumgebung installierten Pakete von den Paketen unterscheiden, die in der Remote-Umgebung in Agent Runtime installiert sind.

Empfohlene Lösunge(n)

  • Dirty-Status auf LangchainAgent. Erstellen Sie eine neue Instanz der LangchainAgent oder entfernen Sie agent.set_up() aus dem Code, bevor Sie den Agenten bereitstellen.
  • Nicht übereinstimmende Paketspezifikationen Weitere Informationen finden Sie im Abschnitt zur Behebung von Serialisierungsfehlern.

Serialisierungsfehler

Im Allgemeinen ist es wichtig, dass die „lokale“ und die „Remote“-Umgebung bei der Bereitstellung des Agenten synchron sind. Sie können dies sicherstellen, indem Sie requirements= angeben, wenn Sie den Agenten bereitstellen.

Wenn Sie Probleme mit der Serialisierung haben (Fehler im Zusammenhang mit „pickle“ oder „Pickling“ sind Synonyme für „Serialisierung“), kann dies an einem der in diesem Abschnitt beschriebenen Probleme liegen.

Pydantic-Version

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

Mögliche Ursache:

Dies kann auftreten, wenn Ihr pydantic-Paket älter als Version 2.6.4 ist. Führen Sie folgenden Befehl in Ihrem Terminal aus, um zu prüfen, welche Version Sie verwenden:

pip show pydantic

Empfohlene Lösung:

Aktualisieren Sie das Paket, indem Sie im Terminal den folgenden Befehl ausführen:

pip install pydantic --upgrade

Führen Sie den folgenden Befehl in Ihrem Terminal aus, um zu prüfen, ob Sie die Version 2.6.4 oder höher verwenden:

pip show pydantic

Wenn Sie sich in einer Notebookinstanz befinden, z. B. ein Jupyter, Colab oder Workbench, müssen Sie möglicherweise Ihre Laufzeit neu starten, um die aktualisierten Pakete verwenden zu können.

Cloudpickle-Version

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

Mögliche Ursache:

Das kann passieren, wenn die Version Ihres cloudpickle-Pakets in Ihrer Entwicklungsumgebung und Ihrer Bereitstellungsumgebung unterschiedlich ist. Führen Sie den folgenden Befehl in Ihrem Terminal aus, um zu prüfen, welche Version Sie in der Entwicklung verwenden:

pip show cloudpickle

Empfohlene Lösung:

Stellen Sie dieselbe Version von cloudpickle in beiden Umgebungen bereit, z. B. in Ihrer lokalen Entwicklungsumgebung und im remote bereitgestellten Agenten, indem Sie beim Bereitstellen des Agenten requirements= angeben.

Interne Serverfehler

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

Mögliche Ursache:

Das kann passieren, wenn sich sys_version= von der Entwicklungsumgebung unterscheidet, wenn Sie den Agenten bereitstellen.

Empfohlene Lösung:

Nachdem Sie den Agenten bereitgestellt haben, sollten Sie sys_version= aus den Eingabeargumenten entfernen. Wenn weiterhin Probleme auftreten, reichen Sie einen Fehlerbericht ein.

Cloud Storage-Bucket-Fehler

Wenn Probleme mit dem Cloud Storage-Staging-Bucket auftreten, der zum Zeitpunkt der Bereitstellung zum Erfassen und Hochladen Ihres Bots verwendet wird, kann das an einem der folgenden Probleme liegen:

Berechtigungsfehler

Empfohlene Lösung:

Wenn Sie einen bereits vorhandenen Bucket verwenden möchten, achten Sie darauf, dass das Hauptkonto, das für die Verwendung der Agent Platform authentifiziert ist (entweder Sie selbst oder ein Dienstkonto), Storage Admin-Zugriff auf den Bucket hat, und gewähren Sie Berechtigungen für das Dienstkonto.

Alternativ können Sie bei der Bereitstellung des KI-Agenten einen neuen Bucket angeben und das SDK erstellt den Bucket mit den erforderlichen Berechtigungen.

Wenn weiterhin Probleme auftreten, reichen Sie einen Fehlerbericht ein.

Unterverzeichnis des Cloud Storage-Buckets wird nicht erstellt

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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.

(Der 404-Fehler tritt auf, wenn das System versucht, in einen nicht vorhandenen Ordner zu kopieren.)

Mögliche Ursache:

Das liegt wahrscheinlich an einem Problem mit der Stringinterpolation in google-cloud-aiplatform-Versionen, die älter als 1.49.0 sind. Dieser Fehler wurde in höheren Versionen behoben. Führen Sie in Ihrem Terminal den folgenden Befehl aus, um zu prüfen, welche Version von google-cloud-aiplatform Sie verwenden:

pip show google-cloud-aiplatform

Empfohlene Lösung:

Aktualisieren Sie das Paket, indem Sie im Terminal den folgenden Befehl ausführen:

pip install google-cloud-aiplatform --upgrade

Prüfen Sie, ob Sie die Version 1.49.0 oder höher von google-cloud-aiplatform verwenden. Führen Sie dazu den folgenden Befehl in Ihrem Terminal aus:

pip show google-cloud-aiplatform

Wenn Sie eine Notebookinstanz nutzen, z. B. Jupyter, Colab oder Workbench, müssen Sie möglicherweise Ihre Laufzeit neu starten, bevor Sie die aktualisierten Pakete verwenden können.

VPC-SC-Verstoßfehler

Wenn Probleme mit VPC-SC auftreten, kann dies eine der folgenden Ursachen haben:

Berechtigungsfehler

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

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

oder:

Request is prohibited by organization's policy.

Mögliche Ursache:

Dies wird wahrscheinlich durch fehlende erforderliche Regeln für eingehenden Traffic im VPC-SC-Perimeter verursacht.

Empfohlene Lösung:

Wenn Sie die Agent Platform in einer VPC-SC-Umgebung verwenden, müssen Sie in Ihrem Perimeter eine Regel für eingehenden Traffic erstellen, um eingehenden Traffic vom Reasoning Engine-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) zum Dienst storage.googleapis.com und zum Dienst artifactregistry.googleapis.com zuzulassen.

Fehler bei benutzerdefinierten Dienstkonten

Wenn Sie Probleme mit Dienstkonten haben, kann dies eine der folgenden Ursachen haben:

Als Dienstkonto agieren

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

You do not have permission to act as service_account.

Mögliche Ursache:

Möglicherweise haben Sie nicht die Berechtigung iam.serviceAccounts.actAs für das benutzerdefinierte Dienstkonto, das für die Bereitstellung verwendet wird. In einem Multi-Agenten-System mit mehreren benutzerdefinierten Dienstkonten kann ein Agent-Autor oder -Deployer als einige der Dienstkonten fungieren. Wenn Sie das falsche Dienstkonto verwenden, ist dieser Fehler das erwartete Verhalten.

Dieser Fehler kann auch auftreten, wenn sich das benutzerdefinierte Dienstkonto in einem anderen Projekt als dem befindet, in dem Sie den Agent bereitstellen, und die Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage im Dienstkontoprojekt erzwungen wird.

Eine vollständige Liste der erforderlichen Konfigurationen für dieses Szenario finden Sie unter Projektübergreifendes benutzerdefiniertes Dienstkonto.

Empfohlene Lösung:

Achten Sie darauf, dass Sie das gewünschte Dienstkonto verwenden. Prüfen Sie, ob Sie die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser) für dieses Dienstkonto haben. Wenn nicht, bitten Sie Ihren Administrator, Ihnen die Rolle für dieses Dienstkonto zu gewähren.

Wenn Sie sich im projektübergreifenden Szenario befinden, prüfen Sie, ob die Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage für Ihr Dienstkontoprojekt erzwungen wird. Bitten Sie in diesem Fall Ihren Administrator, die Richtlinie zu deaktivieren.

Metadatenserver nicht verfügbar

Problem:

Möglicherweise erhalten Sie eine Fehlermeldung, die so aussieht:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

oder

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

Mögliche Ursache:

Das kann passieren, wenn sich das benutzerdefinierte Dienstkonto und Ihr Agent in verschiedenen Projekten befinden und der KI Platform Reasoning Engine-Dienst-Agent nicht die Berechtigung iam.serviceAccounts.getAccessToken für das benutzerdefinierte Dienstkonto hat.

Eine vollständige Liste der erforderlichen Konfigurationen für dieses Szenario finden Sie unter Projektübergreifendes benutzerdefiniertes Dienstkonto.

Empfohlene Lösung:

Bitten Sie Ihren Administrator, dem KI-Plattform Reasoning Engine-Dienst-Agent des Agent-Projekts die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) für das benutzerdefinierte Dienstkonto zuzuweisen.

Der KI-Plattform Reasoning Engine-Dienst-Agent sollte sich im selben Projekt befinden, das Sie zum Bereitstellen Ihres Agenten verwenden. Die IAM-Bindung der Rollenzuweisung sollte sich in dem Projekt befinden, in dem sich das benutzerdefinierte Dienstkonto befindet.

Fehler vom Typ „Ressource erschöpft“ oder „Ratenbegrenzung“ (Fehler 429)

Problem:

Die Bereitstellung schlägt mit dem Status Error 429 oder RESOURCE_EXHAUSTED fehl.

Mögliche Ursache:

Das Projekt hat die API-Ratenbegrenzungen oder die Kontingente für gleichzeitige Anfragen überschritten.

Empfohlene Lösungen:

  • Implementieren Sie in Bereitstellungsskripts eine Strategie für exponentiellen Backoff und Wiederholungsversuche.
  • Prüfen Sie die aktuelle Nutzung im Vergleich zu den Limits auf der Seite Cloud de Confiance „Kontingente“ für die Agent Platform API.
  • Reduzieren Sie die Häufigkeit gleichzeitiger Bereitstellungen.

Region vorübergehend ausgelastet

Problem:

Die Bereitstellung schlägt mit dem Status 429, RESOURCE_EXHAUSTED und einer Meldung fehl, dass die Region vorübergehend die Kapazität für die zulässige Gesamtmenge an Arbeitsspeicher oder CPU erreicht hat.

Mögliche Ursache:

Agentenbereitstellungen in einer Region greifen auf einen Pool von Bereitstellungskapazität zurück, der von Agent Runtime in Ihrem Namen verwaltet wird und den alle Kunden in dieser Region gemeinsam nutzen. Wenn der Pool erschöpft ist, schlagen neue Bereitstellungen in dieser Region fehl, bis wieder Kapazität frei wird.

Dieses Limit gehört nicht zu den Kontingenten Ihres Projekts. Es wird nicht auf der SeiteCloud de Confiance Kontingente angezeigt und kann nicht durch eine Anfrage zur Kontingenterhöhung erhöht werden.

Empfohlene Lösungen:

  • Stellen Sie die Anwendung in einer anderen unterstützten Region bereit. Dies ist die schnellste Möglichkeit, die Blockierung eines Deployments aufzuheben.
  • Versuchen Sie es später noch einmal. Eine Region, die ihre Kapazitätsgrenze erreicht hat, ist ein vorübergehendes Problem, das sich in der Regel von selbst löst.
  • Fordern Sie weniger Arbeitsspeicher oder CPU für Ihren Agenten an. Eine kleinere Bereitstellung passt möglicherweise in die verbleibende Kapazität.
  • Wenden Sie sich an den Support, wenn Bereitstellungen in einer Region weiterhin auf diese Weise fehlschlagen. Wir können das Limit zwar nicht erhöhen, aber Ihre Berichte helfen uns, die Kapazität dorthin zu lenken, wo sie benötigt wird.

Nicht zutreffende Lösungen:

  • Durch das Löschen Ihrer vorhandenen Agenten wird keine Kapazität für dieses Limit freigegeben, da die Kapazität nicht nur von Ihrem Projekt verbraucht wird.
  • Die Anforderung einer Kontingenterhöhung hat keine Auswirkungen, da das Limit kein Projektkontingent ist.

Maximale Anzahl von Instanzen überschreitet regionales Limit

Problem:

Die Bereitstellung schlägt mit dem Status 429, RESOURCE_EXHAUSTED und einer Meldung fehl, dass spec.deployment_spec.max_instances die maximale Anzahl von Instanzen überschreitet, die für die angeforderte CPU oder den angeforderten Arbeitsspeicher in der resource_limits der Region unterstützt werden.

Mögliche Ursache:

Wenn Sie einen Agenten bereitstellen, multipliziert Agent Runtime spec.deployment_spec.max_instances mit den instanzspezifischen cpu und memory in spec.deployment_spec.resource_limits und prüft, ob die Spitzenzuweisung dieses einzelnen Agenten innerhalb des regionalen Limits des zugrunde liegenden Bereitstellungsprojekts liegt. Wenn Sie max_instances nicht angeben, wendet Agent Runtime einen Standardwert an (z. B. 200). Dieser kann in Regionen mit niedrigeren Limits die maximal unterstützten Instanzen überschreiten, wenn er mit dem konfigurierten cpu oder memory pro Instanz multipliziert wird.

Empfohlene Lösungen:

  • Setzen Sie spec.deployment_spec.max_instances auf den in der Fehlermeldung angezeigten Höchstwert (oder einen niedrigeren Wert).
  • Reduzieren Sie den Wert für cpu oder memory pro Instanz in spec.deployment_spec.resource_limits.
  • Stellen Sie den KI-Agenten in einer anderen unterstützten Region mit einem höheren Limit bereit.

Nicht zutreffende Lösungen:

  • Das Anfordern einer Kontingenterhöhung auf der Seite Cloud de Confiance „Kontingente“ Ihres Projekts hat keine Auswirkungen, da dieses Limit für das von Google verwaltete Bereitstellungsprojekt und nicht für Ihr Projekt gilt.
  • Das Löschen anderer Agenten in Ihrem Projekt oder ein erneuter Versuch ohne Änderung von max_instances oder resource_limits behebt diesen Fehler nicht, da bei der Prüfung die Spitzenzuweisung der einzelnen Bereitstellung mit einem statischen Limit verglichen wird.

Secret Manager-Zugriffsfehler

Problem:

Die Bereitstellung schlägt mit dem Status 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) und einer Meldung wie der folgenden fehl:

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

Mögliche Ursachen:

  • NOT_FOUND: Die in secret_env angegebene Secret-ID oder Versions-ID ist im Secret Manager im selben Projekt wie der bereitgestellte Agent nicht vorhanden oder enthält einen Tippfehler.
  • DESTROYED oder DISABLED: Die referenzierte Secret-Version in Secret Manager ist gelöscht oder deaktiviert.
  • PERMISSION_DENIED: Das vom Agent verwendete Dienstkonto hat nicht die Rolle „Secret Manager Secret Accessor“ (roles/secretmanager.secretAccessor) für das referenzierte Secret.

Empfohlene Lösungen:

  • Für NOT_FOUND, DESTROYED oder DISABLED:
    1. Prüfen Sie auf der Secret Manager-Seite des Projekts, in dem Sie den Agenten bereitstellen, ob alle in secret_env referenzierten SECRET_ID und VERSION_ID vorhanden sind und den Status Aktiviert haben.
    2. Wenn eine referenzierte Version deaktiviert oder gelöscht wurde, aktivieren Sie eine gültige Version oder aktualisieren Sie secret_env, um auf eine aktivierte Version zu verweisen.
  • Für PERMISSION_DENIED: Weisen Sie dem Dienstkonto, das das Secret abruft, die Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das Secret (oder das Projekt, das das Secret enthält) zu:
    • Standarddienstkonto: Weisen Sie die Rolle dem AI Platform Reasoning Engine-Dienst-Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com) zu.
    • Benutzerdefiniertes Dienstkonto: Weisen Sie die Rolle dem benutzerdefinierten Dienstkonto zu, das für den Agent konfiguriert ist.

Zeitüberschreitung beim Erstellen des Container-Images

Problem:

Die Bereitstellung schlägt mit dem Status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) und einer Meldung fehl, dass das Container-Image des Agents nicht rechtzeitig erstellt wurde.

Mögliche Ursachen:

Wenn Sie aus Quelldateien bereitstellen, erstellt Agent Runtime ein Container-Image, das Ihren Code und seine Abhängigkeiten installiert. Die Bereitstellung schlägt fehl, wenn der Build noch ausgeführt wird, wenn die zulässige Zeit abgelaufen ist. Builds dauern in der Regel zu lange, weil sie Abhängigkeiten installieren, z. B.:

  • Eine lange Liste von Paketen in requirements, einschließlich derer, die der Agent nicht verwendet.
  • Pakete ohne vordefinierte Wheels für die Build-Umgebung, die während des Builds aus der Quelle kompiliert werden.
  • Nicht angepinnte oder lose angepinnte Versionen, die die Auflösung von Abhängigkeiten verlangsamen.

Empfohlene Lösungen:

  • Prüfen Sie die Build-Logs, die im Feld logs_url der Fehlermetadaten verlinkt sind, um zu sehen, welcher Schritt ausgeführt wurde, als der Build gestoppt wurde.
  • Entfernen Sie unnötige Abhängigkeiten und pinnen Sie die Versionen aller erforderlichen Pakete an.
  • Priorisieren Sie Pakete und Versionen, die vordefinierte Wheels veröffentlichen, damit während des Builds nichts kompiliert wird.
  • Wiederholen Sie die Bereitstellung. Ein Build kann gelegentlich aus Gründen, die nichts mit Ihrem Code zu tun haben, länger als gewöhnlich dauern.

Container wurde nicht rechtzeitig gestartet

Problem:

Die Bereitstellung schlägt mit dem Status 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) und der Meldung fehl, dass der Container des Agents nicht rechtzeitig gestartet wurde.

Mögliche Ursachen:

Nachdem das Image erstellt wurde, startet Agent Runtime den Container des Agents und wartet, bis er bereit ist, Anfragen zu verarbeiten. Die Bereitstellung schlägt fehl, wenn der Container noch gestartet wird, wenn die zulässige Zeit abgelaufen ist. Häufige Ursachen sind:

  • Langsame Arbeit beim Import, z. B. das Laden großer Modelle oder Dateien, wenn die Module des KI-Agenten importiert werden.
  • Langsame oder blockierende Arbeit in der Methode set_up() des Agents, z. B. Netzwerkaufrufe, die auf einen nicht erreichbaren Dienst warten.

Empfohlene Lösungen:

  • Prüfen Sie die Containerlogs, die im Feld logs_url der Fehlermetadaten verlinkt sind, um zu sehen, wo der Startvorgang hängen geblieben ist.
  • Verschieben Sie die teure Initialisierung aus der Modulimportzeit und minimieren Sie die Anzahl der Schritte in set_up() schnell. Verschieben Sie Aufgaben, die nicht für die erste Anfrage erforderlich sind.
  • Achten Sie darauf, dass alle Dienste, die der Agent beim Start aufruft, vom Agenten erreichbar sind, und legen Sie Zeitlimits für diese Aufrufe fest, damit sie den Start nicht unbegrenzt blockieren können.
  • Wenn die Containerlogs zeigen, dass der Agent normal gestartet wurde, versuchen Sie es noch einmal mit der Bereitstellung. Der Start kann gelegentlich aus Gründen, die nichts mit Ihrem Code zu tun haben, länger als gewöhnlich dauern.

Supportressourcen

Wenn das Problem weiterhin besteht, findest du in unserem Supportleitfaden weitere Informationen.