Informazioni di riferimento su YAML del carico di lavoro

Importante

Questa funzionalità è in Anteprima Pubblica.

Definire il nome dell'esperimento, il calcolo, il comando, l'ambiente e l'origine del codice di un processo di training nella configurazione YAML del carico di lavoro passata a databricks air run -f. Questa pagina tratta la configurazione per i carichi di lavoro on-demand A10 e H100.

Note

La CLI genera aiuto nella configurazione dallo stesso schema che utilizza per validare il carico di lavoro YAML. Esegui databricks air run -h config la lista completa dei campi per la versione installata. Usa databricks air run -h config.<section> (ad esempio, databricks air run -h config.environment) per i dettagli per sezione.

Configurazione minima

experiment_name: my-training
environment:
  dependencies:
    - mlflow
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: echo "Hello World"

Invia con:

databricks air run -f train.yaml -p profile

Concetti di base

I campi richiesti identificano l'esperimento, le risorse di calcolo e il comando. I campi opzionali configurano dipendenze, codice e comportamento di esecuzione.

Campi principali

La maggior parte delle configurazioni di training include cinque componenti:

experiment_name (Richiesto): Crea o aggiunge a un esperimento MLflow. Usa da 1 a 100 lettere, cifre, trattini o sottolinee ASCII.
environment(Opzionale): dipendenze Python o una versione base dell'ambiente.
compute (Richiesto): risorse GPU (tipo e conteggio).
command (Richiesto): Un comando o script shell non vuoto di al massimo 1.000 righe utilizzato per lanciare l'addestramento.
code_source (Opzionale): Percorso verso il tuo codice di addestramento, reso disponibile da remoto.

Per valori supportati e vincoli di campo, vedi Riferimento.

Il primo lavoro di formazione

experiment_name: simple-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/train.py

In questa configurazione:

experiment_name crea un esperimento MLflow denominato simple-training (o aggiunge una nuova esecuzione se esiste già).
environment usa l'ambiente predefinito e installa torch e transformers.
compute alloca un nodo H100 (8 GPU H100).
code_source carica la cartella repo nel nodo, disponibile all'indirizzo $CODE_SOURCE_PATH.
command viene eseguito train.py tramite torchrun le 8 GPU H100. Il file si trova in /home/username/repo/train.py locale.

Casi d'uso comuni

Usa variabili di ambiente e segreti per configurare il tuo codice di addestramento senza incorporare valori nello script.

Aggiungere variabili di ambiente

experiment_name: training-with-env
environment:
  dependencies:
    - torch
    - transformers
env_variables:
  BATCH_SIZE: '32'
  LEARNING_RATE: '0.001'
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/train.py

Usare segreti (chiavi API, token)

experiment_name: training-with-secrets
environment:
  dependencies:
    - torch
    - transformers
secrets:
  HF_TOKEN: 'my_scope/hf_token'
  WANDB_API_KEY: 'my_scope/wandb'
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/train.py

I segreti usano il formato scope/key e devono essere configurati in Segreti di Databricks. Vedere Gestione dei segreti per la configurazione. Un nome di variabile non può comparire sia env_variables in che secretsin .

Quando si condivide un modello YAML, altri utenti devono creare i propri segreti o avere accesso al segreto a cui si fa riferimento.

Environment

Usa il environment blocco per selezionare un ambiente GPU serverless e installare le dipendenze di Python. Ad esempio, la seguente configurazione seleziona la versione 4 dell'ambiente Standard e installa PyTorch e Transformers:

environment:
  version: '4'
  dependencies:
    - torch
    - transformers

Versione dell'ambiente

environment.version è opzionale e seleziona la versione dell'ambiente gestito per il carico di lavoro.

Ecco alcuni esempi:

"4" oppure "5" utilizzare la corrispondente versione dell'ambiente standard.
"databricks_ai_v5" per utilizzare l'ambiente AI di Databricks versione 5, che include pacchetti specifici per ML preinstallati. (Lista completa dei pacchetti)

Il seguente esempio seleziona l'ambiente AI di Databricks versione 5:

environment:
  version: 'databricks_ai_v5'
  dependencies: []

environment.dependencies è opzionale quando specifichi environment.version. Ommettila o usa una lista vuota se non hai bisogno di pacchetti aggiuntivi. Se fornisci dipendenze, usa una lista di stringhe, non un percorso scalare verso un file di requisiti.

