Trainingscode lokal containerisieren und ausführen

Mit dem Befehl gcloud ai custom-jobs local-run können Sie ein Docker-Container-Image basierend auf Ihrem Trainingscode erstellen und das Image als Container auf Ihrem lokalen Computer ausführen. Dieses Feature bietet mehrere Vorteile:

  • Sie können ein Container-Image mit minimalen Kenntnissen von Docker erstellen. Sie müssen kein eigenes Dockerfile schreiben. Später können Sie dieses Image in Artifact Registry hochladen und für das benutzerdefinierte Container-Training verwenden.

    Für erweiterte Anwendungsfälle wollen Sie vielleicht dennoch ein eigenes Dockerfile schreiben.

  • Ihr Container-Image kann eine Python-Trainingsanwendung oder ein Bash-Skript ausführen.

    Sie können ein Bash-Skript verwenden, um Trainingscode auszuführen, der in einer anderen Programmiersprache geschrieben wurde, solange Sie auch ein Basis-Container-Image angeben, das die andere Sprache unterstützt.

  • Wenn Sie einen Container lokal ausführen, wird Ihr Trainingscode auf ähnliche Weise ausgeführt wie in Vertex AI.

    Wenn Sie den Code lokal ausführen, können Sie Probleme mit dem Code beheben, bevor Sie ein benutzerdefiniertes Training in Vertex AI durchführen.

Hinweis

  1. Richten Sie Ihre Vertex AI-Entwicklungsumgebung ein.

  2. Installieren Sie Docker Engine.

  3. Wenn Sie Linux verwenden, konfigurieren Sie Docker so, dass es ohne sudo ausgeführt werden kann.

    Der Befehl local-run erfordert diese Konfiguration, um Docker verwenden zu können.

Den Befehl local-run ausführen

Führen Sie den folgenden Befehl aus, um ein Container-Image basierend auf Ihrem Trainingscode zu erstellen und einen Container lokal auszuführen:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

Dabei gilt:

  • BASE_IMAGE_URI: URI eines Docker-Image, das als Basis des Containers verwendet werden soll. Wählen Sie ein Basis-Image aus, das die für den Trainingscode erforderlichen Abhängigkeiten enthält.

    Sie können den URI für eine Vorgefertigter Trainingscontainer Image oder ein anderer Wert, der für ein Dockerfile FROM Anweisung gültig wäre verwenden; z. B. ein öffentlich verfügbares oder ein Docker-Image, in Artifact Registry auf das Sie Zugriff haben.

  • WORKING_DIRECTORY: Das Verzeichnis der niedrigsten Ebene in Ihrem Dateisystem, das Ihren Trainingscode und lokale Abhängigkeiten enthält, die Sie für das Training verwenden müssen.

    Standardmäßig wird mit dem Befehl nur das übergeordnete Verzeichnis der Datei, die durch das Flag --script angegeben ist (siehe folgendes Listenelement), in das erstellte Docker-Image kopiert. Das Docker-Image enthält nicht alle Dateien in WORKING_DIRECTORY: Um zu bestimmen, welche Dateien einbezogen werden sollen, lesen Sie den Abschnitt Abhängigkeiten einbeziehen dieses Artikels.

    Wenn Sie das Flag --local-package-path (und diesen Platzhalter) weglassen, verwendet der Befehl local-run das aktuelle Arbeitsverzeichnis für diesen Wert.

  • SCRIPT_PATH: Der Pfad, relativ zu WORKING_DIRECTORY in Ihrem lokalen Dateisystem, zu dem Skript, das der Einstiegspunkt für Ihren Trainingscode ist. Dies kann ein Python-Skript (mit der Endung .py) oder ein Bash-Skript sein.

    Wenn Sie beispielsweise /hello-world/trainer/task.py ausführen möchten und WORKING_DIRECTORY auf /hello-world gesetzt ist, verwenden Sie trainer/task.py für diesen Wert.

    Wenn Sie ein Python-Skript angeben, muss Python auf Ihrem Basis-Image installiert sein. Wenn Sie ein Bash-Skript angeben, muss Bash auf Ihrem Basis-Image installiert sein. (Alle vorgefertigten Trainingscontainer und viele andere öffentlich verfügbare Docker-Images enthalten beide Abhängigkeiten.)

    --python-module anstelle von --script verwenden

    Wenn Sie das Flag --script (und SCRIPT_PATH) weglassen, müssen Sie stattdessen das Flag --python-module verwenden, um den Namen eines Python-Moduls in WORKING_DIRECTORY anzugeben, das als Einstiegspunkt für das Training ausgeführt werden soll. Anstelle von --script=trainer/task.py können Sie beispielsweise --python-module=trainer.task angeben.

    Der resultierende Docker-Container lädt in diesem Fall Ihren Code als Modul und nicht als Skript. Sie sollten diese Option vermutlich verwenden, wenn über Ihr Einstiegspunktskript andere Python-Module in WORKING_DIRECTORY importiert werden.

  • OUTPUT_IMAGE_NAME: Ein Name für das resultierende Docker-Image, das vom Befehl erstellt wird. Sie können jeden Wert verwenden, der vom Flag -t von docker build akzeptiert wird.

    Wenn Sie das Image später per Push in Artifact Registry übertragen möchten, können Sie einen Image-Namen verwenden, der die Artifact Registry-Anforderungen erfüllt. Alternativ können Sie das Image später mit zusätzlichen Namen taggen.

    Wenn Sie das Flag --output-image-uri (und diesen Platzhalter) weglassen, taggt der Befehl local-run das Image mit einem Namen entsprechend der aktuellen Uhrzeit und dem Dateinamen des Einstiegspunktskripts.

