Paket für eine Trainingsanwendung erstellen

Bevor Sie Ihre Trainingsanwendung mit AI Platform Training ausführen können, müssen Sie Ihren Code und alle Abhängigkeiten in einen Cloud Storage-Bucket hochladen, auf den Ihr Google Cloud-Projekt zugreifen kann. Auf dieser Seite erfahren Sie, wie Sie Ihre Anwendung in der Cloud verpacken und bereitstellen.

Die besten Ergebnisse erzielen Sie, wenn Sie Ihre Trainingsanwendung lokal testen, bevor Sie sie in die Cloud hochladen. Bei Trainings mit AI Platform Training werden Ihrem Konto Gebühren für die genutzten Ressourcen berechnet.

Hinweise

Bevor Sie Ihre Trainingsanwendung in die Cloud verschieben können, müssen Sie die folgenden Schritte ausführen:

1. Konfigurieren Sie die Entwicklungsumgebung wie im Startleitfaden erläutert.

2. Entwickeln Sie Ihre Trainingsanwendung mit einem der gehosteten Frameworks für maschinelles Lernen von AI Platform Training: TensorFlow, scikit-learn oder XGBoost. Alternativ können Sie einen benutzerdefinierten Container erstellen, um die Umgebung Ihrer Trainingsanwendung anzupassen. Dies gibt Ihnen die Möglichkeit, andere Frameworks für maschinelles Lernen als die von AI Platform Training gehosteten Frameworks zu verwenden.

   Wenn Sie Ihr trainiertes Modell nach dem Training für AI Platform Prediction bereitstellen möchten, lesen Sie die Anleitung zum Exportieren Ihres Modells zur Vorhersage, damit Ihr Trainingspaket Modellartefakte exportiert, die AI Platform Prediction verwenden kann.

3. Befolgen Sie die Anleitung zum Einrichten eines Cloud Storage-Buckets, in dem Sie die Daten und Dateien der Trainingsanwendung speichern können.

4. Machen Sie sich mit allen Python-Bibliotheken vertraut, auf die Ihre Trainingsanwendung angewiesen ist, ganz gleich, ob es sich um benutzerdefinierte Pakete handelt oder diese frei über PyPI verfügbar sind.

In diesem Dokument werden folgende Faktoren erläutert, die Einfluss darauf haben, wie Sie Ihre Anwendung verpacken und in Cloud Storage hochladen:

• Verwenden der gcloud CLI (empfohlen) oder Code-Erstellung für eine eigene Lösung.
• Bei Bedarf manuelles Erstellen Ihres Pakets.
• Vorgehensweise zum Einbeziehen zusätzlicher Abhängigkeiten, die nicht durch die von Ihnen verwendete Laufzeitumgebung von AI Platform Training installiert werden.

Anwendung mit gcloud verpacken und hochladen (empfohlen)

Die Verwendung der gcloud CLI ist die einfachste Methode, ein Paket für Ihre Anwendung zu erstellen und sie mit ihren Abhängigkeiten hochzuladen: Dabei verwenden Sie einen einzigen Befehl (gcloud ai-platform jobs submit training), um das Anwendungspaket zu erstellen und hochzuladen sowie Ihren ersten Trainingsjob zu senden.

Der Einfachheit halber ist es hilfreich, die Konfigurationswerte als Shell-Variablen zu definieren:

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

Dabei gilt:

• LOCAL_PACKAGE_PATH: Der Pfad zum Verzeichnis Ihres Python-Pakets in Ihrer lokalen Umgebung
• MODULE_NAME: Der vollqualifizierte Name Ihres Trainingsmoduls
• BUCKET_NAME: Name eines Cloud Storage-Buckets
• JOB_NAME: Ein Name für den Trainingsjob
• JOB_OUTPUT_PATH: Der URI eines Cloud Storage-Verzeichnisses, in dem Ihr Trainingsjob seine Ausgabe speichern soll
• REGION: Region, in der Sie den Trainingsjob ausführen möchten

Weitere Informationen zu den Anforderungen für diese Werte finden Sie in der Liste nach dem folgenden Befehl.

Im folgenden Beispiel wird gezeigt, wie Sie mit dem Befehl gcloud ai-platform jobs submit training eine Anwendung verpacken und einen Trainingsjob senden.

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

