Verwenden Sie benutzerdefinierte Docker-Images mit AI Runtime

Important

Dieses Feature befindet sich in der Public Preview. Um sie zu verwenden, muss ein Workspace-Administrator die Databricks Artifact Registry-Vorschau auf der Seite der Vorschauen des Arbeitsbereichs aktivieren.

AI Runtime kann Ihre Workload in einem benutzerdefinierten Docker-Container-Image statt in einer verwalteten Umgebung ausführen. Sie erstellen das Image für linux/amd64, geben es in Ihrem Arbeitsbereich in die Artifact Registry und verweisen auf den Namen des Unity-Katalogs in der Workload-YAML, die Sie mit der Databricks-CLI einreichen. Verwenden Sie bei Bedarf ein benutzerdefiniertes Bild:

  • Systembibliotheken oder komplexe Abhängigkeiten, die Sie nicht mit environment.dependencies installieren können.
  • CUDA-Erweiterungen, die Sie aus dem Quellcode kompilieren, wie flash-attn oder benutzerdefinierte Kernel.
  • Eine reproduzierbare Umgebung über Entwicklung, Forschung und Produktion hinweg.
  • Private, von der Organisation genehmigte Bilder, erstellt von Ihrer Plattform oder Ihrem Sicherheitsteam.

Prerequisites

Übertragen Sie ein Image in die Artifact Registry

Bevor Sie ein benutzerdefiniertes Image mit AI Runtime verwenden, speichern Sie es im Artifact Registry im selben Arbeitsbereich, mit dem Sie die Arbeitslast einreichen. Informationen zum Erstellen eines Images finden Sie unter Erstellen Sie Ihr eigenes Bild.

  1. Erstellen oder wählen Sie einen Unity Catalog-Katalog und ein Schema für das Image aus und erhalten Sie die erforderlichen Artifact Registry-Berechtigungen.

  2. Ein OAuth-Profil für den Arbeitsbereich erstellen oder aktualisieren:

    databricks auth login --profile my-databricks-profile
    

    Der Docker-Anmeldeinformations-Helfer erfordert ein Profil, das mit databricks auth login erstellt wurde. Es unterstützt keine Profile, die persönliche Zugriffstoken oder OAuth-Maschinen-zu-Maschine (M2M)-Anmeldedaten verwenden.

  3. Um Docker zu authentifizieren, taggen Sie das Bild und pushen Sie es in einem Schritt, führen Sie den databricks air images push Helper aus:

    databricks air images push \
      --profile my-databricks-profile \
      --source my-training-image:v1 \
      --catalog main \
      --schema ml \
      --artifact training:v1
    

    Weitere Optionen, einschließlich des Kopierens eines Images aus einer anderen Registry, finden Sie unter Push-Images mit der Databricks-CLI.

    Um stattdessen mit docker push zu pushen, führen Sie databricks auth docker configure --profile my-databricks-profile aus, um den Docker-Anmeldedatenhelfer zu konfigurieren, und folgen Sie dann Push an image im Artifact Registry-Leitfaden.

  4. Beachten Sie den Unity Catalog-Namen des Image im folgenden Format:

    <catalog>.<schema>.<image>:<tag>
    

    Beispiel: main.ml.training:v1 Fügen Sie den Registry-Hostnamen nicht in die Workload-Konfiguration ein.

Verwenden Sie ein Docker-Image in einer Workload

Geben Sie den Unity Catalog-Namen des Images in Ihrer Workload-YAML-Datei unter environment.unity_catalog_image an:

experiment_name: my-dcs-training
environment:
  unity_catalog_image: main.ml.training:v1
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python /app/train.py

Dieses Beispiel verläuft von train.py bis /app im Image. Um Anwendungscode separat hochzuladen, ohne das Bild neu zu erstellen, siehe Ausführen hochgeladener Anwendungscode.

Wenn Sie ein eigenes Docker-Image verwenden, werden environment.dependencies und environment.version nicht unterstützt. Die Angabe environment.unity_catalog_image mit beiden Feldern löst einen Fehler aus. Wenn Sie über zusätzliche Abhängigkeiten verfügen, installieren Sie stattdessen die Pakete in der Dockerfile-Datei.

Übermitteln Sie die Arbeitsauslastung:

databricks air run -f workload.yaml --watch -p my-databricks-profile

Das Profil muss sich im selben Arbeitsbereich authentifizieren, in dem das Bild gespeichert ist.

Schein

Wenn AI Runtime Ihre Workload außerhalb der Heimatregion Ihres Arbeitsbereichs ausführt, verschiebt sich Ihr benutzerdefiniertes Bild mit der Workload in die Region, in der es ausgeführt wird. Weitere Informationen unter Verfügbarkeit von AI Runtime nach Geografie.