Der Befehl erstellt ein Docker-Container-Image entsprechend Ihrer Konfiguration. Nach dem Erstellen des Image gibt der Befehl die folgende Ausgabe aus:

A training image is built.
Starting to run ...

Der Befehl verwendet dann sofort dieses Container-Image, um einen Container auf Ihrem lokalen Computer auszuführen. Wenn der Container beendet ist, gibt der Befehl die folgende Ausgabe aus:

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

Zusätzliche Optionen

In den folgenden Abschnitten werden zusätzliche Optionen beschrieben, mit denen Sie das Verhalten des Befehls local-run anpassen können.

Abhängigkeiten installieren

Der Trainingscode kann auf allen Abhängigkeiten basieren, die auf Ihrem Basis-Image installiert sind. Vordefinierte Trainings-Container-Images enthalten beispielsweise viele Python-Bibliotheken für maschinelles Lernen sowie alle Dateien, die Sie in das Docker-Image einfügen, das mit dem Befehl local-run erstellt wurde.

Wenn Sie ein Skript mit dem Flag --script oder --python-module angeben, kopiert der Befehl das übergeordnete Verzeichnis des Skripts und seine Unterverzeichnisse in das Docker-Image. Wenn Sie beispielsweise --local-package-path=/hello-world und --script=trainer/task.py angeben, kopiert der Befehl /hello-world/trainer/ in das Docker-Image.

Sie können auch zusätzliche Python-Abhängigkeiten oder beliebige Dateien aus Ihrem Dateisystem hinzufügen. Führen Sie dazu die zusätzlichen Schritte aus, die in einem der folgenden Abschnitte beschrieben werden:

Zusätzliche Python-Abhängigkeiten installieren

Sie können zusätzliche Python-Abhängigkeiten in das Docker-Image auf verschiedene Arten einbeziehen:

requirements.txt-Datei verwenden

Wenn sich eine Datei mit dem Namen requirements.txt im Arbeitsverzeichnis befindet, wird sie vom Befehl local-run als pip requirements-Datei behandelt und zur Installation von Python-Abhängigkeiten im Docker-Image verwendet.

setup.py-Datei verwenden

Wenn sich im Arbeits-Verzeichnis die Datei setup.py befindet, wird diese mit dem Befehl local-run als Python-Datei setup.py behandelt und in Das Docker-Image kopiert und führt pip install für das Verzeichnis im Docker-Image aus, das diese Datei enthält.

Sie können beispielsweise ein install_requires-Argument zu setup.py hinzufügen, um Python-Abhängigkeiten im Docker-Image zu installieren.

Einzelne PyPI-Abhängigkeiten angeben

Mit dem Flag --requirements können Sie bestimmte Abhängigkeiten aus PyPI im Docker-Image installieren. Beispiel:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

Ersetzen Sie REQUIREMENTS durch eine durch Kommas getrennte Liste von Python-Anforderungsspezifizierern.

Zusätzliche lokale Python-Abhängigkeiten angeben

Mit dem Flag --extra-packages können Sie bestimmte lokale Python-Abhängigkeiten installieren. Diese Python-Abhängigkeiten müssen sich im Arbeitsverzeichnis befinden und jede Abhängigkeit muss in einem von pip install unterstützten Format vorliegen. Das kann beispielsweise eine Wheel-Datei oder eine Python-Quellverteilung sein.

Beispiel:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

Ersetzen Sie LOCAL_DEPENDENCIES durch eine durch Kommas getrennte Liste lokaler Dateipfade, die relativ zum Arbeitsverzeichnis ausgedrückt werden.

Andere Dateien einschließen

Sie können mit dem Flag --extra-dirs weitere Verzeichnisse in das Docker-Image kopieren, ohne sie als Python-Abhängigkeiten zu installieren. Sie können nur Verzeichnisse unter dem Arbeitsverzeichnis angeben. Beispiel:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