Per informazioni sugli ambienti disponibili per AI Runtime, vedi Configura il tuo ambiente.

dipendenze Python

Elenca le dipendenze da Python del tuo carico di lavoro come una lista inline sotto environment.dependencies.

Formato di dipendenza

L'elenco delle dipendenze segue la specifica dell'ambiente di base di Databricks. Ogni voce è una specifica di pacchetto di tipo pip (ad esempio, my-library==6.1). L'elenco accetta anche le voci seguenti:

File dei requisiti: un riferimento a un oggetto esistente requirements.txt usando -r, ad esempio -r '/Workspace/Shared/requirements.txt'. Le variabili di ambiente, $HOME ad esempio vengono espanse.
Ruote: percorso assoluto di un .whl file, ad esempio /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl.
URL di indice: URL di indice, ad esempio --index-url https://pypi.org/simple.

environment:
  version: '4'
  dependencies:
    - --index-url https://pypi.org/simple
    - -r '/Workspace/Shared/requirements.txt'
    - my-library==6.1
    - /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl

Flag di installazione supportati

Le dipendenze vengono installate con uv. I flag di tipo pip seguenti sono supportati come voci di elenco:

Applicato all'intero installazione: --index-url, --extra-index-urle --find-links (-f) impostato o estende gli indici del pacchetto.
Applicato alla dipendenza che li segue: --no-deps, --no-build-isolation, --no-cache-dire --force-reinstall. Posizionare il flag sulla propria riga (o prima della specifica), seguito dalla dipendenza a cui si applica.

Ad esempio, per eseguire l'installazione flash-attn in base all'installazione già installata torch (senza isolamento della compilazione) e senza risolvere le proprie dipendenze:

environment:
  version: '4'
  dependencies:
    - torch
    - --no-build-isolation
    - --no-deps
    - flash-attn

Note

--trusted-host non è supportato. Poiché uv configura l'attendibilità per URL di indice, usare --index-url o --extra-index-url .

Immagini Docker personalizzate

Come alternativa a un ambiente gestito, specificare un'immagine container Docker personalizzata da Artifact Registry utilizzando environment.unity_catalog_image. Il valore utilizza il <catalog>.<schema>.<image>:<tag> formato senza il nome host del registro. environment.unity_catalog_image è mutuamente esclusivo sia environment.dependencies con che environment.version, inclusa una lista di dipendenze vuota.

experiment_name: my-dcs-training
environment:
  unity_catalog_image: main.ml.training:v1
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python /app/train.py

Prima di usare un'immagine personalizzata, inviala nel Registro degli Artefatti nello stesso workspace che usi per inviare il carico di lavoro. Vedi Inizia con Registro degli Artefatti e Usa immagini Docker personalizzate con AI Runtime.

Usare le origini codice

Il code_source blocco carica il codice locale in modo che il processo di training possa eseguirlo.

root_path è la directory locale da creare uno snapshot. Senza un git: blocco, la CLI di Databricks impacchettisce l'albero di lavoro, inclusi cambiamenti non commessi, rispettando le regole Git ignore.
Per fare snapshot di una versione Git commessa, aggiungi un git: blocco con un branch oppure commit. La directory deve trovarsi in un repository Git. Se root_path punta a una sottodirectory, solo quel sottoalbero viene impacchettato.
Per i repository di grandi dimensioni, include_paths consente di creare uno snapshot di un subset.

Esempio minimo

experiment_name: simple-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
command: python $CODE_SOURCE_PATH/train.py

Nel computer remoto il codice viene inserito in /databricks/code_source/<directory_name>, dove <directory_name> è il componente di percorso finale di root_path. $CODE_SOURCE_PATH è impostato su tale percorso assoluto, quindi usarlo nel comando invece di impostare come hardcoded il percorso.

Repository Git: aggiungere per ramo o commit

Per i repository Git, aggiungi un git: blocco per fissare la versione del codice tramite branch o commit SHA. branch e commit si escludono a vicenda: specificare esattamente uno all'interno del blocco. La revisione deve esistere localmente. La CLI non recupera da un repository remoto.