Wenn Ihre Workload in einer anderen Region als der Ihres Arbeitsbereichs läuft, könnte Azure Databricks Ihr benutzerdefiniertes Docker-Image in dieser Region zwischenspeichern, um spätere Workloads zu beschleunigen. Azure Databricks löscht ein zwischengespeichertes Image automatisch, nachdem es 30 Tage lang ungenutzt bleibt.

In Ihren Container eingefügte Umgebungsvariablen

KI-Runtime fügt die folgenden Umgebungsvariablen in jeden Container zur Laufzeit ein:

  • CODE_SOURCE_PATH: Pfad zum hochgeladenen Anwendungscode, wenn code_source konfiguriert ist.
  • NUM_NODES: Gesamtzahl der Knoten.
  • LOCAL_WORLD_SIZE: GPUs je Knoten.
  • WORLD_SIZE: Gesamtzahl der Prozesse.
  • POD_RANK: aktueller Knotenrang (0-indexiert). Auch eingefügt als NODE_RANK.

Examples

Das folgende Beispiel zeigt, wie hochgeladener Anwendungscode mit einem eigenen Image ausgeführt werden kann.

Ausführen Sie hochgeladenen Anwendungscode

Verwenden Sie code_source es, um den Anwendungscode separat vom Bild hochzuladen. Du kannst deinen Code bearbeiten und erneut einreichen, ohne das Bild neu zu erstellen. Installiere die Python- und Systemabhängigkeiten des Codes im Image.

Platziere train.py in einem lokalen src-Verzeichnis neben workload.yaml. Die folgende Konfiguration lädt src hoch und führt train.py im benutzerdefinierten Image aus:

experiment_name: my-dcs-uploaded-code
environment:
  unity_catalog_image: main.ml.training:v1
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
code_source:
  root_path: ./src
command: |-
  cd "$CODE_SOURCE_PATH"
  python3 train.py

root_path resolviert relativ zu workload.yaml. AI Runtime setzt $CODE_SOURCE_PATH auf den Pfad des hochgeladenen Verzeichnisses im Container. Siehe code_source für Code-Quelloptionen.

Bauen Sie Ihr eigenes Image auf

Beim Erstellen eines eigenen Bilds empfiehlt Databricks, databricks-ai-runtime mit einem Coding-Agent zu verwenden oder mit einem Databricks-Basis-Bild zu beginnen.

Sie können auch von einem anderen Basisbild ausgehen, zum Beispiel nvidia/cuda. In diesem Fall muss das Image eine CUDA-Laufzeit enthalten, die vom Host-GPU-Treiber unterstützt wird, sowie NCCL für die Multi-GPU-Kommunikation. Die Fähigkeit databricks-ai-runtime umfasst den Aufbau eines Images von Grund auf.

Verwenden eines Codierungs-Agents

Installieren Sie den databricks-ai-runtime-Claude-Code-Skill für eine schrittweise Anleitung zu Dockerfiles, einschließlich der Erstellung von Grund auf, der CUDA/NCCL/EFA-Kompatibilität, häufiger Probleme und einer Checkliste vor dem Build. Diese Fähigkeit erfordert Databricks CLI Version 1.0.0 oder höher.

databricks aitools install --skills databricks-ai-runtime

Databricks-Basisbilder

Databricks veröffentlicht Basis-Images auf Docker Hub unter databricksruntime/air mit vorkonfiguriertem CUDA, NCCL und cloud-spezifischer Netzwerkkonfiguration (AWS EFA oder Azure InfiniBand).

Tag Variante CUDA Verwenden Sie, wenn
dcs-base-azure-runtime Runtime 12 Nur vorinstallierte Räder installieren
dcs-base-azure-devel Entwi 12 Kompilieren von CUDA-Erweiterungen (erfordert nvcc)

Das folgende Dockerfile fügt PyTorch einem Databricks-Basisimage hinzu. Die Basisbilder stellen Python unter /opt/venv bereit, das von uv verwaltet wird. uv pip install Standardmäßig zielt sie auf diese Umgebung ab. Um eine andere Umgebung zu verwenden, erstellen und aktivieren Sie eine venv, bevor Sie uv pip install ausführen.

Um dein Trainingsskript ins Bild einzubinden, platziere train.py es neben die Dockerfile. Das Dockerfile kopiert es nach /app/train.py. Wenn du Anwendungscode mit code_sourcehochlädst, lasse die COPY Anleitung weg und behalte train.py stattdessen im Quellverzeichnis.

FROM databricksruntime/air:dcs-base-azure-runtime

RUN uv pip install --no-cache \
    torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0

RUN uv pip install --no-cache \
    transformers==4.45.0 \
    accelerate==0.34.0 \
    'mlflow>=3.6'

COPY ./train.py /app/train.py

Bilder müssen die linux/amd64 Plattform nutzen. Auf einem Mac mit Apple Silicon erstellt Docker standardmäßig arm64-Images, daher sollte man immer --platform linux/amd64 übergeben. Um das Image lokal zu erstellen, führen Sie Folgendes aus:

docker build --platform linux/amd64 -t my-training-image:v1 .