• --staging-bucket gibt einen Cloud Storage-Bucket an, in dem Sie Ihre Trainings- und Abhängigkeitspakete bereitstellen möchten. Ihr Google Cloud-Projekt muss Zugriff auf diesen Cloud Storage-Bucket haben. Außerdem muss sich der Bucket in derselben Region befinden, in der Sie den Job ausführen. Hier finden Sie die Regionen, in denen AI Platform Training-Dienste verfügbar sind. Wenn Sie keinen Staging-Bucket angeben, stellt AI Platform Training Ihre Pakete an dem im Parameter job-dir angegebenen Speicherort bereit.

• --job-dir gibt den Cloud Storage-Speicherort an, den Sie für die Ausgabedateien Ihres Trainingsjobs verwenden möchten. Ihr Google Cloud-Projekt muss Zugriff auf diesen Cloud Storage-Bucket haben. Außerdem sollte sich der Bucket in derselben Region befinden, in der Sie den Job ausführen. Hier finden Sie die Regionen, in denen die Dienste von AI Platform Training verfügbar sind.

• --package-path gibt den lokalen Pfad zum Verzeichnis der Anwendung an. Die gcloud CLI erstellt ein .tar.gzDistributionspaket- aus Ihrem Code anhand der Datei setup.py im übergeordneten Verzeichnis des mit --package-path angegebenen Verzeichnisses. Anschließend wird diese .tar.gz-Datei in Cloud Storage hochgeladen und zum Ausführen Ihres Trainingsjobs verwendet.

  Wenn am erwarteten Speicherort keine setup.py-Datei vorhanden ist, erstellt die gcloud CLI eine einfache, temporäre setup.py-Datei. In die .tar.gz-Datei, die es erstellt, wird nur das Verzeichnis aufgenommen, das in --package-path angegeben ist.

• --module-name gibt den Namen des Hauptmoduls der Anwendung unter Verwendung der Namespace-Punktnotation des Pakets an. Dies ist die Python-Datei, die Sie zum Starten der Anwendung ausführen. Wenn Ihr Hauptmodul zum Beispiel .../my_application/trainer/task.py ist (weitere Informationen unter empfohlene Projektstruktur), lautet der Name des Moduls trainer.task.

• Wenn Sie eine Option sowohl in der Konfigurationsdatei (config.yaml) als auch als Befehlszeilen-Flag angeben, wird der Wert in der Konfigurationsdatei durch den Wert in der Befehlszeile überschrieben.
• Das leere Flag -- markiert das Ende der gcloud-spezifischen Flags und den Anfang der USER_ARGS, die Sie an die Anwendung übergeben möchten.
• Spezifische Flags von AI Platform Training, wie --module-name, --runtime-version und --job-dir, müssen vor dem leeren Flag -- stehen. Der AI Platform Training-Dienst interpretiert diese Flags.
• Das Flag --job-dir muss, falls es angegeben wird, vor dem leeren Flag -- stehen, weil AI Platform Training --job-dir verwendet, um den Pfad zu validieren.
• Wenn das Flag --job-dir angegeben wird, muss es auch von der Anwendung verarbeitet werden. Das Flag --job-dir steht zwar vor dem leeren Flag --, es wird aber trotzdem als Befehlszeilen-Flag an die Anwendung übergeben.
• Sie können beliebig viele USER_ARGS definieren. AI Platform Training übergibt --user_first_arg, --user_second_arg usw. an Ihre Anwendung.

Weitere Informationen zu Jobübermittlungs-Flags finden Sie unter Trainingsjob ausführen.

Mit Abhängigkeiten arbeiten

Abhängigkeiten sind Pakete, die Sie in Ihren Code importieren (import). Ihre Anwendung kann viele Abhängigkeiten haben, ohne die sie nicht richtig funktioniert.

Wenn Sie einen Trainingsjob in AI Platform Training ausführen, wird der Job auf Trainingsinstanzen ausgeführt (speziell konfigurierte virtuelle Maschinen), auf denen bereits viele gängige Python-Pakete installiert sind. Prüfen Sie die Pakete, die in der für das Training verwendeten Laufzeitversion enthalten sind, und notieren Sie sich die benötigten Abhängigkeiten, die noch nicht installiert sind.

Es gibt zwei Arten von Abhängigkeiten, die Sie eventuell hinzufügen müssen:

