Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefinierte Containeranforderungen für Vorhersagen

Wenn Sie einen benutzerdefinierten Container für die Bereitstellung von Vorhersagen aus einem benutzerdefiniert trainierten Modell verwenden möchten, müssen Sie für Vertex AI ein Docker-Container-Image bereitstellen, auf dem ein HTTP-Server ausgeführt wird. In diesem Dokument werden die Anforderungen beschrieben, die ein Container-Image erfüllen muss, um mit Vertex AI kompatibel zu sein. Außerdem wird beschrieben, wie Vertex AI mit Ihrem benutzerdefinierten Container interagiert, sobald er ausgeführt wird. In diesem Dokument wird also beschrieben, was Sie beachten müssen, wenn Sie ein Container-Image für die Verwendung mit Vertex AI entwerfen.

Unter Benutzerdefinierten Container verwenden erfahren Sie, wie Sie ein benutzerdefiniertes Container-Image für Vorhersagen verwenden.

Anforderungen an Container-Images

Wenn das Docker-Container-Image als Container ausgeführt wird, muss der Container einen HTTP-Server ausführen. Insbesondere muss der Container Aktivitätsprüfungen, Systemdiagnosen und Vorhersageanfragen überwachen und darauf reagieren. In den folgenden Unterabschnitten werden diese Anforderungen detailliert beschrieben.

Sie können den HTTP-Server auf jede beliebige Weise mit jeder beliebigen Programmiersprache implementieren, sofern die Anforderungen in diesem Abschnitt erfüllt werden. Sie können beispielsweise einen benutzerdefinierten HTTP-Server mit einem Web-Framework wie Flask schreiben oder ML-Bereitstellungssoftware (maschinelles Lernen) verwenden, die einen HTTP-Server ausführt, z. B. TensorFlow Serving, TorchServe oder KServe Python Server.

HTTP-Server ausführen

Zum Ausführen eines HTTP-Servers können Sie eine ENTRYPOINT-Anweisung, eine CMD-Anweisung oder beides in dem Dockerfile verwenden, den Sie zum Erstellen des Container-Images nutzen. Weitere Informationen erhalten Sie unter Interaktion zwischen CMD und ENTRYPOINT.

Alternativ können Sie die Felder containerSpec.command und containerSpec.args bei der Erstellung Ihrer Model Ressource angeben, um die ENTRYPOINT und CMD Ihres Container-Images zu überschreiben. Wenn Sie eines dieser Felder angeben, können Sie ein Container-Image verwenden, das die Anforderungen aufgrund eines nicht kompatiblen (oder nicht vorhandenen) ENTRYPOINT oder CMD sonst nicht erfüllen würde.

Sie bestimmen jedoch, welcher Befehl auf dem Container ausgeführt wird. Achten Sie darauf, dass diese ENTRYPOINT-Anweisung unbegrenzt ausgeführt wird. Führen Sie beispielsweise keinen Befehl aus, der einen HTTP-Server im Hintergrund startet und dann beendet. In diesem Fall wird der Container sofort nach der Ausführung beendet.

Ihr HTTP-Server muss auf 0.0.0.0 Anfragen an einem Port Ihrer Wahl überwachen. Wenn Sie ein Model erstellen, geben Sie diesen Port im Feld containerSpec.ports an. Im Abschnitt zur Umgebungsvariable AIP_HTTP_PORT in diesem Dokument erfahren Sie, wie der Container auf diesen Wert zugreifen kann.

Aktivitätsprüfungen

Vertex AI führt eine Aktivitätsprüfung durch, wenn der Container gestartet wird, um zu prüfen, ob der Server ausgeführt wird. Wenn Sie ein benutzerdefiniert trainiertes Modell für eine Endpoint-Ressource bereitstellen, verwendet AI Platform einen TCP-Aktivitätstest, um zu versuchen, eine TCP-Verbindung zu Ihrem Container am konfigurierten Port herzustellen. Es werden bis zu vier Versuche gestartet, eine Verbindung herzustellen. Warten Sie nach jedem Fehler zehn Sekunden. Wenn die Prüfung zu diesem Zeitpunkt noch immer keine Verbindung hergestellt hat, startet Vertex AI Ihren Container neu.

