Utilisation d'images Docker personnalisées avec l'ancienne CLI Python
Cette documentation a été retirée et ne sera peut-être pas mise à jour.
La CLI air basée sur Python, installée avec le package databricks-air, est désormais 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 du workspace doit activer l'aperçu AI Runtime Beta Features depuis la page des aperçus du workspace.
Docker Container Services (DCS) vous permet d'importer votre propre image de conteneur Docker pour les charges de travail air. Utilisez une image personnalisée lorsque vous avez besoin de :
- Versions de bibliothèque système spécifiques.
- Dépendances complexes qui ne s'intègrent pas clairement dans
environment.dependencies. - Un environnement exact pour reproduire les résultats de recherche.
- Images standard créées par l'équipe de plateforme ou de sécurité de votre organisation.
Prérequis
- Installez l'AI Runtime CLI.
- Un administrateur du Workspace a activé la version préliminaire AI Runtime Beta Features . Pour obtenir des instructions, consultez Gérer les aperçus au niveau du workspace.
- Pour les images privées, un compte Docker Hub disposant d'un accès à votre image.
Enregistrer une image
Avant d'exécuter une charge de travail avec une image personnalisée, enregistrez-la auprès de air register image. L'enregistrement extrait et met en cache l'image dans la plateforme Databricks. Chaque utilisateur doit enregistrer une image une fois par tag d'image. Réenregistrez l'élément uniquement lorsque vous envoyez un nouveau tag ou que vous changez d'identifiants. L'enregistrement prend 2 à 6 minutes et se 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 sous forme abrégée fonctionne également. Par exemple, library/ubuntu:latest.
Images Private Docker Hub
Pour enregistrer une image Docker Hub privée, générez d'abord 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)
Connectez-vous à Docker Hub depuis le terminal. Votre nom d’utilisateur Docker Hub et votre jeton d’accès personnel vous seront demandés :
docker login
Ceci stocke vos identifiants dans ~/.docker/config.json. Ensuite, enregistrez l'image — air lit les identifiants automatiquement :
air register image myorg/myrepo:mytag -p my-databricks-profile
Utilisation d’une authentification interactive
Authentifiez-vous et stockez les informations d'identification dans un Secret Scope Databricks en une seule étape :
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile
Le nom d'utilisateur et le jeton d'accès personnel de votre Docker Hub vous seront demandés. Les identifiants sont stockés dans votre Secret Scope du Workspace pour les enregistrements ultérieurs.
Utilisation d'un secret Databricks pré-stocké (recommandé pour la CI/les scripts)
Stockez les informations d'identification dans un secret Databricks et faites-y référence 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 workload 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 utilisez votre propre image Docker, environment.dependencies et environment.version ne sont pas pris en charge. Spécifier environment.docker_image.url avec l'un ou l'autre champ Trigger une erreur. Si vous avez des dépendances supplémentaires, installez plutôt les packages dans le Dockerfile.
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 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 de nœud actuel (indexé à partir de 0). Également injecté en tant queNODE_RANK.LOCAL_ADDR— IP du nœud local (multinœud uniquement).MASTER_ADDR— adresse de coordination de rang 0 (multinœud uniquement).MASTER_PORT— Port de coordination rank-0 (uniquement pour les configurations multi-nœuds).
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 qui nécessitent 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 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 Claude Code databricks-ai-runtime pour obtenir des conseils Dockerfile détaillés étape par étape, notamment sur la création à partir de zéro, la compatibilité CUDA/NCCL/EFA, les problèmes courants et une liste de contrôle avant génération. Cette compétence nécessite la version 1.0.0 ou ultérieure de la CLI Databricks.
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 la mise en réseau spécifique au cloud (AWS EFA ou Azure InfiniBand) préconfigurés.
Tag | Variante | CUDA | À utiliser lorsque |
|---|---|---|---|
| Environnement d'exécution | 12 | Installation de wheels précompilés uniquement |
| Dévelop. | 12 | Compilation des extensions CUDA (nécessite |
| Environnement d'exécution | 13 | Installation de wheels prédéfinis uniquement, sur CUDA 13 |
| Dévelop. | 13 | Compilation d'extensions CUDA sur CUDA 13 (nécessite |
Exemple de fichier Dockerfile ajoutant PyTorch à une image de base Databricks. Les images de base fournissent Python à l'emplacement /opt/venv, géré par uv. uv pip install cible cet environnement by 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, transférer 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 pris en compte à l’exécution. Utilisez des chemins absolus pour les fichiers intégrés à l’image. Par exemple, utilisezpython /app/train.pyet 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 présents dans l'image, vous devez les ajouter au Dockerfile.
Dépannage
ssl.SSLError : [CRYPTO] unknown error (_ssl.c) lors du chargement des dépendances
Une image personnalisée peut échouer à 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 parce que les charges de travail air sont exécutées sur des hôtes compatibles FIPS. Lorsque les bibliothèques cryptographiques de l'image ne sont pas compatibles avec la norme 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 des entreprises, des gouvernements, du secteur de la santé et de la 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, construisez votre image avec des bibliothèques cryptographiques 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 d’environnement OPENSSL_FORCE_FIPS_MODE sur 0. Cela peut enfreindre silencieusement les exigences de conformité.
Pour désactiver le mode FIPS, configurez-le dans le YAML de votre charge de travail sous env_variables:
env_variables:
OPENSSL_FORCE_FIPS_MODE: '0'
Vous pouvez également définir la variable dans votre Dockerfile pour qu’elle s’applique à chaque charge de travail qui utilise l’image :
ENV OPENSSL_FORCE_FIPS_MODE=0
Soumettez à nouveau la charge de travail et vérifiez que l'erreur SSL n'apparaît plus lors du chargement des dépendances.