• Standardabhängigkeiten, also häufig genutzte Python-Pakete, die auf PyPI zur Verfügung stehen.
• Benutzerdefinierte Pakete, also z. B. selbst entwickelte oder unternehmensinterne Pakete.

In den folgenden Abschnitten wird die Vorgehensweise für jede Art beschrieben.

Standardabhängigkeiten (PyPI) hinzufügen

Sie können die Standardabhängigkeiten Ihres Pakets im zugehörigen setup.py-Skript angeben. AI Platform Training verwendet pip zur Installation des Pakets auf den Trainingsinstanzen, die es für Ihren Job zuweist. Mit dem Befehl pip install können Sie nach konfigurierten Abhängigkeiten suchen und diese installieren.

Erstellen Sie im Stammverzeichnis der Anwendung eine Datei mit dem Namen setup.py. Das Stammverzeichnis befindet sich im Verzeichnis über dem Verzeichnis trainer, wenn Sie sich an das empfohlene Muster halten.

Geben Sie in setup.py folgendes Skript mit Ihren eigenen Werten ein:

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application package.'
)

Wenn Sie den Trainingsjob mit der Google Cloud CLI senden, wird zum Erstellen des Pakets automatisch die Datei setup.py verwendet.

Wenn Sie den Trainingsjob nicht mit gcloud senden, verwenden Sie zum Ausführen des Skripts diesen Befehl:

python setup.py sdist

Weitere Informationen finden Sie unter Paket manuell erstellen.

Benutzerdefinierte Abhängigkeiten hinzufügen

Sie können die benutzerdefinierten Abhängigkeiten der Anwendung angeben, indem Sie deren Pfade als Teil der Jobkonfiguration übergeben. Dazu benötigen Sie den URI zu jedem Abhängigkeitspaket. Benutzerdefinierte Abhängigkeiten müssen sich an einem Cloud Storage-Speicherort befinden. AI Platform Training verwendet pip install benutzerdefinierte Abhängigkeiten zu installieren, damit sie Standardabhängigkeiten von ihre eigenen in setup.py-Skripts.

Wenn Sie den Trainingsjob mit der gcloud CLI ausführen, können Sie Abhängigkeiten auf Ihrem lokalen Computer sowie in Cloud Storage angeben. Das Tool stellt sie dann in der Cloud bereit: Wenn Sie den Befehl gcloud ai-platform jobs submit training ausführen, legen Sie mit dem Flag --packages die Abhängigkeiten in einer durch Kommas getrennten Liste fest.

Jeder URI, den Sie angeben, ist der Pfad zu einem Distributionspaket im Format Tarball (.tar.gz) oder als Wheel (.whl) verwendet werden. AI Platform Training-Installationen jeweils Paket mit pip install auf jeder virtuellen Maschine, die er für Ihren Trainingsjob zuweist.

Im folgenden Beispiel werden Abhängigkeitspakete mit den Namen dep1.tar.gz und dep2.whl (eines für jede unterstützte Paketart) verwendet, wobei ein Pfad zum Quellcode der Anwendung einbezogen wird:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Ebenso werden im folgenden Beispiel Abhängigkeitspakete mit den Namen dep1.tar.gz und dep2.whl (eines für jede unterstützte Paketart) verwendet, wobei jedoch eine erstellte Trainingsanwendung einbezogen wird:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Wenn Sie Trainingsjobs direkt mit der AI Platform Training and Prediction API ausführen, müssen Sie die Abhängigkeitspakete selbst an einem Cloud Storage-Speicherort bereitstellen und dann die Pfade zu den Paketen an diesem Speicherort verwenden.

Paket manuell erstellen

Die Paketerstellung für Python-Code ist ein umfassendes Thema, das den Rahmen dieser Dokumentation sprengen würde. Als Referenz enthält dieser Abschnitt aber eine Übersicht zum Erstellen eines Pakets mit Setuptools. Es gibt auch noch andere Bibliotheken, die Sie für diesen Zweck verwenden können.

Hinweis: Sie brauchen das Paket nicht manuell zu erstellen, auch dann nicht, wenn Sie bei der Installation des Anwendungspakets verschiedene Einrichtungsvorgänge ausführen müssen. Sie können stattdessen eine benutzerdefinierte __init__.py-Datei in das Stammverzeichnis des Pakets einfügen und das Paket mit der Google Cloud CLI erstellen und hochladen. Wenn Sie --package-path beim Ausführen des Befehls gcloud ai-platform jobs submit mit aufnehmen, sucht das Tool automatisch nach zu verwendenden __init__.py-Dateien.

