Referência de YAML de Workload

Esta página descreve os campos YAML de carga de trabalho aceitos por databricks air run. Para a sintaxe e as flags dos comandos, consulte databricks air run. Para enviar uma carga de trabalho, consulte o início rápido do AI Runtime.

Cada carga de trabalho requer experiment_name, compute e command.

Exemplo

O exemplo a seguir mostra uma configuração de carga de trabalho de amostra:

YAML
experiment_name: my-training
compute:
  accelerator_type: GPU_1xA10
  num_accelerators: 1
environment:
  version: 6
  dependencies:
    - torch
code_source:
  root_path: .
command: python $CODE_SOURCE_PATH/train.py

experiment_name

Tipo: String

Obrigatório. A key experiment_name é o nome da experiment MLflow.

Se um experimento com esse nome não existir, o AI Runtime o criará. Caso contrário, o AI Runtime adicionará a nova execução ao experimento existente.

compute

Tipo: Mapa

Obrigatório. O objeto compute define a configuração do acelerador.

Chave	Tipo	Descrição
`accelerator_type`	string	Obrigatório. Um tipo de acelerador aceito pela CLI e disponível no workspace. A correspondência diferencia maiúsculas de minúsculas.
`num_accelerators`	inteiro	Obrigatório. Uma contagem positiva de aceleradores suportada para o tipo de acelerador selecionado.
`pool_id`	string	O ID da capacidade de GPU provisionada.
`priority_class`	string	A prioridade de agendamento para cargas de trabalho usando capacidade de GPU provisionada. Os valores aceitos são `BEST_EFFORT`, `NORMAL` e `CRITICAL`. Requer `pool_id`.

Chave	Tipo	Descrição
`accelerator_type`	string	Obrigatório. Um tipo de acelerador aceito pela CLI e disponível no workspace. A correspondência diferencia maiúsculas de minúsculas.
`num_accelerators`	inteiro	Obrigatório. Uma contagem positiva de aceleradores suportada para o tipo de acelerador selecionado.
`pool_id`	string	O ID da capacidade de GPU provisionada.
`priority_class`	string	A prioridade de agendamento para cargas de trabalho usando capacidade de GPU provisionada. Os valores aceitos são `BEST_EFFORT`, `NORMAL` e `CRITICAL`. Requer `pool_id`.

Os tipos e contagens de aceleradores dependem do workspace, da cloud e da região. Para seleção e disponibilidade de hardware, consulte Opções de hardware.

comando

Tipo: String

Obrigatório. A key command contém um comando shell ou script não vazio. Os caminhos no comando referem-se a caminhos de arquivo remotos no container de workload. Quando code_source é definido, $CODE_SOURCE_PATH contém o caminho absoluto para o código extraído.

ambiente

Tipo: Mapa

O objeto environment seleciona um ambiente gerenciado com dependências opcionais ou uma imagem personalizada do Unity Catalog.

Chave	Tipo	Descrição
`version`	string ou número inteiro	Uma versão de ambiente numérica, como `6`, ou um identificador de ambiente Databricks AI, como `databricks_ai_v6`. Um identificador `databricks_ai_v` requer a versão 5 ou acima. Se omitido, a CLI usará o default atual do AI Runtime.
`dependencies`	lista de strings	Especificações de pacote passadas para o ambiente serverless. O default é não ter dependências adicionais.
`unity_catalog_image`	string	Uma imagem personalizada no formato `<catalog>.<schema>.<image>:<tag>`. Mutuamente exclusivo com `version` e `dependencies`. Para obter instruções de configuração, consulte Usar imagens Docker personalizadas com o AI Runtime.

Chave	Tipo	Descrição
`version`	string ou número inteiro	Uma versão de ambiente numérica, como `6`, ou um identificador de ambiente Databricks AI, como `databricks_ai_v6`. Um identificador `databricks_ai_v` requer a versão 5 ou acima. Se omitido, a CLI usará o default atual do AI Runtime.
`dependencies`	lista de strings	Especificações de pacote passadas para o ambiente serverless. O default é não ter dependências adicionais.
`unity_catalog_image`	string	Uma imagem personalizada no formato `<catalog>.<schema>.<image>:<tag>`. Mutuamente exclusivo com `version` e `dependencies`. Para obter instruções de configuração, consulte Usar imagens Docker personalizadas com o AI Runtime.

