Anforderungen an benutzerdefinierte Container

Wenn Sie mithilfe eines benutzerdefinierten Containers Vorhersagen bereitstellen möchten, müssen Sie AI Platform Prediction ein Docker-Container-Image zur Verfügung stellen, auf dem ein HTTP-Server ausgeführt wird. In diesem Dokument werden die Anforderungen beschrieben, die ein Container-Image erfüllen muss, damit es mit AI Platform Prediction kompatibel ist. Das Dokument beschreibt auch, wie AI Platform Prediction mit Ihrem benutzerdefinierten Container interagiert, sobald er ausgeführt wird. In diesem Dokument wird also beschrieben, was Sie bei der Entwicklung eines Container-Images zur Verwendung mit AI Platform Prediction beachten müssen.

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 KFServing 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 angeben, wenn Sie Ihre Modellversion erstellen, um die Werte ENTRYPOINT und CMD für das Container-Image 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 dieser "entrypoint"-Befehl 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 eine Modellversion 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

AI Platform Prediction führt eine Aktivitätsprüfung durch, wenn der Container gestartet wird, um zu prüfen, ob der Server ausgeführt wird. Beim Erstellen der Version verwendet AI Platform Prediction eine TCP-Aktivitätsprüfung, um eine TCP-Verbindung zu Ihrem Container auf dem konfigurierten Port herzustellen. Es werden bis zu vier Versuche gestartet, eine Verbindung herzustellen. Warten Sie nach jedem Fehler zehn Sekunden. Wenn dann immer noch keine Verbindung hergestellt wurde, startet AI Platform Prediction 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

AI Platform Prediction führt während der Ausführung zeitweise Systemdiagnosen auf Ihrem HTTP-Server aus, damit 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 beim Erstellen einer Modellversion im Feld routes.health an. 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 für Vorhersageanfragen bereit ist, auf die Systemdiagnose mit dem Statuscode 200 OK antworten. Der Inhalt des Antworttextes spielt keine Rolle; er wird von AI Platform Prediction ignoriert.

    Diese Antwort bedeutet, dass der Server fehlerfrei ist.

  • Wenn der Server nicht für die Verarbeitung von Vorhersageanfragen bereit ist, nicht auf die Systemdiagnoseanfrage antworten bzw. mit keinem Statuscode außer 200 OK antworten. Beispielsweise kann mit dem Statuscode 503 Service Unavailable geantwortet werden.

    Diese Antwort bedeutet, dass der Server fehlerhaft ist.

Wenn die Systemdiagnose eine fehlerhafte Antwort von Ihrem Server empfängt, sendet sie bis zu drei zusätzliche Systemdiagnosen im Abstand von zehn Sekunden. Bis dahin hält AI Platform Prediction Ihren Server für intakt. 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 fehlerhafte Antworten erhält, beendet AI Platform Prediction die Weiterleitung des Vorhersagetraffics an den Container. Wenn die Modellversion auf die Verwendung mehrerer Vorhersageknoten skaliert wird, leitet AI Platform Prediction Vorhersageanfragen an andere fehlerfreie Container weiter.

AI Platform Prediction startet den Container nicht neu. Stattdessen sendet die Systemprüfung 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.predict-Anfrage an die AI Platform Training and Prediction API sendet, leitet AI Platform Prediction diese Anfrage als HTTP-POST-Anfrage an einen konfigurierbaren Pfad auf Ihrem Server weiter. Geben Sie diesen Pfad beim Erstellen einer Modellversion im Feld routes.predict an. Im Abschnitt zur Umgebungsvariable AIP_PREDICT_ROUTE in diesem Dokument erfahren Sie, wie der Container auf diesen Wert zugreifen kann.

AI Platform Prediction validiert Vorhersageanfragen und -antworten nicht. Jede Vorhersageanfrage wird unverändert an den HTTP-Server in Ihrem Container übergeben und die Antworten des Servers werden an den Client übergeben.

Vorhersageanfragen und -antworten dürfen maximal 1,5 MB groß sein. Sie müssen jedoch nicht die anderen Anforderungen an Anfragetexte und Anforderungen an Antworttexte einhalten. Diese gelten nur für Modellversionen, die keinen benutzerdefinierten Container verwenden. Wenn Sie einen benutzerdefinierten Container verwenden, können Sie die Anfrage- und Antworttexte beliebig gestalten.

Wir empfehlen Ihnen jedoch trotzdem, den HTTP-Server so zu gestalten, dass er die in den vorherigen Links beschriebenen Anforderungen für Anfragen und Antworten erfüllt. Wenn Sie das nicht tun, gibt es keine Garantie, dass andere AI Platform Prediction-Features wie Logging, monitoring und AI Explanations ordnungsgemäß funktionieren.