So können Sie Ihr Paket manuell erstellen:

1. Fügen Sie in jedes Verzeichnis des Anwendungspakets eine Datei mit dem Namen __init__.py ein. Diese Datei kann leer sein oder Code enthalten, der beim Importieren des jeweiligen Pakets (beliebiges Modul in diesem Verzeichnis) ausgeführt wird.

2. Fügen Sie in das übergeordnete Verzeichnis des gesamten Codes, den Sie in Ihr .tar.gz-Distributionspaket aufnehmen möchten (dieses Verzeichnis befindet sich eine Ebene über dem Verzeichnis trainer, wenn Sie sich an das empfohlene Muster halten), die Setuptools-Datei mit dem Namen setup.py ein, die Folgendes enthält:

   • Importanweisungen für setuptools.find_packages und setuptools.setup.

   • Einen Aufruf von setuptools.setup mit mindestens diesen Parametern, die so festgelegt sind:

     • _name ist auf den Namen des Paket-Namespace festgelegt.

     • _version ist auf die Versionsnummer des jeweiligen Paket-Builds festgelegt.

     • _install_requires ist auf eine Liste von Paketen festgelegt, die die Anwendung benötigt, mit Versionsanforderungen wie 'docutils>=0.3'.

     • _packages ist auf find_packages() festgelegt. Dieser Parameter weist Setuptools an, alle Unterverzeichnisse des übergeordneten Verzeichnisses einzuschließen, die eine __init__.py-Datei enthalten. Sie werden dann als "Importpakete" Ihrem "Distributionspaket", der Datei .targ.gz mit dem gesamten Code, hinzugefügt (Sie importieren Module aus "Importpaketen" in Python mit Befehlen wie from trainer import util).

     • _include_package_data ist auf True festgelegt.

3. Führen Sie python setup.py sdist aus, um das Distributionspaket .tar.gz zu erstellen.

Empfohlene Projektstruktur

Sie können die Trainingsanwendung beliebig strukturieren. Allerdings wird die folgende Struktur häufig in AI Platform Training-Beispielen verwendet. Wenn Sie Ihr Projekt so ähnlich wie die Beispiele aufbauen, können Sie sie unter Umständen leichter nachvollziehen.

• Verwenden Sie ein Hauptprojektverzeichnis, das die Datei setup.py enthält.

  Rufen Sie die Funktion find_packages() von setuptools in Ihrer Datei setup.py auf, damit alle Unterverzeichnisse in das von Ihnen erstellte .tar.gz-Distributionspaket aufgenommen werden.

• Verwenden Sie ein Unterverzeichnis mit dem Namen trainer, um das Hauptanwendungsmodul zu speichern.

• Geben Sie dem Hauptanwendungsmodul den Namen task.py.

• Erstellen Sie im Hauptverzeichnis des Projekts alle anderen Unterverzeichnisse, die Sie zum Implementieren der Anwendung benötigen.

• Erstellen Sie in jedem Unterverzeichnis eine Datei namens __init__.py. Diese Dateien werden von Setuptools verwendet, um Verzeichnisse mit Code zu ermitteln, für den ein Paket erstellt werden soll. Die Dateien können auch leer sein.

In den Beispielen für AI Platform Training enthält das Verzeichnis trainer in der Regel folgende Quelldateien:

• task.py enthält die Anwendungslogik, die den Trainingsjob verwaltet.

• model.py enthält die Logik des Modells.

• util.py enthält, sofern vorhanden, Code zum Ausführen der Trainingsanwendung.

Setzen Sie --package-path beim Ausführen von gcloud ai-platform jobs submit training auf trainer. Dadurch sucht die gcloud CLI nach einer setup.py-Datei im übergeordneten Verzeichnis von trainer, Ihrem Hauptprojektverzeichnis.

Python-Module

Das Anwendungspaket kann mehrere Module (Python-Dateien) enthalten. Sie müssen das Modul identifizieren, das den Einstiegspunkt für Ihre Anwendung enthält. Der Trainingsdienst führt dieses Modul mit einem Python-Aufruf aus, genau wie bei einer lokalen Ausführung.