Ersetzen Sie EXTRA_DIRECTORIES durch eine durch Kommas getrennte Liste lokaler Verzeichnisse, die relativ zum Arbeitsverzeichnis ausgedrückt werden.

Argumente für die Trainingsanwendung

Wenn das Einstiegspunktskript für Ihre Trainingsanwendung Befehlszeilenargumente erwartet, können Sie diese beim Ausführen des Befehls local-run angeben. Diese Argumente werden nicht im Docker-Image gespeichert. Sie werden stattdessen als Argumente übergeben, wenn das Image als Container ausgeführt wird.

Um Argumente an Ihr Einstiegspunktskript zu übergeben, übergeben Sie das Argument --, gefolgt von den Argumenten Ihres Skripts an den Befehl local-run nach allen anderen Flags des Befehls.

Angenommen, ein Skript wird lokal mit dem folgenden Befehl ausgeführt:

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Wenn Sie den Befehl local-run verwenden, können Sie die folgenden Flags verwenden, um das Skript mit denselben Argumenten im Container auszuführen:

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Modelltraining mit GPUs beschleunigen

Wenn Sie schließlich das Docker-Image (erstellt durch den Befehl local-run) in Vertex AI bereitstellen möchten und GPUs zum Trainieren verwenden möchten, schreiben Sie dann Trainingscode, der GPUs nutzt und verwenden Sie ein GPU-fähiges Docker-Image für den Wert des --executor-image-uri-Flags. Sie können beispielsweise eines der vordefinierten Trainings-Container-Images verwenden, die GPUs unterstützen.

Wenn Ihr lokaler Computer Linux ausführt und GPUs hat, können Sie den Befehl local-run so konfigurieren, dass er Ihre GPUs verwendet, wenn er lokal einen Container ausführt. Dies ist optional, kann aber nützlich sein, wenn Sie testen möchten, wie Ihr Trainingscode mit GPUs funktioniert. Gehen Sie dazu so vor:

  1. Installieren Sie das NVIDIA Container Toolkit (nvidia-docker) auf Ihrem lokalen Computer, falls noch nicht geschehen.

  2. Verwenden Sie das Flag --gpu, wenn Sie den Befehl local-run ausführen: Beispiel:

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

Benutzerdefiniertes Dienstkonto angeben

Wenn der Befehl local-run Ihren Trainingscode in einem lokalen Container ausführt, werden die in Ihrer lokalen Umgebung verfügbaren Google Cloud-Anmeldedaten über Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) im Container bereitgestellt, damit Ihr Trainingscode ADC für die Authentifizierung mit denselben Anmeldedaten verwenden kann. Mit anderen Worten: Die Anmeldedaten, die von ADC in Ihrer lokalen Shell verfügbar sind, sind auch für Ihren Code verfügbar, wenn Sie den Befehl local-run ausführen.

Sie können den Befehl gcloud auth application-default login verwenden, um Ihr Nutzerkonto für ADC zu verwenden, oder in Ihrer Shell können Sie eine Umgebungsvariable auf die Verwendung eines Dienstkontos für ADC festlegen.

Wenn der Container mit anderen Google Cloud-Anmeldedaten als den von ADC in der lokalen Shell verfügbaren ausgeführt werden soll, gehen Sie so vor:

  1. Erstellen oder wählen Sie ein Dienstkonto mit den Berechtigungen aus, auf die Ihr Trainingscode zugreifen soll.

  2. Laden Sie einen Dienstkontoschlüssel für dieses Dienstkonto auf Ihren lokalen Computer herunter.

  3. Wenn Sie den Befehl local-run ausführen, geben Sie das Flag --service-account-key-file an. Beispiel:

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH

    Ersetzen Sie KEY_PATH durch den Pfad zum Dienstkontoschlüssel in Ihrem lokalen Dateisystem. Dieser muss absolut oder relativ zum aktuellen Arbeitsverzeichnis der Shell sein und nicht relativ zum Arbeitsverzeichnis, das durch das Flag --local-package-path angegebenen ist.

Im erstellten Container kann Ihr Trainingscode ADC verwenden, um sich mit den angegebenen Dienstkonto-Anmeldedaten zu authentifizieren.

Vergleich mit Training in Vertex AI

Wenn Sie für Vertex AI benutzerdefiniertes Training durchführen, verwendet Vertex AI standardmäßig den Dienst-Agent für benutzerdefinierten Vertex AI-Code, um den Code auszuführen. Sie können auch ein anderes Dienstkonto anhängen, um benutzerdefiniertes Training durchzuführen.

Wenn Sie den Befehl local-run verwenden, können Sie sich nicht als Dienst-Agent für benutzerdefinierten Vertex AI-Code authentifizieren, aber Sie können ein Dienstkonto mit ähnlichen Berechtigungen erstellen und lokal verwenden.

Nächste Schritte