Utiliser des images Docker personnalisées

Important

Les images Docker personnalisées pour les charges de travail CLI AI Runtime sont en version bêta.

Docker Container Services (DCS) vous permet d’utiliser votre propre image de conteneur Docker avec les charges de travail air. Utilisez une image personnalisée lorsque vous avez besoin des éléments suivants :

• Versions spécifiques de la bibliothèque système.
• Dépendances complexes qui ne s’intègrent pas correctement dans environment.dependencies.
• Environnement exact pour reproduire les résultats de recherche.
• Images standard créées par l’équipe de sécurité ou de plateforme de votre organisation.

Prerequisites

• Installez l’interface CLI d’AI Runtime.
• Pour les images privées, un compte Docker Hub avec accès à votre image.

Inscrire une image

Avant d’exécuter une charge de travail avec une image personnalisée, inscrivez-la avec air register image. L’enregistrement récupère l’image et la met en cache sur la plateforme Databricks. Chaque utilisateur doit inscrire une image une fois par balise d’image. Réenregistrez-vous uniquement lorsque vous poussez un nouveau tag ou renouvelez les identifiants. L’inscription prend 2 à 6 minutes et bloque jusqu’à ce que l’image soit prête.

Images publiques

Inscrivez des images publiques en fournissant l’URL de l’image Docker et votre profil Databricks :

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

La référence d’image sous forme abrégée fonctionne également. Par exemple : library/ubuntu:latest.

Images de Docker Hub privées

Pour inscrire une image de Docker Hub privée, générez d’abord un jeton d’accès personnel. Dans vos paramètres de compte Docker Hub, cliquez sur Jetons d’accès personnels → Générer un nouveau jeton. L’accès en lecture seule est suffisant.

Choisissez l’une des méthodes d’authentification suivantes :

Utilisation de la connexion Docker (recommandé pour une utilisation interactive)

Connectez-vous à Docker Hub au terminal. Vous serez invité à entrer votre nom d’utilisateur et votre jeton d’accès personnel Docker Hub :

docker login

Cela stocke vos informations d’identification dans ~/.docker/config.json. Inscrivez ensuite l’image : air lit automatiquement les informations d’identification :

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

Utilisation de l’authentification interactive

Authentifiez-vous et stockez des identifiants dans un périmètre de secret Databricks en une seule étape :

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

Vous serez invité à entrer votre nom d’utilisateur et votre jeton d’accès personnel Docker Hub. Les identifiants sont stockés dans le périmètre des secrets de votre espace de travail pour de futurs enregistrements.

Utilisation d’un secret Databricks préenregistré (recommandé pour CI/scripts)

Stockez les informations d’identification dans un secret Databricks et référencez-les directement :

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

Utiliser une image Docker dans une charge de travail

Spécifiez l’image Docker dans le YAML de votre charge de travail, dans 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

Lorsque vous apportez votre propre image Docker, environment.dependencies et environment.version ne sont pas pris en charge. La spécification environment.docker_image.url avec l’un ou l’autre champ déclenche une erreur. Si vous avez des dépendances supplémentaires, installez les packages dans le fichier Dockerfile à la place.

Soumettez la charge de travail :

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

Variables d’environnement injectées dans votre conteneur

AI Runtime injecte les variables d’environnement suivantes dans chaque conteneur au moment de l’exécution :

• NUM_NODES — nombre total de nœuds.
• LOCAL_WORLD_SIZE — GPU par nœud.
• WORLD_SIZE — nombre total de processus.
• POD_RANK — rang actuel du nœud (indexation à partir de 0). Également injecté sous la forme de NODE_RANK.
• LOCAL_ADDR — adresse IP de nœud local (multi-nœud uniquement).
• MASTER_ADDR — adresse de coordination de rang 0 (multinœud uniquement).
• MASTER_PORT — port de coordination de rang 0 (multinœud uniquement).

Exemples

A10 à nœud unique

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 à plusieurs nœuds avec RDMA

Pour les travaux H100 à plusieurs nœuds qui nécessitent une bande passante réseau complète sur des instances AWS p5, basez votre image sur l’une des images de base Databricks avec NCCL et EFA préconfigurées :

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

Créer votre propre image

Pour créer votre propre image, Databricks recommande d’utiliser la compétence databricks-ai-runtime avec un agent de codage ou de partir d’une image de base Databricks.