Ihr HTTP-Server muss kein spezielles Verhalten zeigen, um diese Prüfungen durchzuführen. Solange die Anfragen über den konfigurierten Port überwacht werden, kann die Aktivitätsprüfung eine Verbindung herstellen.

Systemdiagnosen

Optional können Sie startup_probe oder health_probe angeben.

Die Startprüfung prüft, ob die Containeranwendung gestartet wurde. Wenn keine Startprüfung angegeben ist, wird keine Startprüfung durchgeführt und die Systemdiagnosen beginnen sofort. Wenn eine Startprüfung angegeben ist, werden Systemdiagnosen erst ausgeführt, wenn die Startprüfung erfolgreich war.

Für ältere Anwendungen, die bei der ersten Initialisierung möglicherweise zusätzliche Startzeit benötigen, sollte eine Startprüfung konfiguriert werden. Wenn die Anwendung beispielsweise die Modellartefakte aus einer externen Quelle kopieren muss, sollte eine Startprüfung so konfiguriert werden, dass sie nach Abschluss dieser Initialisierung einen Erfolg zurückgibt.

Die Systemdiagnose prüft, ob ein Container bereit ist, Traffic anzunehmen. Wenn keine Systemdiagnose angegeben ist, verwendet Vertex AI die Standardsystemdiagnosen, wie unter Standardsystemdiagnosen beschrieben.

Für Legacy-Anwendungen, die nicht 200 OK zurückgeben werden, um anzuzeigen, dass das Modell geladen und bereit ist, Traffic anzunehmen, sollten eine Systemdiagnose konfiguriert werden. Beispielsweise kann eine Anwendung 200 OK zurückgeben, um den Erfolg anzuzeigen, obwohl der tatsächliche Ladestatus des Modells im Antworttext angibt, dass das Modell möglicherweise nicht geladen wird und daher möglicherweise keinen Traffic akzeptiert. In diesem Fall sollte eine Systemdiagnose so konfiguriert werden, dass sie nur dann einen Erfolg zurückgibt, wenn das Modell geladen ist und bereit ist, Traffic zu verarbeiten.

Um eine Prüfung durchzuführen, führt Vertex AI den angegebenen exec-Befehl im Zielcontainer aus. Wenn der Befehl erfolgreich ist, wird „0“ zurückgegeben und der Container wird als aktiv und fehlerfrei betrachtet.

Standard-Systemdiagnosen

Vertex AI führt während der Ausführung standardmäßig zeitweise Systemdiagnosen auf Ihrem HTTP-Server aus, um sicherzugehen, dass er für die Verarbeitung von Vorhersageanfragen bereit ist. Der Dienst verwendet eine Systemdiagnose, um HTTP-GET-Anfragen an einen konfigurierbaren Systemdiagnosepfad auf Ihrem Server zu senden. Geben Sie diesen Pfad im Feld containerSpec.healthRoute an, wenn Sie ein Model erstellen. Im Abschnitt zur Umgebungsvariable AIP_HEALTH_ROUTE in diesem Dokument erfahren Sie, wie der Container auf diesen Wert zugreifen kann.

Konfigurieren Sie den HTTP-Server so, dass er auf jede Systemdiagnoseanfrage antwortet:

Wenn der Server bereit für die Verarbeitung von Vorhersageanfragen ist, antworten Sie innerhalb von zehn Sekunden auf die Systemdiagnoseanfrage mit dem Statuscode 200 OK. Der Inhalt des Antworttextes spielt keine Rolle, er wird von Vertex AI ignoriert.

Diese Antwort bedeutet, dass der Server fehlerfrei ist.
Wenn der Server nicht für die Verarbeitung von Vorhersageanfragen bereit ist, antworten Sie nicht innerhalb von zehn Sekunden auf die Systemdiagnoseanfrage oder antworten Sie mit einem Statuscode, der nicht 200 OK ist. Beispielsweise kann mit dem Statuscode 503 Service Unavailable geantwortet werden.

Diese Antwort (oder das Fehlen einer Antwort) gibt an, dass der Server fehlerhaft ist.