Anforderungen an die Veröffentlichung von Container-Images

Sie müssen Ihr Container-Image in Artifact Registry hochladen, um es mit AI Platform Prediction 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.

Location

Das Repository muss eine Region verwenden, die mit dem regionalen Endpunkt übereinstimmt, für den Sie eine Modellversion erstellen möchten. Wenn Sie beispielsweise eine Modellversion auf dem Endpunkt us-central1-ml.googleapis.com erstellen möchten, muss der vollständige Name des Container-Images mit us-central1-docker.pkg.dev/ beginnen.

Verwenden Sie kein multiregionales Repository für Ihr Container-Image.

Berechtigungen

AI Platform Prediction muss die Berechtigung zum Abrufen des Container-Image haben, wenn Sie eine Modellversion erstellen. Das von AI Platform verwaltete Dienstkonto muss die Berechtigungen der Rolle "Artifact Registry-Leser" (roles/artifactregistry.reader) für das Repository des Container-Image haben.

Wenn Sie das Container-Image in dasselbe Google Cloud-Projekt übertragen haben, in dem Sie AI Platform Prediction verwenden, müssen Sie keine Berechtigungen konfigurieren. Die Standardberechtigungen, die dem von Google verwalteten Dienstkonto zugewiesen sind, reichen aus.

Wenn Sie das Container-Image hingegen nicht in das Google Cloud-Projekt hochgeladen haben, in dem Sie AI Platform Prediction verwenden, müssen Sie dem von Google verwalteten AI Platform-Dienstkonto die Rolle "Artifact Registry-Leser" für das Artifact Registry-Repository erteilen.

Auf Modellartefakte zugreifen

Wenn Sie eine Modellversion ohne benutzerdefinierten Container erstellen, müssen Sie den URI eines Cloud Storage-Verzeichnisses mit Modellartefakten als deploymentUri-Feld angeben. Wenn Sie eine Modellversion mit einem benutzerdefinierten Container erstellen, ist die Bereitstellung 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 deploymentUri angeben, muss der Container diese Artefakte beim Starten der Anwendung laden. Wenn AI Platform Prediction den Container startet, wird die Umgebungsvariable AIP_STORAGE_URI auf einen Cloud Storage-URI festgelegt, der mit gs:// beginnt. Mit dem entrypoint-Befehl Ihres Containers 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 der Modellversion im Feld deploymentUri angegeben haben. AIP_STORAGE_URI verweist stattdessen auf eine Kopie Ihres Modellartefakts in einem anderen Cloud Storage-Bucket, den AI Platform Prediction verwaltet. AI Platform Prediction füllt dieses Verzeichnis aus, wenn Sie eine Modellversion erstellen. Sie können den Inhalt des Verzeichnisses nicht aktualisieren. Wenn Sie neue Modellartefakte verwenden möchten, müssen Sie eine neue Modellversion erstellen.

Das Dienstkonto, das der Container standardmäßig verwendet, hat Lesezugriff auf diesen URI. Wenn Sie allerdings beim Erstellen einer Modellversion ein benutzerdefiniertes Dienstkonto angeben, weist AI Platform Prediction automatisch dem angegebenen Dienstkonto die Rolle "Storage-Objekt-Betrachter" (roles/storage.objectViewer) für den Cloud Storage-Bucket des URI zu.

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.

Da der Container ADC für das von Google verwaltete AI Platform-Dienstkonto oder ein benutzerdefiniertes Dienstkonto unterstützt, sofern Sie eines angegeben haben, kann er auch auf alle anderen Google-Dienste zugreifen, für die das Dienstkonto Berechtigungen hat.

Im Container verfügbare Umgebungsvariablen

Bei der Ausführung kann der entrypoint-Befehl des Containers auf Umgebungsvariablen verweisen, die Sie manuell konfiguriert haben, sowie auf von AI Platform Prediction automatisch festgelegte Umgebungsvariablen. In diesem Abschnitt wird beschrieben, wie Sie Umgebungsvariablen festlegen können. Außerdem erhalten Sie Details zu den Variablen, die von AI Platform Prediction 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 kann diese Umgebungsvariablen verwenden, aber Sie können in keinem der API-Felder Ihrer Modellversion darauf verweisen.

Von AI Platform Prediction festgelegte Variablen

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

Der entrypoint-Befehl des Containers kann auf diese Variablen zugreifen. Informationen dazu, welche AI Platform Training and Prediction API-Felder auch auf diese Variablen verweisen können, finden Sie in der API-Referenz zu ContainerSpec.

