Usar imagens personalizadas do Docker com a CLI antiga do Python
Esta documentação foi descontinuada e pode não ser atualizada.
A air CLI baseada em Python, instalada com o pacote databricks-air, agora está obsoleta e não é mais mantida ativamente.
Use a CLI do Databricks para novas cargas de trabalho. Consulte Usar a CLI do Databricks com o AI Runtime.
Esse recurso está em Beta. Para usá-lo, um administrador do workspace deve habilitar a visualização dos AI Runtime Beta Features na página Pré-visualizações do workspace.
Docker Container Services (DCS) lets you bring your own Docker container image to air workloads. Use a custom image when you need:
- Versões específicas da biblioteca do sistema.
- Dependências complexas que não se encaixam perfeitamente em
environment.dependencies. - Um ambiente exato para reproduzir resultados de pesquisa.
- Standard images built by your organization's platform or security team.
Pré-requisitos
- Install the AI Runtime CLI.
- Um administrador do workspace ativou a pré-visualização do recurso AI Runtime Beta Features . Para obter instruções, consulte Gerenciar prévias no nível do workspace.
- Para imagens privadas, uma account do Docker Hub com acesso à sua imagem.
Registrar uma imagem
Before running a workload with a custom image, register it with air register image. Registration pulls and caches the image in the Databricks platform. Each user must register an image once per image tag. Re-register only when you push a new tag or rotate credentials. Registration takes 2–6 minutes and blocks until the image is ready.
Imagens públicas
Registre imagens públicas fornecendo a URL da imagem do Docker e o seu perfil do Databricks:
air register image docker.io/nvidia/cuda:12.9.0-devel-ubuntu24.04 -p my-databricks-profile
A forma abreviada da referência de imagem também funciona. Por exemplo, library/ubuntu:latest.
Imagens privadas do Docker Hub
To register a private Docker Hub image, generate a personal access token first. In your Docker Hub account settings, click Personal access tokens → Generate new token . Read-only access is sufficient.
Escolha um dos seguintes métodos de autenticação:
Usando o docker login (recomendado para uso interativo)
Log in no Docker Hub pelo terminal. Você será solicitado a fornecer seu nome de usuário do Docker Hub e o access token pessoal:
docker login
This stores your credentials in ~/.docker/config.json. Then register the image — air reads the credentials automatically:
air register image myorg/myrepo:mytag -p my-databricks-profile
Usando autenticação interativa
Autentique e armazene credenciais em um Secret Scope do Databricks em uma única etapa:
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile
Você receberá uma solicitação para inserir seu nome de usuário do Docker Hub e o access token pessoal. As credenciais são armazenadas no secret scope do workspace para registros futuros.
Usando um segredo do Databricks pré-armazenado (recomendado para CI/scripts)
Store credentials in a Databricks secret and reference it directly:
air register image myorg/myrepo:mytag --scope my-secret-scope --key my-docker-key -p my-databricks-profile
Usar uma Docker Image em uma carga de trabalho
Especifique a Docker Image em sua carga de trabalho YAML em 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
When bringing your own Docker image, environment.dependencies and environment.version are not supported. Specifying environment.docker_image.url with either field triggers an error. If you have additional dependencies, install the pacotes in the Dockerfile instead.
Envie a carga de trabalho:
air run --file workload.yaml -p my-databricks-profile
Variáveis de ambiente injetadas no seu contêiner
O AI Runtime injeta as seguintes variáveis de ambiente em cada container em runtime:
NUM_NODES— número total de nós.LOCAL_WORLD_SIZE— GPUs por nó.WORLD_SIZE— número total de processos.POD_RANK— classificação atual do nó (com base 0). Também injetado comoNODE_RANK.LOCAL_ADDR— IP do nó local (apenas multinó).MASTER_ADDR— endereço de coordenação de rank 0 (somente multinó).MASTER_PORT— porta de coordenação rank-0 (somente multinó).
Exemplos
A10 de nó único
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 multinó com RDMA
Para jobs H100 de vários nós que precisam de largura de banda de rede completa em instâncias AWS p5, baseie sua imagem em uma das imagens base do Databricks com NCCL e EFA pré-configurados:
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
Build your own image
Ao construir sua própria imagem, o Databricks recomenda o uso de databricks-ai-runtime skill com um agente de codificação ou começar a partir de uma imagem base do Databricks.
Use um agente de programação
Instale a skill do Claude Code para o databricks-ai-runtime para obter orientações passo a passo sobre o Dockerfile, incluindo a criação do zero, compatibilidade com CUDA/NCCL/EFA, problemas comuns e uma lista de verificação de pré-compilação. Esta skill requer a versão 1.0.0 ou mais recente da CLI do Databricks.
databricks aitools install --skills databricks-ai-runtime --experimental
Imagens base do Databricks
A Databricks publica imagens de base no Docker Hub em databricksruntime/air com CUDA, NCCL e rede específica da cloud (AWS EFA ou Azure InfiniBand) pré-configurados.
Etiqueta | Variante | CUDA | Usar quando |
|---|---|---|---|
| Runtime | 12 | Instalando apenas wheels pré-construídas |
| Devel | 12 | Compilando extensões CUDA (requer |
| Runtime | 13 | Instalando apenas wheels pré-construídas, no CUDA 13 |
| Devel | 13 | Compilando extensões CUDA no CUDA 13 (requer |
Example Dockerfile adding PyTorch to a Databricks base image. The base images provide Python at /opt/venv, managed by uv. uv pip install targets that environment by default; to use a different environment, create and activate a venv before running 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
Build, push, and registro:
docker build -t myorg/myrepo:mytag .
docker push myorg/myrepo:mytag
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile
Requisitos
- Images must be hosted on Docker Hub. Amazon ECR, Google GCR, and GitHub GHCR are not supported.
- O tamanho da imagem deve ser inferior a 20 GB.
WORKDIRnão é respeitado em Runtime. Use caminhos absolutos para arquivos embutidos na imagem. Por exemplo, usepython /app/train.py, nãopython train.py.- Você não pode usar
environment.dependenciesouenvironment.versioncomenvironment.docker_image.url. Se você precisar de pacotes extras além dos que estão na imagem, deverá adicioná-los ao Dockerfile.
Solução de problemas
ssl.SSLError: [CRYPTO] unknown error (_ssl.c) ao carregar dependências
Uma imagem personalizada pode falhar no runtime com um erro do OpenSSL quando uma biblioteca tenta criar um contexto SSL, por exemplo:
ssl.SSLError: [CRYPTO] unknown error (_ssl.c:3076)
O erro aparece ao importar bibliotecas que abrem conexões de rede, como huggingface_hub, e impede que elas sejam carregadas.
Isso ocorre porque as cargas de trabalho de air são executadas em hosts habilitados para FIPS. Quando as bibliotecas criptográficas da imagem não são compatíveis com FIPS, o OpenSSL falha ao inicializar no modo FIPS, fazendo com que a criação de um contexto SSL falhe.
Recommended solution:
Workloads corporativas, governamentais, de saúde e financeiras frequentemente dependem de compliance com FIPS 140-2 ou 140-3 para auditorias FedRAMP, CMMC ou HIPAA. Se a sua workload precisar permanecer em conformidade com FIPS, crie sua imagem com bibliotecas criptográficas em conformidade com FIPS.
Se a sua carga de trabalho não exigir compliance com FIPS, você poderá desativar o modo FIPS definindo a variável de ambiente OPENSSL_FORCE_FIPS_MODE como 0. Fazer isso pode violar silenciosamente os requisitos de compliance.
Para desativar o modo FIPS, configure-o no YAML da sua carga de trabalho em env_variables:
env_variables:
OPENSSL_FORCE_FIPS_MODE: '0'
Como alternativa, defina a variável no seu Dockerfile para que ela seja aplicada a todas as cargas de trabalho que usam a imagem:
ENV OPENSSL_FORCE_FIPS_MODE=0
Reenvie a carga de trabalho e confirme se o erro de SSL não aparece mais quando as dependências forem carregadas.