Wenn die Systemdiagnose jemals eine Antwort "Fehlerhaft" von Ihrem Server erhält (einschließlich einer Antwort innerhalb von 10 Sekunden), sendet sie bis zu drei zusätzliche Systemdiagnosen in Intervallen von 10 Sekunden. In dieser Zeit wird der Server von Vertex AI weiterhin als fehlerfrei eingestuft. Wenn die Prüfung eine fehlerfreie Antwort auf eine dieser Prüfungen erhält, kehrt sie sofort zum temporären Zeitplan der Systemdiagnosen zurück. Wenn die Prüfung jedoch vier aufeinanderfolgende Antworten "Fehlerhaft" erhält, beendet Vertex AI die Weiterleitung des Vorhersagetraffics an den Container. Wenn die Ressource DeployedModel skaliert wird, um mehrere Vorhersageknoten zu verwenden, leitet Vertex AI Vorhersageanfragen an andere, fehlerfreie Container weiter.

Vertex AI startet den Container nicht neu. Die Systemdiagnose sendet stattdessen weiterhin periodische Systemdiagnoseanfragen an den fehlerhaften Server. Wenn eine fehlerfreie Antwort eingeht, wird dieser Container als fehlerfrei gekennzeichnet und Vorhersagetraffic wird wieder an diesen Container weitergeleitet.

Praktische Hinweise

In einigen Fällen reicht es aus, dass der HTTP-Server in Ihrem Container immer mit dem Statuscode 200 OK auf Systemdiagnosen reagiert. Wenn Ihr Container Ressourcen lädt, bevor er den Server startet, ist der Container während des Startzeitraums und immer dann, wenn der HTTP-Server ausfällt, fehlerhaft. In allen anderen Fällen wird das System als fehlerfrei erkannt.

Bei einer komplexeren Konfiguration können Sie den HTTP-Server absichtlich so konzipieren, dass er zu bestimmten Zeiten auf Systemdiagnosen mit einem fehlerhaften Zustand antwortet. Sie haben beispielsweise die Möglichkeit, den Vorhersagetraffic an einen Knoten für einen bestimmten Zeitraum zu blockieren, damit der Container Wartungsarbeiten ausführen kann.

Prognoseanfragen

Wenn ein Client eine projects.locations.endpoints.predict-Anfrage an die Vertex AI API sendet, leitet Vertex AI diese Anfrage als HTTP-POST-Anfrage an einen konfigurierbaren Vorhersagepfad auf Ihrem Server weiter. Geben Sie diesen Pfad im Feld containerSpec.predictRoute an, wenn Sie ein Model erstellen. Im Abschnitt zur Umgebungsvariable AIP_PREDICT_ROUTE in diesem Dokument erfahren Sie, wie der Container auf diesen Wert zugreifen kann.

Anfrageanforderungen

Wenn das Modell auf einem öffentlichen Endpunkt bereitgestellt wird, darf jede Vorhersageanfrage maximal 1,5 MB groß sein. Der HTTP-Server muss Vorhersageanfragen mit dem HTTP-Header Content-Type: application/json und JSON-Texten im folgenden Format akzeptieren:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

In diesen Anfragen gilt:

INSTANCES ist ein Array von einem oder mehreren JSON-Werten eines beliebigen Typs. Jeder Wert steht für eine Instanz, für die Sie eine Vorhersage bereitstellen.
PARAMETERS ist ein JSON-Objekt mit allen Parametern, die der Container zum Bereitstellen von Vorhersagen auf den Instanzen benötigt. Vertex AI betrachtet das Feld parameters als optional, sodass Sie Ihren Container so entwerfen können, dass es entweder erforderlich ist, nur verwendet wird, wenn es bereitgestellt wird, oder ignoriert wird.

Weitere Informationen zu den Anforderungen des Anfragetexts.

Anforderungen an Antworten

Wenn das Modell auf einem öffentlichen Endpunkt bereitgestellt wird, darf jede Vorhersageantwort maximal 1,5 MB groß sein. Der HTTP-Server muss Antworten mit JSON-Texten im folgenden Format senden:

{
  "predictions": PREDICTIONS
}

