Usar a CLI do Databricks com o AI Runtime
A CLI databricks air executa cargas de trabalho de GPU de nó único e multinó no AI Runtime, a plataforma de compute de GPU serverless sob demanda. Defina o compute, o ambiente e o comando de uma carga de trabalho em YAML e, em seguida, envie-o com databricks air run.
O AI Runtime lida com o provisionamento de GPU e a configuração do ambiente e fornece status de execução, logs, métricas de sistema e acompanhamento de MLflow. O fluxo de trabalho YAML e CLI funciona naturalmente com agentes de codificação, que podem definir, enviar e monitorar cargas de trabalho.
Use a CLI para:
- Desenvolva e faça iterações em aplicativos Python a partir de seu ambiente local.
- Defina cargas de trabalho repetíveis em arquivos YAML que você pode controlar pela origem.
- Envie e gerencie cargas de trabalho de um terminal ou fluxo de trabalho de desenvolvimento automatizado.
As cargas de trabalho típicas incluem ajuste fino e pós-treinamento de LLM, treinamento distribuído, inferência em lote, aplicativos Ray e pesquisa de hiperparâmetros.
Para requisitos de workspace, consulte Requisitos. Para enviar uma carga de trabalho, siga o início rápido.
Os comandos da CLI do Databricks para AI Runtime atendem aos mesmos padrões de compliance que as cargas de trabalho do AI Runtime. Para ver os padrões compatíveis e as exceções, consulte perfil de segurança de compliance.
Os comandos databricks air e a configuração da carga de trabalho diferem da CLI air baseada em Python legada no pacote databricks-air. Veja a migração da CLI Python.
Explore exemplos executáveis
O Livro de Receitas do AI Runtime contém cargas de trabalho da CLI do Databricks executáveis para treinamento de modelos, ajuste fino, inferência em lote, Ray e busca de hiperparâmetros. Cada receita inclui um arquivo YAML de carga de trabalho, código-fonte e instruções para executá-lo.
Como uma carga de trabalho é execução
Você fornece um arquivo YAML de carga de trabalho, código de aplicativo quando necessário e o comando que começa o aplicativo. Quando você envia uma carga de trabalho:
- A definição da carga de trabalho é validada em relação ao esquema e às restrições de configuração suportadas.
- Se
code_sourceestiver configurado, o código selecionado será empacotado como um Snapshot e upload. - O compute de GPU e o ambiente solicitados são preparados em cada nó.
- O comando fornecido no YAML de carga de trabalho é execução em cada nó.
O envio retorna um ID de execução do job que identifica a carga de trabalho. Use-o para verificar o status, inspecionar logs e configuração ou cancelar a carga de trabalho. Você também pode view a página de execução de jobs e a experiência do MLflow para obter detalhes de execução, métricas do sistema, logs e artefatos.
Este fluxo de trabalho fornece provisionamento gerenciado de GPU, configuração de ambiente reproduzível e observabilidade integrada, sem que você precise configurar ou manter a infraestrutura de GPU.
Configuração de Workload
Um arquivo YAML de workload descreve os seguintes componentes:
- Experimento : O experimento e a execução do MLflow que monitoram a carga de trabalho.
- Ambiente : o ambiente gerenciado, as dependências ou a Docker Image personalizada a ser usada.
- Compute : o tipo de acelerador e o número de aceleradores a provisionar.
- Fonte do código : Um snapshot opcional do código do aplicativo para disponibilizar à workload.
- Comando : O comando shell que começa sua aplicação.
- Configurações de runtime : opções como tentativas, tempos limite, variáveis de ambiente, segredos e permissões.
Para campos de configuração e exemplos, consulte a referência YAML da Workload.
Usar uma Docker Image personalizada
Em vez de um ambiente gerenciado, uma carga de trabalho pode entrar em execução em sua própria Docker Image. Use uma imagem personalizada quando sua carga de trabalho precisar de bibliotecas de sistema, extensões CUDA ou outras dependências que você não possa instalar com environment.dependencies. Imagens Docker personalizadas estão em Pré-visualização Pública. Para usá-las, um admin de workspace deve habilitar a visualização Databricks Artifact Registry na página de Pré-visualizações do workspace.
Você cria a imagem para linux/amd64, envia-a para o Artifact Registry em seu workspace e define environment.unity_catalog_image no YAML da carga de trabalho para o nome da imagem no Unity Catalog. Para os passos, imagens de base do Databricks, autenticação do Docker e solução de problemas, consulte Usar imagens Docker personalizadas com AI Runtime.
Fazer upload de código de aplicativo
Use code_source para fazer upload de arquivos de aplicativo com uma carga de trabalho. O AI Runtime disponibiliza o diretório upload em cada nó e define $CODE_SOURCE_PATH para o local dele. Por exemplo, o seguinte comando execução train.py do diretório upload:
command: python "$CODE_SOURCE_PATH/train.py"
Você pode fazer upload da árvore de trabalho atual ou selecionar uma branch ou commit do Git. Para ver um exemplo completo, consulte o início rápido.
Desenvolver e gerenciar workloads
O desenvolvimento normalmente segue este processo:
- Desenvolva o código do aplicativo e o YAML da carga de trabalho localmente.
- Valide o YAML localmente com
databricks air run --file <file> --dry-run. - Envie a carga de trabalho com
databricks air run --file <file>. Adicione--watchaos logs de transmissão até que a execução seja concluída. - Use
databricks air get,databricks air listedatabricks air logspara inspecionar cargas de trabalho e logs. - Opcionalmente, pare uma carga de trabalho em execução com
databricks air cancel.
Para ver todos os comandos e sinalizadores, consulte o air grupo de comandos.
Para execuções agendadas, fluxos de trabalho multitarefa ou promoção entre ambientes, você pode usar databricks air convert-to-dabs como ponto de partida para um pacote. Veja programar cargas de trabalho de GPU e compor tarefas.
Acompanhar cargas de trabalho com MLflow
Cada carga de trabalho enviada é representada por uma execução de job do Databricks e rastreada por meio de um experimento de MLflow:
- Execução de job do Databricks : mostra o status da carga de trabalho, tentativas de execução e saída na página de execução do Job.
- Experiment MLflow : contém as execuções do MLflow com métricas de sistema capturadas automaticamente, configuração de carga de trabalho e logs. Sua aplicação também pode usar as APIs do MLflow para registrar parâmetros, métricas e artefatos personalizados.
Use o ID de execução do job com comandos como databricks air get, databricks air logs e databricks air cancel. Consulte Acompanhamento de experimentos e observabilidade.
execução workloads de nó único e distribuídas
O AI Runtime faz a execução do comando configurado uma vez em cada nó com provisionamento. Para uma carga de trabalho distribuída, ele fornece variáveis de coordenação como NUM_NODES, NODE_RANK, LOCAL_WORLD_SIZE, MASTER_ADDR e MASTER_PORT.
Esse modelo de execução é independente de framework. O seu comando deve começar e configurar o framework distribuído, por exemplo, invocando torchrun, um script de bootstrap do Ray ou outro lançador de framework. Para cargas de trabalho completas, consulte o AI Runtime Cookbook.
Usar um agente de AI
A databricks-ai-runtime habilidade do agente fornece instruções que ajudam agentes de AI, como Claude Code, Cursor e Codex, a trabalhar com o AI Runtime por meio da CLI da Databricks. Use-a para criar YAML de carga de trabalho, enviar jobs de treinamento de GPU, verificar o status de execução, transmissão logs e cancelar execuções. Também inclui orientações para imagens personalizadas do Docker.
Após instalar a CLI do Databricks e configurar a autenticação, execute o seguinte comando:
databricks aitools install --skills-only --skills databricks-ai-runtime
Siga os prompts para escolher seu agente de AI e escopo de instalação. Para opções de instalação, consulte o grupo de comandos aitools. Para o que a habilidade cobre, consulte Usar habilidades de agente com AI Runtime.