Aangepaste Docker-installatiekopieën gebruiken

Belangrijk

Deze functie bevindt zich in de bètaversie. Om dit te gebruiken, moet een werkruimtebeheerder de preview AI Runtime Beta Features inschakelen via de pagina Previews van de werkruimte. Het is niet compatibel met werkruimtes die gebruikmaken van serverless egress control (SEG).

Met Docker Container Services (DCS) kunt u uw eigen Docker-containerinstallatiekopieën overbrengen naar air workloads. Gebruik een aangepaste image wanneer u deze nodig hebt:

Specifieke systeembibliotheekversies.
Complexe afhankelijkheden die niet schoon in environment.dependenciespassen.
Een exacte omgeving om onderzoeksresultaten te reproduceren.
Standaardimages die zijn gemaakt door het platform- of beveiligingsteam van uw organisatie.

Prerequisites

Installeer de AI Runtime CLI.
Een workspace-beheerder heeft de AI Runtime Beta Features preview ingeschakeld. Raadpleeg Voorbeelden op werkruimteniveau beheren voor instructies.
Voor privé-images: een Docker Hub-account met toegang tot uw image.

Een installatiekopie registreren

Voordat u een workload met een aangepaste installatiekopie uitvoert, moet u deze registreren met air register image. Bij registratie haalt het Databricks-platform de image op en cachet deze. Elke gebruiker moet één keer per imagetag een image registreren. Registreer u alleen opnieuw wanneer u een nieuwe tag pusht of referenties roteert. Registratie duurt 2-6 minuten en blokkeert totdat de afbeelding gereed is.

Openbare afbeeldingen

Registreer openbare installatiekopieën door de URL van de Docker-installatiekopieën en uw Databricks-profiel op te geven:

air register image docker.io/nvidia/cuda:12.9.0-devel-ubuntu24.04 -p my-databricks-profile

De korte afbeeldingsreferentie werkt ook. Bijvoorbeeld: library/ubuntu:latest.

Privé-Docker Hub-afbeeldingen

Als u eerst een persoonlijk toegangstoken wilt genereren om een privé Docker Hub-image te registreren. Klik in uw Docker Hub accountinstellingen op Persoonlijke toegangstokens → Nieuw token genereren. Alleen-lezentoegang is voldoende.

Kies een van de volgende verificatiemethoden:

Meld u aan bij Docker Hub op de terminal. U wordt gevraagd om uw Docker Hub gebruikersnaam en persoonlijk toegangstoken:

docker login

Dit slaat uw aanmeldgegevens op in ~/.docker/config.json. Registreer vervolgens de image — air leest de inloggegevens automatisch:

air register image myorg/myrepo:mytag -p my-databricks-profile

Interactieve verificatie gebruiken

Authenticeer en sla aanmeldgegevens in één stap op in een Databricks secret scope:

air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile

U wordt gevraagd om uw Docker Hub gebruikersnaam en persoonlijk toegangstoken. Inloggegevens worden opgeslagen in de secret scope van uw werkruimte voor toekomstige registraties.

Een vooraf opgeslagen Databricks-geheim gebruiken (aanbevolen voor CI/scripts)

Sla referenties op in een Databricks-geheim en verwijs er rechtstreeks naar:

air register image myorg/myrepo:mytag --scope my-secret-scope --key my-docker-key -p my-databricks-profile

Een Docker-image gebruiken in een workload

Geef de Docker-image op in uw workload-YAML onder environment.docker_image.url:

experiment_name: my-dcs-training
environment:
  docker_image:
    url: myorg/myrepo:mytag
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python /app/train.py

Wanneer u uw eigen Docker-image gebruikt, worden environment.dependencies en environment.version niet ondersteund. Het opgeven van environment.docker_image.url bij een van beide velden veroorzaakt een fout. Als u extra afhankelijkheden hebt, installeert u in plaats daarvan de pakketten in het Dockerfile.

De werklast verzenden:

air run --file workload.yaml -p my-databricks-profile

Omgevingsvariabelen die zijn geïnjecteerd in uw container

AI Runtime injecteert de volgende omgevingsvariabelen in elke container tijdens runtime:

NUM_NODES — totaal aantal knooppunten.
LOCAL_WORLD_SIZE — GPU's per knooppunt.
WORLD_SIZE — totaal aantal processen.
POD_RANK — huidige positie van knooppunt (0 geïndexeerd). Ook ingevoegd als NODE_RANK.
LOCAL_ADDR — IP van lokaal knooppunt (alleen voor meerdere knooppunten).
MASTER_ADDR — rang-0 coördinatieadres (alleen voor meerdere knooppunten).
MASTER_PORT — rank-0-coördinatiepoort (alleen bij configuraties met meerdere knooppunten).

Examples

A10 met één knooppunt

experiment_name: my-dcs-single-node
environment:
  docker_image:
    url: myorg/myrepo:mytag
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python3 /app/train.py

H100 met meerdere knooppunten met RDMA