Ersetzen Sie in diesen Antworten PREDICTIONS durch ein Array von JSON-Werten, die die Vorhersagen darstellen, die Ihr Container für jede der INSTANCES in der entsprechenden Anfrage generiert hat.

Nachdem Ihr HTTP-Server diese Antwort gesendet hat, fügt Vertex AI der Antwort ein deployedModelId-Feld hinzu, bevor es an den Client zurückgegeben wird. Dieses Feld gibt an, welches DeployedModel an einem Endpoint die Antwort sendet. Weitere Informationen zum Antworttextformat

Anforderungen an die Veröffentlichung von Container-Images

Sie müssen das Container-Image in Artifact Registry hochladen, um es mit Vertex AI zu verwenden. Informationen zum Hochladen eines Container-Images in Artifact Registry

Insbesondere müssen Sie das Container-Image an ein Repository übertragen, das die folgenden Anforderungen an Speicherort und Berechtigungen erfüllt.

Standort

Wenn Sie Artifact Registry verwenden, muss das Repository eine Region verwenden, die mit dem regionalen Endpunkt übereinstimmt, an dem Sie ein Model erstellen möchten. Wenn Sie beispielsweise ein Model am Endpunkt us-central1-aiplatform.googleapis.com erstellen möchten, muss der vollständige Name Ihres Container-Image mit us-central1-docker.pkg.dev/ beginnen. Verwenden Sie kein multiregionales Repository für Ihr Container-Image.

Berechtigungen

Vertex AI muss die Berechtigung zum Abrufen des Container-Image haben, wenn Sie ein Model erstellen. Insbesondere muss der Vertex AI-Dienst-Agent für Ihr Projekt die Berechtigungen der Rolle „Artifact Registry-Leser“ (roles/artifactregistry.reader) für das Repository des Container-Images haben.

Vertex AI verwendet den Vertex AI-Dienst-Agent für Ihr Projekt, um mit anderen Google Cloud-Diensten zu interagieren. Dieses Dienstkonto hat die E-Mail-Adresse service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, wobei PROJECT_NUMBER durch die Projektnummer Ihres Vertex AI-Projekts ersetzt wird.

Wenn Sie Ihr Container-Image per Push in dasselbe Google Cloud-Projekt übertragen haben, in dem Sie Vertex AI verwenden, müssen Sie keine Berechtigungen konfigurieren. Die Standardberechtigungen, die dem Vertex AI-Dienst-Agent gewährt wurden, reichen aus.

Wenn Sie das Container-Image hingegen nicht in das Google Cloud-Projekt hochgeladen haben, in dem Sie Vertex AI verwenden, müssen Sie dem Vertex AI-Dienst-Agent die Rolle Artifact Registry-Leser für das Artifact Registry-Repository zuweisen.

Auf Modellartefakte zugreifen

Beim Erstellen eines benutzerdefinierten Model ohne einen benutzerdefinierten Container müssen Sie den URI eines Cloud Storage-Verzeichnisses mit Modellartefakten als das Feld artifactUri angeben. Wenn Sie ein Model mit einem benutzerdefinierten Container erstellen, ist das Bereitstellen von Modellartefakten in Cloud Storage optional.

Wenn das Container-Image die Modellartefakte enthält, die Sie für die Bereitstellung von Vorhersagen benötigen, müssen Sie keine Dateien aus Cloud Storage laden. Wenn Sie jedoch Modellartefakte bereitstellen, indem Sie das Feld artifactUri angeben, muss der Container diese Artefakte beim Starten der Anwendung laden. Wenn Vertex AI Ihren Container startet, wird die Umgebungsvariable AIP_STORAGE_URI auf einen Cloud Storage-URI gesetzt, der mit gs:// beginnt. Mit dem entrypoint-Befehl Ihres Containers ENTRYPOINT können Sie das von diesem URI angegebene Verzeichnis herunterladen, um auf die Modellartefakte zuzugreifen.