Dann übertrage das Image in die Artifact Registry und verwende den resultierenden <catalog>.<schema>.<image>:<tag> Namen wie environment.unity_catalog_image im Workload-YAML.

Limitations

  • Bilder müssen im Artefaktregister im Arbeitsbereich gespeichert werden, in dem Sie die Workload einreichen.
  • Die Bildgröße muss unter 20 GB betragen.
  • WORKDIR wird zur Laufzeit nicht berücksichtigt. Verwenden Sie absolute Pfade für Dateien, die in das Bild integriert sind. Verwenden Sie beispielsweise python /app/train.py, nicht python train.py.
  • Sie können environment.dependencies oder environment.version nicht mit environment.unity_catalog_image verwenden. Wenn Sie zusätzliche Pakete benötigen, die über das Image hinausgehen, müssen Sie sie der Dockerfile-Datei hinzufügen.

Troubleshooting

Bei Authentifizierungs-, Berechtigungs-, Image-Push- oder Image-Erkennungsfehlern im Zusammenhang mit der Registry siehe Fehlerbehebung für Artifact Registry.

Docker Credential Helper erfordert ein Profil, das durch Databricks-Authentifizierungslogin erstellt wurde

Das Pushen eines Images schlägt mit einem Fehler wie dem folgenden fehl:

Error: profile "my-profile" uses auth_type "". Docker credential helper requires a profile created by databricks auth login

Dieser Fehler tritt auf, wenn das Profil ein persönliches Zugriffstoken oder eine andere Authentifizierungsmethode verwendet, die vom Docker-Anmeldedatenhilfer nicht unterstützt wird. Erstellen Sie ein OAuth-Workspace-Profil und führen Sie den Push mit diesem Profil erneut aus:

databricks auth login --profile my-databricks-profile

Mehrere Profile stimmen mit der Arbeitsbereichs-ID überein

Die Konfiguration der Docker-Authentifizierung oder das Pushen eines Images schlägt mit einem Fehler wie dem folgenden fehl:

Error: multiple Databricks profiles match workspace ID 1111111111111111: profile-a and profile-b. Remove duplicate workspace_id entries before using Docker credential helper

Dieser Fehler tritt auf, wenn mehr als ein Profil in Ihrer Konfigurationsdatei (~/.databrickscfg standardmäßig) auf denselben Arbeitsbereich verweist. Entfernen Sie das Profil, das Sie für Docker nicht verwenden, und führen Sie den Befehl mit dem verbleibenden Profil erneut aus. Um sich aus einem Profil abzumelden und es aus der Konfigurationsdatei zu entfernen, führen Sie Folgendes aus:

databricks auth logout --profile profile-a --delete

Für alle Abmeldeoptionen siehe auth Befehlsgruppe.

ssl.SSLError beim Laden von Abhängigkeiten

Ein benutzerdefiniertes Bild kann zur Laufzeit mit einem OpenSSL-Fehler fehlschlagen, wenn eine Bibliothek versucht, einen SSL-Kontext zu erstellen, z. B.:

ssl.SSLError: [CRYPTO] unknown error (_ssl.c:3076)

Der Fehler tritt beim Importieren von Bibliotheken auf, die Netzwerkverbindungen öffnen, wie z. B. huggingface_hub, und verhindert, dass sie geladen werden.

Dies geschieht, weil KI-Laufzeit-Workloads auf Hosts mit Federal Information Processing Standards (FIPS) aktiviert laufen. Wenn die kryptografischen Bibliotheken des Bilds nicht FIPS-kompatibel sind, kann OpenSSL nicht im FIPS-Modus initialisiert werden, sodass das Erstellen eines SSL-Kontexts fehlschlägt.

Empfohlene Lösung:

Unternehmens-, Regierungs-, Gesundheits- und Finanzarbeitslasten hängen häufig von FIPS 140-2- oder 140-3-Compliance für FedRAMP-, CMMC- oder HIPAA-Audits ab. Wenn Ihre Workload FIPS-kompatibel bleiben muss, erstellen Sie Ihr Image mit FIPS-kompatiblen kryptografischen Bibliotheken.

Wenn Ihre Workload keine FIPS-Compliance erfordert, können Sie den FIPS-Modus deaktivieren, indem Sie die OPENSSL_FORCE_FIPS_MODE Umgebungsvariable auf 0festlegen. Dies kann unbemerkt gegen Compliance-Anforderungen verstoßen.

Um den FIPS-Modus zu deaktivieren, legen Sie ihn in Ihrer Workload YAML unter env_variables:

env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

Alternativ können Sie die Variable in Ihrer Dockerfile-Datei so festlegen, dass sie für jede Workload gilt, die das Image verwendet:

ENV OPENSSL_FORCE_FIPS_MODE=0

Übermitteln Sie die Workload erneut, und bestätigen Sie, dass der SSL-Fehler nicht mehr angezeigt wird, wenn Abhängigkeiten geladen werden.

Weitere Ressourcen