Beispielsweise ist das Hauptmodul task.py, wenn Sie der empfohlenen Struktur aus dem vorherigen Abschnitt folgen. Da es sich in einem Importpaket (Verzeichnis mit einer __init__.py-Datei) namens trainer befindet, lautet der voll qualifizierte Name dieses Moduls trainer.task. Wenn Sie also Ihren Job mit gcloud ai-platform jobs submit training senden, legen Sie das Flag --module-name auf trainer.task fest.

Weitere Informationen zu den Modulen finden Sie in der Python-Anleitung zu Paketen.

Vorhandenes Paket mit der gcloud-CLI hochladen

Wenn Sie das Paket selbst erstellen, können Sie es mit der gcloud CLI hochladen. Führen Sie den Befehl gcloud ai-platform jobs submit training aus:

• Legen Sie das Flag --packages auf den Pfad zum Anwendungspaket fest.

• Legen Sie das Flag --module-name unter Verwendung der Namespace-Punktnotation des Pakets auf den Namen des Hauptmoduls der Anwendung fest. Dies ist die Python-Datei, die Sie zum Starten der Anwendung ausführen. Wenn Ihr Hauptmodul zum Beispiel .../my_application/trainer/task.py ist (weitere Informationen unter empfohlene Projektstruktur), lautet der Name des Moduls trainer.task.

Im folgenden Beispiel wird gezeigt, wie Sie ein komprimiertes Tarball-Paket (hier als trainer-0.0.1.tar.gz bezeichnet) verwenden, das sich im selben Verzeichnis befindet, in dem Sie den Befehl ausführen. Die Hauptfunktion befindet sich in einem Modul namens task.py:.

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Bereits in der Cloud vorhandenes Paket mit der gcloud-CLI verwenden

Wenn Sie das Paket selbst erstellen und in einen Cloud Storage-Speicherort hochladen, können Sie dafür das gcloud-Tool verwenden. Führen Sie den Befehl gcloud ai-platform jobs submit training aus:

• Legen Sie das Flag --packages auf den Pfad zum Anwendungspaket fest.

• Legen Sie das Flag --module-name unter Verwendung der Namespace-Punktnotation des Pakets auf den Namen des Hauptmoduls der Anwendung fest. Dies ist die Python-Datei, die Sie zum Starten der Anwendung ausführen. Wenn Ihr Hauptmodul zum Beispiel .../my_application/trainer/task.py ist (weitere Informationen unter empfohlene Projektstruktur), lautet der Name des Moduls trainer.task.

Im folgenden Beispiel wird gezeigt, wie Sie ein komprimiertes Tarball-Paket verwenden, das sich in einem Cloud Storage-Bucket befindet:

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Dabei ist $PATH_TO_PACKAGED_TRAINER eine Umgebungsvariable, die den Pfad zu einem bereits in der Cloud vorhandenen Paket angibt. Der Pfad könnte beispielsweise auf den folgenden Cloud Storage-Speicherort verweisen, der ein komprimiertes Tarball-Paket mit dem Namen trainer-0.0.1.tar.gz enthält:

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

Pakete manuell hochladen

Sie können Ihre Pakete manuell hochladen, wenn es dafür einen Grund gibt. Der häufigste Grund ist, dass Sie die AI Platform Training and Prediction API direkt aufrufen möchten, um Ihren Trainingsjob zu starten. Der einfachste Weg, Ihr Paket und Ihre benutzerdefinierten Ihrem Cloud Storage-Bucket hinzufügen, besteht darin, gcloud storage-Befehl-Tool:

gcloud storage cp /local/path/to/package.tar.gz  gs://bucket/path/

Wenn Sie für diesen Vorgang jedoch die Befehlszeile nutzen können, müssen Sie einfach nur gcloud ai-platform jobs submit training verwenden, um Ihre Pakete beim Einrichten eines Trainingsjobs hochzuladen. Sollte die Verwendung der Befehlszeile nicht möglich sein, können Sie die Cloud Storage-Clientbibliothek verwenden, um den Upload programmgesteuert durchzuführen.

Weitere Informationen

• Trainingsjob konfigurieren und ausführen
• Trainingsjob während der Ausführung überwachen
• Funktionsweise des Trainings