Beachten Sie, dass der Wert der Umgebungsvariable AIP_STORAGE_URI nicht mit dem Cloud Storage-URI identisch ist, den Sie beim Erstellen des Model im Feld artifactUri angegeben haben. Stattdessen verweist AIP_STORAGE_URI auf eine Kopie des Modellartefaktverzeichnisses in einem anderen Cloud Storage-Bucket, den Vertex AI verwaltet. Vertex AI füllt dieses Verzeichnis, wenn Sie ein Model erstellen. Sie können den Inhalt des Verzeichnisses nicht aktualisieren. Wenn Sie neue Modellartefakte verwenden möchten, müssen Sie ein neues Model erstellen.

Das Dienstkonto, das der Container standardmäßig verwendet, hat Lesezugriff auf diesen URI.

Wenn Sie dagegen ein benutzerdefiniertes Dienstkonto angeben, wenn Sie Model auf einem Endpoint bereitstellen, gewährt Vertex AI automatisch dem angegebenen Dienstkonto die Rolle Storage-Objekt-Betrachter (roles/storage.objectViewer) für den Cloud Storage-Bucket des URI.

Verwenden Sie zum Laden der Modellartefakte eine beliebige Bibliothek, die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) unterstützt. Sie müssen die Authentifizierung nicht explizit konfigurieren.

Im Container verfügbare Umgebungsvariablen

Der Befehl "entrypoint" des Containers ENTRYPOINT kann auf Umgebungsvariablen verweisen, die Sie manuell konfiguriert haben, sowie auf Umgebungsvariablen, die automatisch von Vertex AI festgelegt werden. In diesem Abschnitt wird beschrieben, wie Sie Umgebungsvariablen festlegen können. Außerdem enthält er Details zu den Variablen, die von Vertex AI automatisch festgelegt werden.

Im Container-Image festgelegte Variablen

Verwenden Sie zum Festlegen von Umgebungsvariablen im Container-Image die ENV-Anweisung von Docker. Legen Sie keine Umgebungsvariablen fest, die mit dem Präfix AIP_ beginnen.

Der Befehl „entrypoint“ des Containers ENTRYPOINT kann diese Umgebungsvariablen verwenden, aber Sie können in keinem der Model-API-Felder darauf verweisen.

Von Vertex AI festgelegte Variablen

Wenn Vertex AI mit dem Ausführen des Containers beginnt, wird die folgende Umgebungsvariablen in der Containerumgebung festgelegt. Jede Variable beginnt mit dem Präfix AIP_. Legen Sie keine Umgebungsvariablen manuell fest, die dieses Präfix verwenden.

Die ENTRYPOINT-Anweisung des Containers kann auf diese Variablen zugreifen. Informationen dazu, welche Vertex AI API-Felder auch auf diese Variablen verweisen können, finden Sie in der API-Referenz zu ModelContainerSpec.

