Usar imagens personalizadas do Docker com a CLI do Python herdada
Esta documentação foi retirada e pode não ser atualizada.
A CLI air 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 ativar a prévia dos recursos Beta do Runtime de AI na página de prévias do Workspace.
O Docker Container Services (DCS) permite que você traga sua própria imagem de container do Docker para cargas de trabalho air. Use uma imagem personalizada quando você precisar:
- 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 os resultados da pesquisa.
- Imagens padrão criadas pela equipe de plataforma ou segurança da sua organização.
Pré-requisitos
- Instale o CLI do AI Runtime.
- Um administrador de Workspace habilitou a prévia de Recursos Beta do AI Runtime . Para obter instruções, consulte Gerenciar prévias do nível de Workspace.
- Para imagens privadas, uma account do Docker Hub com acesso à sua imagem.
Registro uma imagem
Antes de executar um workload com uma imagem personalizada, registro-a com air register image. O registro puxa e armazena em cache a imagem na plataforma Databricks. Cada usuário deve fazer um registro de uma imagem uma vez por tag de imagem. Faça o registro novamente apenas quando você enviar uma nova tag ou girar credenciais. O registro leva de 2 a 6 minutos e bloqueia até que a imagem esteja pronta.
Imagens públicas
Registre imagens públicas fornecendo a URL da Docker Image e seu perfil Databricks:
air register image docker.io/nvidia/cuda:12.9.0-devel-ubuntu24.04 -p my-databricks-profile
A referência da imagem de forma curta também funciona. Por exemplo, library/ubuntu:latest.
Imagens privadas do Docker Hub
Para fazer o registro de uma imagem privada do Docker Hub, gere um access token pessoal primeiro. Nas configurações da sua account do Docker Hub, clique em access tokens pessoais → Gerar novo token . O acesso somente para leitura é suficiente.
Escolha um dos seguintes métodos de autenticação:
Usando login docker (recomendado para uso interativo)
Log in no Docker Hub no terminal. Você será solicitado a informar seu nome de usuário do Docker Hub e access token pessoal:
docker login
Isso armazena suas credenciais em ~/.docker/config.json. Depois, registro a imagem — air lê as credenciais automaticamente:
air register image myorg/myrepo:mytag -p my-databricks-profile
Uso da autenticação interativa
Autentique e armazene credenciais em um Secret Scope do Databricks em um único passo:
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile
Você será solicitado a fornecer seu nome de usuário do Docker Hub e seu access token pessoal. As credenciais são armazenadas no Secret Scope do seu workspace para registros futuros.
Usando um segredo do Databricks pré-armazenado (recomendado para CI/scripts)
Armazene as credenciais em um segredo do Databricks e referencie-as diretamente:
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 na YAML da sua carga de trabalho 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
Ao trazer sua própria Docker Image, environment.dependencies e environment.version não são suportados. Especificar environment.docker_image.url com qualquer campo Trigger um erro. Se você tiver dependências adicionais, instale os pacotes no Dockerfile.
Enviar a carga de trabalho:
air run --file workload.yaml -p my-databricks-profile
Variáveis de ambiente injetadas no seu container
O AI Runtime injeta as seguintes variáveis de ambiente em todos os containers no runtime:
NUM_NODES— número total de nós.LOCAL_WORLD_SIZE— GPUs por nó.WORLD_SIZE— número total de processos.POD_RANK— rank do nó atual (indexado em 0). Também injetado comoNODE_RANK.LOCAL_ADDR— IP do nó local (somente multinó).MASTER_ADDR— endereço de coordenação de classificação 0 (apenas 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 multinó que precisam de largura de banda de rede total 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
Crie sua própria imagem
Ao construir sua própria imagem, a Databricks recomenda usar a habilidade databricks-ai-runtime com um agente de programação ou começar a partir de uma imagem base da Databricks.
Usar um agente de programação
Instale a habilidade Claude Code databricks-ai-runtime para orientações passo a passo do Dockerfile, incluindo build do zero, compatibilidade CUDA/NCCL/EFA, problemas comuns e uma lista de verificação pré-build. Esta habilidade requer a versão 1.0.0 ou mais recente da CLI do Databricks.
databricks aitools install --skills databricks-ai-runtime
Imagens base do Databricks
A Databricks publica imagens 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 Python wheels pré-construídas |
| Desenv | 12 | Compilando extensões CUDA (exige |
| Runtime | 13 | Instalando apenas rodas pré-construídas, no CUDA 13 |
| Desenv | 13 | Compilação de extensões CUDA no CUDA 13 (requer |
Exemplo de Dockerfile adicionando PyTorch a uma imagem base do Databricks. As imagens de base fornecem Python em /opt/venv, gerenciado por uv. uv pip install aponta para esse ambiente por default; para usar um ambiente diferente, crie e ative um venv antes de executar 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
Construir, enviar e 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
- As imagens devem ser hospedadas no Docker Hub. Amazon ECR, Google GCR e GitHub GHCR não são suportados.
- O tamanho da imagem deve ser menor que 20 GB.
WORKDIRnão é respeitado em Runtime. Use caminhos absolutos para arquivos integrados à 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 do que está na imagem, deve adicioná-los ao Dockerfile.
Solução de problemas
ssl.SSLError: [CRYPTO] erro desconhecido (_ssl.c) ao carregar dependências
Uma imagem personalizada pode falhar no runtime com um erro 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 estão em execução em hosts com FIPS habilitado. 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.
Solução recomendada:
Workloads corporativas, governamentais, de saúde e financeiras muitas vezes dependem da compliance com FIPS 140-2 ou 140-3 para auditorias FedRAMP, CMMC ou HIPAA. Se o seu workload precisar permanecer compatível com FIPS, crie sua imagem com bibliotecas criptográficas compatíveis com FIPS.
Se sua carga de trabalho não exigir compliance com FIPS, você pode desabilitar o modo FIPS definindo a variável de ambiente OPENSSL_FORCE_FIPS_MODE como 0. Fazer isso pode interromper silenciosamente os requisitos de compliance.
Para desativar o modo FIPS, defina-o em YAML de carga de trabalho em env_variables:
env_variables:
OPENSSL_FORCE_FIPS_MODE: '0'
Como alternativa, defina a variável em 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 que o erro de SSL não aparece mais quando as dependências são carregadas.