Aggiungere a un ramo (usa l'head locale di tale ramo):

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main # Uses local HEAD of main (no remote fetch)
command: bash $CODE_SOURCE_PATH/train.sh

Aggiungere a un commit SHA (riproducibilità esatta):

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      commit: abc1234567 # Pins specific commit
command: bash $CODE_SOURCE_PATH/train.sh

Campi chiave:

root_path (Richiesto): percorso locale verso il repository o una sottodirectory per snapshot.
git.branch (Opzionale): Utilizza il HEAD locale della filiale. Modifiche non compromettenti nei percorsi selezionati causano un errore perché non fanno parte di quel commit.
git.commit (Opzionale): Usa un commit specifico disponibile localmente. Le modifiche non impegnate non sono incluse.
git.remote: Ometti questo campo o impostalo a false. Il recupero remoto con true o un nome remoto non è supportato. Recupera la revisione localmente prima di inviare il carico di lavoro.

Se ometti il git: blocco, la CLI Databricks impacchetterebbe l'albero di lavoro, includendo le modifiche non compromettenti ed escludendo i file ignorati. Non è necessario alcun campo aggiuntivo.

Directory non Git

Puoi fare snapshot a directory che non sono repository Git. Omettere il git: blocco. La CLI impacchetta la directory rispettando le regole Git ignore. Sia gli snapshot a albero di lavoro che quelli fissati su Git possono riutilizzare un archivio caricato quando la chiave della cache dello snapshot è invariata.

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/my_project
command: python $CODE_SOURCE_PATH/train.py

Filtro cartelle con `include_paths`

Per i monorepos di grandi dimensioni, snapshot solo cartelle specifiche per ridurre il tempo di caricamento e il download e le dimensioni degli snapshot:

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    include_paths:
      - research/models
      - research/common
      - research/configs
command: python $CODE_SOURCE_PATH/research/models/launch_training.py

Punti principali:

Il campo è facoltativo. Se omessa, la CLI seleziona i file sotto root_path utilizzando la modalità snapshot descritta sopra. Non impostare una lista vuota.
I percorsi devono essere relativi a root_path, senza alcun elemento di guida /.
.. non è consentito. Non puoi fare riferimento alle directory genitori.

Carica istantanee su un volume

Per impostazione predefinita, la CLI carica snapshot nel tuo workspace. Per usare invece un volume del Catalogo Unity, imposta code_source.snapshot.remote_volume un percorso che inizia con /Volumes/:

code_source:
  type: snapshot
  snapshot:
    root_path: .
    remote_volume: /Volumes/main/ml/training-code

Devi avere accesso al volume e il permesso di scrivere file su di esso.

Funzionalità avanzate

Configura i parametri di addestramento, il comportamento dei ritenti e l'attribuzione dei costi con i seguenti campi.

Iperparametri personalizzati

Passare la configurazione strutturata allo script di training tramite HYPERPARAMETERS_PATH:

experiment_name: parameterized-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/train.py
parameters:
  model:
    name: 'gpt2'
    hidden_size: 768
  training:
    batch_size: 32
    learning_rate: 0.0001

Leggerli nello script:

import os
import yaml

with open(os.environ['HYPERPARAMETERS_PATH']) as f:
    params = yaml.safe_load(f)

learning_rate = params['training']['learning_rate']
model_name = params['model']['name']

Affidabilità dei processi

experiment_name: reliable-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/train.py
max_retries: 2
timeout_minutes: 90

max_retries: 2 consente fino a due tentativi dopo il primo tentativo. Il valore predefinito è 3. Impostato max_retries: 0 per disabilitare i tentativi di tentativo.

timeout_minutes: 90 imposta un timeout di 90 minuti per la run del lavoro inviato. Non è un budget separato di 90 minuti per ogni tentativo. Il valore deve essere almeno 1. Se omesso, si applica il default del backend.

Attribuzione dei costi

Assegna un carico di lavoro a una politica di utilizzo serverless esistente con usage_policy_name. Il nome viene risolto nell'ID del criterio all'avvio del carico di lavoro. In alternativa, imposta usage_policy_id l'UUID di una politica esistente. Questi campi sono mutuamente esclusivi. I nomi delle policy devono contenere da 1 a 127 caratteri. Per la configurazione, vedere Utilizzo degli attributi con criteri di utilizzo serverless.

experiment_name: my-training
environment:
  dependencies:
    - mlflow
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: echo "Hello World"
usage_policy_name: my team policy

Reference

Usa queste tabelle per i campi di carico di lavoro on-demand e le configurazioni GPU descritte in questa pagina. Per lo schema completo accettato dalla CLI installata, esegui databricks air run -h config.

Riferimento del campo principale

Campo	Tipo	Description	Example
`experiment_name`	string	Nome richiesto dell'esperimento MLflow. Da 1 a 100 lettere, cifre, trattini o sottolinee ASCII.	`"my-training-job"`
`mlflow_artifact_location`	string	Posizione radice per gli artefatti MLflow registrati dalla run. Opzionale.	`/Volumes/main/default/mlflow-artifacts/my-training`
`environment.dependencies`	list	Elenco opzionale delle specifiche di dipendenza.	`["torch", "transformers"]`
`environment.version`	stringa o integer	Versione dell'ambiente gestito. Opzionale. Usa il valore predefinito se omesso. Vedi Versione Ambiente.	`"4"`, `"5"`, `"databricks_ai_v5"`
`compute.num_accelerators`	int	Numero di GPU. Deve essere un multiplo delle GPU per nodo per il selezionato `compute.accelerator_type`.	`1`, `4`, `8`
`compute.accelerator_type`	string	Configurazione dell'acceleratore, inclusi il tipo di GPU e la forma del nodo. Vedi Configurazioni GPU supportate.	`"GPU_1xA10"`, `"GPU_1xH100"`, `"GPU_8xH100"`
`code_source`	dict	Configurazione dell'origine del codice.	Vedere Usare le origini del codice.
`command`	string	Comando o script di shell non vuoto richiesto, al massimo 1.000 righe.	`torchrun --nproc_per_node=8 train.py`

Configurazioni GPU supportate

La CLI corrisponde ai nomi degli acceleratori in modo sensibile alla maiuscola e minuscola. La disponibilità e le quote dipendono dal tuo spazio di lavoro.

`accelerator_type`	GPU per nodo	`num_accelerators` Requisito	Note
`GPU_1xA10`	1	Qualsiasi intero positivo	Singolo A10, valido per lo sviluppo e i carichi di lavoro di piccole dimensioni.
`GPU_1xH100`	1	Qualsiasi intero positivo	Singolo H100.
`GPU_8xH100`	8	Un multiplo positivo di 8	Nodo H100 completo, tipico per il training distribuito.

Per le capacità degli acceleratori e i casi d'uso consigliati, vedi Opzioni hardware.

compute.num_accelerators è il numero totale di GPU per il carico di lavoro. Deve essere un multiplo delle GPU per nodo per il selezionato compute.accelerator_type.

Campi facoltativi

Questi campi configurano l'esecuzione oltre al suo esperimento, calcolo e comando richiesti:

Campo	Tipo	Vincoli e comportamento
`env_variables`	Mappa delle stringhe	Semplici variabili ambientali. Un nome non può comparire anche in `secrets`.
`secrets`	Mappa delle stringhe	Nomi delle variabili dell'ambiente mappati a `scope/key` riferimenti segreti.
`parameters`	mappatura	Parametri di addestramento free-form annidati esposti attraverso `HYPERPARAMETERS_PATH`.
`max_retries`	integer	Conteggio dei ritenti non negativo. Di default è `3`. Impostare su `0` per disabilitare i tentativi.
`timeout_minutes`	integer	Time out per il lavoro in pochi minuti. Deve essere almeno `1`. Se omesso, si applica il default del backend.
`idempotency_token`	string	Gettone non vuoto di al massimo 64 caratteri per deduplicare le sottomissioni. La `--idempotency-key` bandiera ha la precedenza.
`mlflow_run_name`	string	Nome della corsa da 1 a 100 lettere, cifre, trattini o sottolineamenti ASCII. Di default è `experiment_name`.
`mlflow_experiment_directory`	string	Directory dello spazio di lavoro per l'esperimento MLflow. Deve iniziare con `/Workspace`. La CLI crea la directory se necessario.
`mlflow_artifact_location`	string	Radice di artefatto come `dbfs:/` URI o `/Volumes/` percorso. La CLI normalizza `/Volumes/` i percorsi verso `dbfs:/Volumes/` gli URI.
`permissions`	Elenco degli oggetti	Ogni borsa richiede un non vuoto `level` ed esattamente uno di `user_name`, `group_name`, o `service_principal_name`. I livelli di permesso sono convalidati dallo spazio di lavoro.
`usage_policy_name`	string	Nome della politica d'uso esistente da 1 a 127 caratteri. Si escludono con `usage_policy_id` a vicenda.
`usage_policy_id`	string	UUID della politica d'uso esistente. Si escludono con `usage_policy_name` a vicenda.

Configurazione dell'ambiente

environment:
  version: '4'
  dependencies:
    - torch
    - transformers
env_variables:
  BATCH_SIZE: '32'
secrets:
  HF_TOKEN: 'my_scope/hf_token'

Per le versioni dell'ambiente, il formato delle dipendenze e i flag di installazione supportati, vedi Ambiente.

Immagine Docker personalizzata

environment:
  unity_catalog_image: main.ml.training:v1

Questo campo è mutuamente esclusivo con environment.dependencies e environment.version. Spingi l'immagine nel Registro degli Artefatti prima di usarlo. Vedi Usa immagini Docker personalizzate con runtime AI.

Permessi di esecuzione

Concedere l'accesso al lavoro inviato utilizzando un titolare per ogni voce di lavoro. Per esempio:

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

Directoria degli esperimenti MLflow

Memorizza l'esperimento in una directory di spazio di lavoro condiviso:

mlflow_experiment_directory: /Workspace/Shared/training-experiments

Configurazione dell'origine del codice

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo # REQUIRED — local path to repo or directory
    git: # Optional (git repos only) — pin to a branch or commit
      branch: main # Uses the branch's local HEAD
      # commit: abc1234567 # Mutually exclusive with 'branch'
      remote: false # Optional; remote fetching is not supported
    include_paths: # Optional — filter included paths
      - src/
      - configs/

Vincoli di campo:

git.branch e git.commit si escludono a vicenda: specificare esattamente uno all'interno del git: blocco.
Ometti git.remote o impostalo su false. La CLI non recupera revisioni da un telecomando.
Se ometti il git: blocco, l'albero di lavoro viene impacchettato, rispettando le regole di ignorare Git, incluse le modifiche non commesse nei file selezionati.

Parametri personalizzati

Passato al carico di lavoro tramite HYPERPARAMETERS_PATH:

parameters:
  model:
    name: 'gpt2'
    hidden_size: 768
  training:
    batch_size: 32

Nome esecuzione MLflow

Usa da 1 a 100 lettere, cifre, trattini o sottolinee ASCII. Se omesso, il nome della run si riporta experiment_namedi default a .

mlflow_run_name: 'experiment-001-baseline'

Posizione dell'artefatto MLflow

Imposta mlflow_artifact_location per memorizzare artefatti per un esperimento MLflow in una posizione root personalizzata. Se ometti questo campo, un nuovo esperimento utilizza la posizione DBFS predefinita, come dbfs:/databricks/mlflow-tracking/<experiment-id>/....

mlflow_artifact_location: /Volumes/main/default/mlflow-artifacts/my-training

Se l'accesso a DBFS è limitato o preferisci Unity Catalog, specifica un /Volumes/<catalog>/<schema>/<volume>/... percorso o l'URI equivalente dbfs:/Volumes/<catalog>/<schema>/<volume>/... . La CLI Databricks converte un /Volumes percorso verso l'URI dbfs: che MLflow utilizza.

Usa una location unica per ogni esperimento. La posizione dell'artefatto di un esperimento MLflow è fissata quando l'esperimento viene creato. Se experiment_name identifica un esperimento esistente, mlflow_artifact_location deve corrispondere alla sua posizione dell'artefatto o essere omesso. Per usare una posizione diversa, specifica un nuovo nome per l'esperimento.

Risoluzione del percorso

I valori relativi code_source.snapshot.root_path si risolvono dalla directory del file YAML del carico di lavoro. include_paths Le voci si risolvono da root_path. I percorsi all'interno command si riferiscono a file sul runtime remoto, non alla tua macchina locale. Usalo $CODE_SOURCE_PATH per fare riferimento al codice caricato.

Struttura delle cartelle:

/home/username/my-project/
├── train.yaml
└── scripts/
    └── train.py

Configurazione YAML:

experiment_name: my-training
environment:
  dependencies:
    - torch
    - transformers
compute:
  num_accelerators: 8
  accelerator_type: GPU_8xH100
code_source:
  type: snapshot
  snapshot:
    root_path: . # Relative to train.yaml
    git:
      branch: main
command: torchrun --nproc_per_node=8 $CODE_SOURCE_PATH/scripts/train.py

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-09-30