Voor H100-taken met meerdere knooppunten waarvoor volledige netwerkbandbreedte op AWS p5-exemplaren nodig is, baseert u uw installatiekopie op een van de Databricks-basisinstallatiekopieën met NCCL en EFA vooraf geconfigureerd:

experiment_name: my-dcs-distributed
environment:
  docker_image:
    url: myorg/myrepo:mytag
compute:
  num_accelerators: 16 # 2 nodes × 8 H100
  accelerator_type: GPU_8xH100
command: |-
  torchrun \
    --nnodes="${NUM_NODES}" \
    --nproc_per_node="${LOCAL_WORLD_SIZE}" \
    --node_rank="${POD_RANK}" \
    --rdzv_endpoint="${MASTER_ADDR}:${MASTER_PORT}" \
    /app/train.py

Maak uw eigen image

Wanneer je je eigen image bouwt, raadt Databricks aan om de databricks-ai-runtime skill met een codeeragent te gebruiken of te beginnen met een Databricks-basisimage.

Een coderingsagent gebruiken

Installeer de databricks-ai-runtime Claude Code-skill voor stapsgewijze Dockerfile-richtlijnen, waaronder vanaf nul bouwen, compatibiliteit met CUDA/NCCL/EFA, veelvoorkomende problemen en een checklist vóór het bouwen. Voor deze vaardigheid is Databricks CLI versie 1.0.0 of hoger vereist.

databricks aitools install --skills databricks-ai-runtime --experimental

Databricks-basisinstallatiekopieën

Databricks publiceert basisimages op Docker Hub op databricksruntime/air met CUDA, NCCL en cloudspecifieke netwerkconfiguratie (AWS EFA of Azure InfiniBand) vooraf geconfigureerd.

Tag	Variant	CUDA	Wanneer gebruiken
`dcs-base-azure-runtime`	Runtime	12	Alleen vooraf gebouwde wielen installeren
`dcs-base-azure-devel`	Devel	12	CUDA-extensies compileren (vereist `nvcc`)

Een voorbeeld van een Dockerfile waarin PyTorch wordt toegevoegd aan een Databricks-basisimage. De basisimages bevatten Python op /opt/venv, beheerd door uv. uv pip install is standaard gericht op die omgeving; als u een andere omgeving wilt gebruiken, maakt en activeert u een venv voordat u deze uitvoert uv pip install.

FROM databricksruntime/air:dcs-base-aws-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 /app/train

Bouwen, uploaden en registreren:

docker build -t myorg/myrepo:mytag .
docker push myorg/myrepo:mytag
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile

Requirements

Images moeten worden gehost op Docker Hub. Amazon ECR, Google GCR en GitHub GHCR worden niet ondersteund.
De grootte van de afbeelding moet kleiner zijn dan 20 GB.
WORKDIR wordt tijdens runtime niet gehonoreerd. Gebruik absolute paden voor bestanden die in de afbeelding zijn gebakken. Gebruik bijvoorbeeld python /app/train.py, niet python train.py.
U kunt environment.dependencies of environment.version niet met environment.docker_image.url gebruiken. Als u extra pakketten nodig hebt boven op wat er in de image zit, moet u die aan de Dockerfile toevoegen.

Probleemoplossingsproces

Een aangepaste installatiekopie kan tijdens runtime mislukken met een OpenSSL-fout wanneer een bibliotheek probeert een SSL-context te maken, bijvoorbeeld:

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

De fout wordt weergegeven bij het importeren van bibliotheken die netwerkverbindingen openen, zoals huggingface_huben voorkomt dat ze worden geladen.

Dit gebeurt omdat air workloads worden uitgevoerd op hosts met FIPS-functionaliteit. Wanneer de cryptografische bibliotheken van de image niet FIPS-conform zijn, kan OpenSSL niet initialiseren in de FIPS-modus, waardoor het maken van een SSL-context mislukt.

Aanbevolen oplossing:

Workloads voor ondernemingen, overheid, gezondheidszorg en financiën zijn vaak afhankelijk van FIPS 140-2- of 140-3-naleving voor FedRAMP-, CMMC- of HIPAA-audits. Als uw workload aan FIPS moet blijven voldoen, bouw dan uw image met cryptografische bibliotheken die aan FIPS voldoen.

Als uw workload geen FIPS-naleving vereist, kunt u de FIPS-modus uitschakelen door de OPENSSL_FORCE_FIPS_MODE omgevingsvariabele in te stellen op 0. Daardoor kunnen nalevingseisen ongemerkt worden geschonden.

Als u de FIPS-modus wilt uitschakelen, stelt u deze in uw workload YAML in onder env_variables:

env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

U kunt de variabele ook instellen in uw Dockerfile, zodat deze geldt voor elke workload die de image gebruikt:

ENV OPENSSL_FORCE_FIPS_MODE=0

Verzend de workload opnieuw en bevestig dat de SSL-fout niet meer wordt weergegeven wanneer afhankelijkheden worden geladen.

Zie ook

Feedback

Is deze pagina nuttig?

Last updated on 2026-09-11