Para obter orientação sobre como selecionar e expandir um ambiente, consulte Configurar seu ambiente.

Exemplo de ambiente gerenciado

YAML
environment:
  version: 6
  dependencies:
    - torch

Para usar uma imagem personalizada em vez de um ambiente gerenciado, especifique apenas unity_catalog_image:

Exemplo de imagem personalizada

YAML
environment:
  unity_catalog_image: main.ml.training:v1

code_source

Tipo: Mapa

O objeto code_source empacota o código local para a carga de trabalho.

Chave	Tipo	Descrição
`root_path`	string	Necessário quando `code_source` está definido. O diretório local para empacotar. O diretório deve existir quando a CLI preparar a execução.
`remote_volume`	string	Uma localização de volume do Unity Catalog para o arquivo upload. Deve começar com `/Volumes/`. default para um local de Workspace.
`include_paths`	lista de strings	Caminhos para incluir relativos a `root_path`. As entradas devem ser não vazias e relativas, e não podem conter `..`. Omita a key para incluir todos os arquivos selecionados. Uma lista vazia não é válida.
`git`	objeto	pin o Snapshot da origem do código a uma Branch ou commit local do Git.

Chave	Tipo	Descrição
`root_path`	string	Necessário quando `code_source` está definido. O diretório local para empacotar. O diretório deve existir quando a CLI preparar a execução.
`remote_volume`	string	Uma localização de volume do Unity Catalog para o arquivo upload. Deve começar com `/Volumes/`. default para um local de Workspace.
`include_paths`	lista de strings	Caminhos para incluir relativos a `root_path`. As entradas devem ser não vazias e relativas, e não podem conter `..`. Omita a key para incluir todos os arquivos selecionados. Uma lista vazia não é válida.
`git`	objeto	pin o Snapshot da origem do código a uma Branch ou commit local do Git.

Se você omitir git, a CLI criará um pacote da árvore de trabalho, inclusive arquivos não confirmados e não rastreados que não são excluídos pelas regras de exclusão do Git. Um root_path relativo é resolvido no diretório que contém o arquivo YAML de carga de trabalho.

git

Tipo: Mapa

O objeto git dá suporte às seguintes keys:

Chave	Tipo	Descrição
`branch`	string	Obrigatório quando `commit` é omitido. Empacota o HEAD local do branch. Os arquivos selecionados não podem conter alterações sem commit.
`commit`	string	Necessário quando `branch` é omitido. Cria um pacote de um commit do armazenamento de objetos Git local. Mutuamente exclusivo com `branch`.

Chave	Tipo	Descrição
`branch`	string	Obrigatório quando `commit` é omitido. Empacota o HEAD local do branch. Os arquivos selecionados não podem conter alterações sem commit.
`commit`	string	Necessário quando `branch` é omitido. Cria um pacote de um commit do armazenamento de objetos Git local. Mutuamente exclusivo com `branch`.

Exemplo

O exemplo a seguir pacote caminhos selecionados do branch local main:

YAML
code_source:
  root_path: ./src
  include_paths:
    - training
    - configs
  git:
    branch: main

env_variables

Tipo: mapa de strings

A key env_variables contém nomes de variáveis de ambiente simples e valores de strings. Um nome não pode aparecer em secrets.

Exemplo

YAML
env_variables:
  BATCH_SIZE: '32'
  LEARNING_RATE: '0.001'

idempotency_token

Tipo: String

A key idempotency_token identifica envios repetidos. Um envio repetido com o mesmo token retorna a execução existente. A CLI gera um UUID quando essa key é omitida. O sinalizador de comando --idempotency-key tem precedência.

max_retries

Tipo: inteiro

A key max_retries especifica o número de novas tentativas após a tentativa inicial. O valor deve ser não negativo. default: 3.

mlflow_artifact_location

Tipo: String

A key mlflow_artifact_location contém um URI dbfs:/ ou um caminho /Volumes/. Se você omitir esta key, um novo experimento usará o local DBFS default, e um experimento existente usará seu local de artefato configurado. Para um experimento existente, o valor deve coincidir com a localização do artefato do experimento.

mlflow_experiment_directory