Utiliser un agent de codage

Installez la compétence Databricks-ai-runtime Claude Code pour obtenir des instructions pas à pas sur Dockerfile, notamment la création à partir de zéro, la compatibilité CUDA/NCCL/EFA, les problèmes courants et une liste de contrôle de pré-build. Cette compétence nécessite Databricks CLI version 1.0.0 ou ultérieure.

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

Images de base Databricks

Databricks publie des images de base sur Docker Hub à l’adresse databricksruntime/air, avec CUDA, NCCL et une mise en réseau spécifique au cloud (AWS EFA ou Azure InfiniBand) préconfigurés.

Tag	Cloud	Variant	À utiliser lorsque
dcs-base-aws-runtime	AWS	Runtime	Installation des wheels précompilées uniquement
dcs-base-aws-devel	AWS	Devel	Compilation d’extensions CUDA (nécessite nvcc)
dcs-base-azure-runtime	Azure	Runtime	Installation des wheels précompilées uniquement
dcs-base-azure-devel	Azure	Devel	Compilation d’extensions CUDA (nécessite nvcc)

Utilisez la variante d’exécution , sauf si votre fichier Dockerfile compile des extensions CUDA telles que flash-attn, apex ou noyaux personnalisés.

Exemple de Dockerfile ajoutant PyTorch à une image de base de Databricks. Les images de base fournissent Python à la version /opt/venv, géré par uv. uv pip install cible cet environnement par défaut ; pour utiliser un autre environnement, créer et activer un venv avant d’exécuter 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

Compiler, pousser et enregistrer :

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

Requirements

• Les images doivent être hébergées sur Docker Hub. Amazon ERC, Google GCR et GitHub GHCR ne sont pas pris en charge.
• La taille de l’image doit être inférieure à 20 Go.
• WORKDIR n’est pas pris en compte à l’exécution. Utilisez des chemins absolus pour les fichiers insérés dans l’image. Par exemple, utilisez python /app/train.py et non python train.py.
• Vous ne pouvez pas utiliser environment.dependencies ou environment.version avec environment.docker_image.url. Si vous avez besoin de packages supplémentaires au-delà de ce qui se trouve dans l’image, vous devez les ajouter au fichier Dockerfile.

Troubleshooting

Ssl. SSLError : [CRYPTO] erreur inconnue (_ssl.c) lors du chargement des dépendances

Une image personnalisée peut échouer lors de l’exécution avec une erreur OpenSSL lorsqu’une bibliothèque tente de créer un contexte SSL, par exemple :

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

L’erreur s’affiche lors de l’importation de bibliothèques qui ouvrent des connexions réseau, telles que huggingface_hub, et les empêchent de charger.

Cela se produit parce que air les charges de travail s’exécutent sur des hôtes compatibles FIPS. Lorsque les bibliothèques de chiffrement de l’image ne sont pas conformes à FIPS, OpenSSL ne parvient pas à s’initialiser en mode FIPS, de sorte que la création d’un contexte SSL échoue.

Solution recommandée :

Les charges de travail d’entreprise, de gouvernement, de santé et de finance dépendent souvent de la conformité FIPS 140-2 ou 140-3 pour les audits FedRAMP, CMMC ou HIPAA. Si votre charge de travail doit rester conforme à FIPS, générez votre image avec des bibliothèques de chiffrement conformes à FIPS.

Si votre charge de travail ne nécessite pas de conformité FIPS, vous pouvez désactiver le mode FIPS en définissant la variable OPENSSL_FORCE_FIPS_MODEd’environnement 0 sur . Cela peut interrompre silencieusement les exigences de conformité.

Pour désactiver le mode FIPS, définissez-le dans votre yaML de charge de travail sous env_variables:

env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

Vous pouvez également définir la variable dans votre fichier Dockerfile afin qu’elle s’applique à chaque charge de travail qui utilise l’image :

ENV OPENSSL_FORCE_FIPS_MODE=0

Renvoyez la charge de travail et confirmez que l’erreur SSL n’apparaît plus lorsque les dépendances se chargent.

Voir aussi

• Démarrage rapide de l’interface CLI AI Runtime
• Référence YAML de la charge de travail
• Informations de référence sur la commande CLI d’AI Runtime