Fehlerbehebung bei der Bereitstellung eines Agents

In diesem Dokument wird beschrieben, wie Sie Fehler beheben können, die beim Bereitstellen eines Agents auftreten können.

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

  • Verschmutzter Zustand 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 Remoteumgebung in Vertex AI Agent Engine installiert sind.

Empfohlene Lösunge(n)

  • Verschmutzter Zustand auf LangchainAgent. Erstellen Sie eine neue Instanz der LangchainAgent oder entfernen Sie agent.set_up() aus dem Code, bevor Sie den Agent 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 Agents synchron sind. Sie können dies sicherstellen, indem Sie requirements= angeben, wenn Sie den Agent 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 Ihr 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 Entwicklungs- 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 aus der Ferne bereitgestellten Agent, indem Sie beim Bereitstellen des Agents requirements= angeben.

Interne Serverfehler

Problem:

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

InternalServerError: 500 Revision XXX 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 Agent bereitgestellt haben, sollten Sie sys_version= aus den Eingabeargumenten entfernen. Wenn weiterhin Probleme auftreten, melden Sie den Fehler.

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 von Vertex AI 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 Agents einen neuen Bucket angeben und das SDK erstellt den Bucket mit den erforderlichen Berechtigungen.

Wenn weiterhin Probleme auftreten, melden Sie den Fehler.

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 Ihr 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 Sie Probleme mit VPC-SC haben, kann dies einen der folgenden Gründe 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:

Das liegt wahrscheinlich daran, dass im VPC-SC-Perimeter erforderliche Regeln für eingehenden Traffic fehlen.

Empfohlene Lösung:

Wenn Sie Vertex AI Agent Engine 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.iam.gserviceaccount.com) in den Dienst storage.googleapis.com und den Dienst artifactregistry.googleapis.com zuzulassen.

Fehler bei benutzerdefinierten Dienstkonten

Wenn Sie Probleme mit Dienstkonten haben, kann das folgende Ursachen haben:

Als Dienstkonto fungieren

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 iam.serviceAccounts.actAs-Berechtigung für das benutzerdefinierte Dienstkonto, das für die Bereitstellung verwendet wird. In einem Multi-Agent-System mit mehreren benutzerdefinierten Dienstkonten kann ein Agent-Autor oder ‑Bereitsteller als einige der Dienstkonten fungieren. Wenn Sie das falsche Dienstkonto verwenden, ist dieser Fehler das erwartete Verhalten.

Außerdem kann dieser Fehler 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 Benutzerdefiniertes dienstübergreifendes Dienstkonto.

Empfohlene Lösung:

Achten Sie darauf, dass Sie das vorgesehene 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 das projektübergreifende Szenario verwenden, prüfen Sie, ob in Ihrem Dienstkontoprojekt die Organisationsrichtlinie iam.disableCrossProjectServiceAccountUsage erzwungen wird. Bitten Sie 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 AI Platform Reasoning Engine Service 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 Benutzerdefiniertes dienstübergreifendes Dienstkonto.

Empfohlene Lösung:

Bitten Sie Ihren Administrator, dem AI Platform Reasoning Engine-Dienst-Agent des Agent-Projekts die Rolle Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) für das benutzerdefinierte Dienstkonto zu gewähren.

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

Supportressourcen

Wenn das Problem weiterhin besteht, wenden Sie sich an den Support.