Tipo: String

A key mlflow_experiment_directory contém o diretório do workspace para o experimento. O caminho deve começar com /Workspace.

mlflow_run_name

Tipo: String

A key mlflow_run_name contém o nome da execução. Se você omitir essa key, o nome da execução usará por default o valor de experiment_name.

parâmetros

Tipo: Mapa

A key parameters contém valores aninhados de formato livre. A CLI serializa os valores para hyperparameters.yaml com os outros artefatos de lançamento.

Exemplo

YAML
parameters:
  learning_rate: 0.001
  model:
    hidden_size: 1024

permissões

Tipo: Lista de mapas

A key permissions contém permissões aplicadas após o envio. Se uma concessão falhar, a execução permanece criada e a CLI imprime um aviso.

Cada concessão suporta as seguintes key:

Chave	Tipo	Descrição
`level`	string	Obrigatório. Um nível de permissão, como `CAN_VIEW` ou `CAN_MANAGE`. O workspace valida o valor.
`user_name`	string	O email do usuário. Especifique exatamente um entre `user_name`, `group_name` ou `service_principal_name` para cada concessão.
`group_name`	string	O nome do grupo. Especifique exatamente um de `user_name`, `group_name`ou `service_principal_name` para cada concessão.
`service_principal_name`	string	O nome do service principal. Especifique exatamente um de `user_name`, `group_name`ou `service_principal_name` para cada concessão.

Chave	Tipo	Descrição
`level`	string	Obrigatório. Um nível de permissão, como `CAN_VIEW` ou `CAN_MANAGE`. O workspace valida o valor.
`user_name`	string	O email do usuário. Especifique exatamente um entre `user_name`, `group_name` ou `service_principal_name` para cada concessão.
`group_name`	string	O nome do grupo. Especifique exatamente um de `user_name`, `group_name`ou `service_principal_name` para cada concessão.
`service_principal_name`	string	O nome do service principal. Especifique exatamente um de `user_name`, `group_name`ou `service_principal_name` para cada concessão.

Exemplo

YAML
permissions:
  - user_name: trainer@example.com
    level: CAN_MANAGE
  - group_name: training-team
    level: CAN_VIEW

segredos

Tipo: mapa de strings

A key secrets contém nomes de variáveis de ambiente mapeados para referências secretas no formato exato scope/key. O escopo e a key não devem estar vazios. Um nome não pode aparecer em env_variables.

Exemplo

YAML
secrets:
  HF_TOKEN: my-scope/hf-token

Para obter informações sobre como criar e gerenciar segredos, consulte Gerenciamento de segredos.

timeout_minutes

Tipo: inteiro

A key timeout_minutes define o limite de tempo real para a execução completa, incluindo novas tentativas. O valor deve ser positivo. Se omitido, o workload usa o default do AI Runtime.

usage_policy_id

Tipo: String

A key usage_policy_id contém o UUID canônico de uma política de uso Serverless existente. Mutuamente exclusivo com usage_policy_name.

nome_da_política_de_uso

Tipo: String

A key usage_policy_name contém o nome de uma política de uso Serverless existente. Mutuamente exclusivo com usage_policy_id.

Para obter informações sobre como criar políticas de uso, consulte Atribuir uso com políticas de uso serverless.

Exemplo​

experiment_name​

compute​

comando​

ambiente​

Exemplo de ambiente gerenciado​

Exemplo de imagem personalizada​

code_source​

git​

Exemplo​

env_variables​

Exemplo​

idempotency_token​

max_retries​

mlflow_artifact_location​

mlflow_experiment_directory​

mlflow_run_name​

parâmetros​

Exemplo​

permissões​

Exemplo​

segredos​

Exemplo​

timeout_minutes​

usage_policy_id​

nome_da_política_de_uso​

Outros recursos​

Exemplo

experiment_name

compute

comando

ambiente

Exemplo de ambiente gerenciado

Exemplo de imagem personalizada

code_source

git

Exemplo

env_variables

Exemplo

idempotency_token

max_retries

mlflow_artifact_location

mlflow_experiment_directory

mlflow_run_name

parâmetros

Exemplo

permissões

Exemplo

segredos

Exemplo

timeout_minutes

usage_policy_id

nome_da_política_de_uso

Outros recursos