Utiliser des images Docker personnalisées avec l’interface CLI Python héritée
Cette documentation est obsolète et pourrait ne pas être mise à jour.
La CLI air basée sur Python, installée avec le package databricks-air, est maintenant obsolète et n'est plus activement maintenue.
Utilisez la CLI Databricks pour les nouvelles charges de travail. Consultez Utiliser la CLI Databricks avec AI Runtime.
Cette fonctionnalité est en version Bêta. Pour l’utiliser, un administrateur de workspace doit activer la prévisualisation des Fonctionnalités Bêta de AI Runtime depuis la page de prévisualisation du workspace.
Docker Container Services (DCS) vous permet d’apporter votre propre image de conteneur Docker aux charges de travail air. Utilisez une image personnalisée lorsque vous avez besoin de :
- Versions de bibliothèques système spécifiques.
- Dépendances complexes qui ne s'intègrent pas parfaitement dans
environment.dependencies. - Un environnement exact pour reproduire des résultats de recherche.
- Images standards créées par l’équipe de plateforme ou de sécurité de votre organisation.
Prérequis
- Installer l’CLI d’AI Runtime.
- Un administrateur de Workspace a activé l'aperçu des fonctionnalités bêta du Runtime de l'IA . Pour des instructions, consultez Gérer les aperçus au niveau du workspace.
- Pour les images privées, un compte Docker Hub avec accès à votre image.
Enregistrer une image
Avant d'exécuter un workload avec une image personnalisée, enregistrez-le avec air register image. L'enregistrement extrait et met en cache l'image sur la plateforme Databricks. Chaque utilisateur doit enregistrer une image une fois par tag d'image. Ne réenregistrez que lorsque vous transférez un nouveau tag ou faites pivoter les identifiants. L'enregistrement prend 2 à 6 minutes et bloque jusqu'à ce que l'image soit prête.
Images publiques
Enregistrez 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 en forme courte fonctionne aussi. Par exemple : library/ubuntu:latest.
Images Docker privées du hub
Pour enregistrer une image Docker Hub privée, commencez par générer un jeton d'accès personnel. Dans les paramètres de votre compte Docker Hub, cliquez sur Personal access tokens → Generate new token . Un accès en lecture seule suffit.
Choisissez l'une des méthodes d'authentification suivantes :
Utilisation de docker login (recommandé pour une utilisation interactive)
Connexion à Docker Hub dans le terminal. Vous serez invité à entrer votre nom d'utilisateur Docker Hub et votre jeton d'accès personnel :
docker login
Cela stocke vos identifiants dans ~/.docker/config.json. Enregistrez ensuite l’image — air lit automatiquement les identifiants :
air register image myorg/myrepo:mytag -p my-databricks-profile
Utilisation de l’authentification interactive
Authentifiez-vous et stockez les identifiants dans un Secret Scope 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 informations d'identification sont stockées dans le Secret Scope de votre workspace pour les inscriptions futures.
Utilisation d’un secret Databricks préstocké (recommandé pour CI/scripts)
Stockez les informations d'identification dans un secret Databricks et référencez-le 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 votre YAML de charge de travail sous 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 importez votre propre image Docker, environment.dependencies et environment.version ne sont pas pris en charge. La spécification de environment.docker_image.url avec l'un ou l'autre champ Trigger une erreur. Si vous avez des dépendances supplémentaires, installez les packages dans le Dockerfile à la place.
Soumettre la charge de travail :
air run --file workload.yaml -p my-databricks-profile
Variables d'environnement injectées dans votre conteneur
L'environnement Runtime de l'IA injecte les variables d'environnement suivantes dans chaque conteneur lors 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 du nœud actuel (indexé sur 0). Également injecté sous la formeNODE_RANK.LOCAL_ADDR— IP du nœud local (multi-nœud uniquement).MASTER_ADDR— adresse de coordination de rang 0 (multi-nœud uniquement).MASTER_PORT— port de coordination du 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 à nœuds multiples avec RDMA
Pour les jobs H100 multinœuds nécessitant toute la bande passante réseau sur les instances AWS p5, basez votre image sur l’une des images de base Databricks avec NCCL et EFA préconfigurés :
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éez votre propre image
Lors de la création de votre propre image, Databricks vous recommande d'utiliser la compétence databricks-ai-runtime avec un agent de code ou de partir d'une image de base Databricks.
Utiliser un agent de codage
Installez la compétence Claude Code databricks-ai-runtime pour obtenir des instructions pas à pas sur le Dockerfile, y compris sur la création à partir de zéro, la compatibilité CUDA/NCCL/EFA, les problèmes courants et une liste de contrôle de pré-création. Cette compétence nécessite Databricks CLI version 1.0.0 ou plus récente.
databricks aitools install --skills databricks-ai-runtime
Images de base Databricks
Databricks publie des images de base sur Docker Hub à databricksruntime/air avec CUDA, NCCL et la mise en réseau spécifique au cloud (AWS EFA ou Azure InfiniBand) préconfigurée.
Tag | Variante | CUDA | Utiliser lors de |
|---|---|---|---|
| Environnement d'exécution | 12 | Installation de wheels prédéfinis uniquement |
| Dev | 12 | Compilation des extensions CUDA (requiert |
| Environnement d'exécution | 13 | Installation des roues pré-construites seulement, sur CUDA 13 |
| Dev | 13 | Compilation d’extensions CUDA sur CUDA 13 (nécessite |
Exemple de Dockerfile ajoutant PyTorch à une image de base Databricks. Les images de base fournissent Python à /opt/venv, géré par uv. uv pip install cible cet environnement default ; pour utiliser un autre environnement, créez et activez 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
Créer, 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
Prérequis
- Les images doivent être hébergées sur Docker Hub. Amazon ECR, Google GCR et GitHub GHCR ne sont pas pris en charge.
- La taille de l'image doit être inférieure à 20 Go.
WORKDIRn’est pas respecté lors de l’exécution. Utiliser des chemins absolus pour les fichiers intégrés dans l’image. Par exemple, utilisezpython /app/train.py, et nonpython train.py.- Vous ne pouvez pas utiliser
environment.dependenciesouenvironment.versionavecenvironment.docker_image.url. Si vous avez besoin de packages supplémentaires au-delà de ceux qui se trouvent dans l'image, vous devez les ajouter au Dockerfile.
Dépannage
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 apparaît lors de l'importation de bibliothèques qui ouvrent des connexions réseau, telles que huggingface_hub, et les empêche de se charger.
Cela se produit car les charges de travail air sont exécutées sur des hôtes activés pour FIPS. Lorsque les bibliothèques cryptographiques de l'image ne sont pas compatibles FIPS, OpenSSL ne s'initialise pas en mode FIPS ; la création d'un contexte SSL échoue donc.
Solution recommandée :
Les charges de travail d'entreprise, gouvernementales, de santé et financières 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, construisez votre image avec des bibliothèques cryptographiques conformes à FIPS.
Si votre charge de travail ne nécessite pas la conformité FIPS, vous pouvez désactiver le mode FIPS en définissant la variable d’environnement OPENSSL_FORCE_FIPS_MODE sur 0. Cela peut compromettre 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'
Sinon, définissez la variable dans votre Dockerfile pour qu’elle s’applique à toutes les charges de travail qui utilisent l’image :
ENV OPENSSL_FORCE_FIPS_MODE=0
Relancez la charge de travail et confirmez que l'erreur SSL n'apparaît plus lorsque les dépendances se chargent.