Variablenname Standardwert So konfigurieren Sie den Wert Details
AIP_ACCELERATOR_TYPE Nicht festgelegt Wenn Sie eine Modellversion erstellen, legen Sie das Feld acceleratorConfig.type fest. Diese Variable gibt gegebenenfalls den Beschleunigertyp an, der von der VM-Instanz verwendet wird, auf der der Container ausgeführt wird.
AIP_FRAMEWORK CUSTOM_CONTAINER Nicht konfigurierbar
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

Ersetzen Sie in diesem String MODEL durch den Wert der Variable AIP_MODEL_NAME und ersetzen Sie VERSION durch den Wert der Variable AIP_VERSION_NAME.		 Wenn Sie eine Modellversion erstellen, legen Sie das Feld routes.health fest. Diese Variablen legen den HTTP-Pfad im Container fest, an den AI Platform Prediction Systemdiagnosen sendet.
AIP_HTTP_PORT 8080 Wenn Sie eine Modellversion erstellen, legen Sie das Feld containerSpec.ports fest. Der erste Eintrag in diesem Feld wird zum Wert AIP_HTTP_PORT. AI Platform Prediction sendet Aktivitäts-, Systemdiagnose- 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 eine Modellversion erstellen, legen Sie das Feld machineType fest. Diese Variable gibt den VM-Typ an, auf dem der Container ausgeführt wird.
AIP_MODE PREDICTION Nicht konfigurierbar Diese Variable gibt an, dass der Container in AI Platform Prediction zur Bereitstellung von Onlinevorhersagen ausgeführt wird. Sie können diese Umgebungsvariable verwenden, um eine benutzerdefinierte Logik zu Ihrem Container hinzuzufügen, damit sie in mehreren Rechenumgebungen ausgeführt werden kann, aber nur bestimmte Codepfade verwendet werden, wenn sie in AI Platform Prediction ausgeführt wird.
AIP_MODE_VERSION 1.0.0 Nicht konfigurierbar Diese Variable steht für die Version der benutzerdefinierten Anforderungen (dieses Dokument), bei denen AI Platform Prediction erwartet, dass sie vom Container erfüllt werden. Dieses Dokument wird gemäß der semantischen Versionsverwaltung aktualisiert.
AIP_MODEL_NAME Kein Standard, muss konfiguriert werden. Wenn Sie ein Modell erstellen (das übergeordnete Element der Modellversion, die den Containers verwendet), geben Sie das Feld name an. Der Wert enthält nicht das Präfix projects/PROJECT_ID/models/, das von der AI Platform Training and Prediction API ausgegeben wird.
AIP_PREDICT_ROUTE /v1/models/MODEL/versions/VERSION:predict

Ersetzen Sie in diesem String MODEL durch den Wert der Variable AIP_MODEL_NAME und ersetzen Sie VERSION durch den Wert der Variable AIP_VERSION_NAME.		 Wenn Sie eine Modellversion erstellen, legen Sie das Feld routes.predict fest. Diese Variable gibt den HTTP-Pfad des Containers an, an den AI Platform Prediction Vorhersageanfragen weiterleitet.
AIP_PROJECT_NUMBER Die Projektnummer des Google Cloud-Projekts, in dem Sie AI Platform Prediction verwenden Nicht konfigurierbar
AIP_STORAGE_URI
  • Wenn Sie das Feld deploymentUri beim Erstellen einer Modellversion nicht festlegen: ein leerer String
  • Wenn Sie das Feld deploymentUri beim Erstellen einer Modellversion festlegen: ein Cloud Storage-URI (beginnend mit gs://), der ein Verzeichnis in einem Bucket angibt, das von AI Platform Prediction verwaltet wird
 Nicht konfigurierbar Diese Variable gibt gegebenenfalls das Verzeichnis an, das eine Kopie Ihrer Modellartefakte enthält.
AIP_VERSION_NAME Kein Standard, muss konfiguriert werden. Wenn Sie eine Modellversion erstellen, legen Sie das Feld name fest. Der Wert enthält nicht das Präfix projects/PROJECT_ID/models/MODEL/versions/, das von der AI Platform Training and Prediction API ausgegeben wird.

In der Versionsressource festgelegte Variablen

Beim Erstellen einer Modellversion können Sie zusätzliche Umgebungsvariablen im Feld container.env festlegen.

Der entrypoint-Befehl des Containers kann auf diese Variablen zugreifen. Informationen dazu, welche AI Platform Training and Prediction API-Felder auch auf diese Variablen verweisen können, finden Sie in der API-Referenz zu ContainerSpec.

Nächste Schritte