Variablenname	Standardwert	So konfigurieren Sie den Wert	Details
AIP_ACCELERATOR_TYPE	Nicht festgelegt	Wenn Sie ein `Model` als `DeployedModel` für eine `Endpoint`-Ressource bereitstellen, legen Sie das Feld `dedicatedResources.machineSpec.acceleratorType` fest.	Diese Variable gibt gegebenenfalls den Beschleunigertyp an, der von der VM-Instanz verwendet wird, auf der der Container ausgeführt wird.
AIP_DEPLOYED_MODEL_ID	Ein String aus Ziffern, der das `DeployedModel` angibt, in dem das `Model` dieses Containers bereitgestellt wurde.	Nicht konfigurierbar	Dieser Wert ist das Feld `id` des `DeployedModel`.
AIP_ENDPOINT_ID	Ein String aus Ziffern, der den `Endpoint` angibt, an dem das `Model` des Containers bereitgestellt wurde.	Nicht konfigurierbar	Dieser Wert ist das letzte Segment des Felds `name` des `Endpoint` (nach `endpoints/`).
AIP_FRAMEWORK	`CUSTOM_CONTAINER`	Nicht konfigurierbar
AIP_HEALTH_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL` Ersetzen Sie in diesem String `ENDPOINT` durch den Wert der Variable `AIP_ENDPOINT_ID` und ersetzen Sie `DEPLOYED_MODEL` durch den Wert der Variable `AIP_DEPLOYED_MODEL_ID`.	Wenn Sie einen `Model` erstellen, legen Sie das Feld `containerSpec.healthRoute` fest.	Diese Variablen geben den HTTP-Pfad im Container an, an den Vertex AI Systemdiagnosen sendet.
AIP_HTTP_PORT	`8080`	Wenn Sie einen `Model` erstellen, legen Sie das Feld `containerSpec.ports` fest. Der erste Eintrag in diesem Feld wird zum Wert `AIP_HTTP_PORT`.	Vertex AI sendet Aktivitätsprüfungen, Systemdiagnosen und Vorhersageanfragen an diesen Port im Container. Der HTTP-Server Ihres Containers muss Anfragen auf diesem Port überwachen.
AIP_MACHINE_TYPE	Kein Standard, muss konfiguriert werden.	Wenn Sie ein `Model` als `DeployedModel` für eine `Endpoint`-Ressource bereitstellen, legen Sie das Feld `dedicatedResources.machineSpec.machineType` fest.	Diese Variable gibt den VM-Typ an, auf dem der Container ausgeführt wird.
AIP_MODE	`PREDICTION`	Nicht konfigurierbar	Diese Variable bedeutet, dass der Container auf Vertex AI für Bereitstellen von Onlinevorhersagen ausgeführt wird. Sie können diese Umgebungsvariable verwenden, um eine benutzerdefinierte Logik zu Ihrem Container hinzuzufügen, damit er in mehreren Rechenumgebungen ausgeführt werden kann, aber nur bestimmte Codepfade verwendet werden können, wenn er in Vertex AI ausgeführt werden.
AIP_MODE_VERSION	`1.0.0`	Nicht konfigurierbar	Diese Variable steht für die Version der benutzerdefinierten Anforderungen (dieses Dokument), bei denen Vertex AI erwartet, dass sie vom Container erfüllt werden. Dieses Dokument wird gemäß der semantischen Versionsverwaltung aktualisiert.
AIP_MODEL_NAME	Der Wert der `AIP_ENDPOINT_ID`-Variablen	Nicht konfigurierbar	Siehe die Zeile `AIP_ENDPOINT_ID`. Diese Variable ist aus Kompatibilitätsgründen vorhanden.
AIP_PREDICT_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict` Ersetzen Sie in diesem String `ENDPOINT` durch den Wert der Variable `AIP_ENDPOINT_ID` und ersetzen Sie `DEPLOYED_MODEL` durch den Wert der Variable `AIP_DEPLOYED_MODEL_ID`.	Wenn Sie einen `Model` erstellen, legen Sie das Feld `containerSpec.predictRoute` fest.	Diese Variable gibt den HTTP-Pfad im Container an, an den Vertex AI Vorhersageanfragen weiterleitet.
AIP_PROJECT_NUMBER	Die Projektnummer des Google Cloud-Projekts, in dem Sie Vertex AI verwenden	Nicht konfigurierbar
AIP_STORAGE_URI	Wenn Sie das Feld `artifactUri` beim Erstellen eines `Model`-Objekts nicht festlegen: ein leerer String Wenn Sie das Feld `artifactUri` beim Erstellen eines `Model` festlegen: Ein Cloud Storage-URI (beginnt mit `gs://`) der gibt ein Verzeichnis in einem von Vertex AI verwalteten Bucket an.	Nicht konfigurierbar	Diese Variable gibt gegebenenfalls das Verzeichnis an, das eine Kopie Ihrer Modellartefakte enthält.
AIP_VERSION_NAME	Der Wert der `AIP_DEPLOYED_MODEL_ID`-Variablen	Nicht konfigurierbar	Siehe die Zeile `AIP_DEPLOYED_MODEL_ID`. Diese Variable ist aus Kompatibilitätsgründen vorhanden.

In der Ressource `Model` festgelegte Variablen

Wenn Sie ein Model erstellen, können Sie im Feld containerSpec.env zusätzliche Umgebungsvariablen festlegen.

Nächste Schritte

Weitere Informationen zum Bereitstellen von Vorhersagen mit einem benutzerdefinierten Container, einschließlich der Angabe von containerbezogenen API-Feldern beim Importieren eines Modells.