Riferimento YAML del carico di lavoro per la CLI legacy di Python

Importante

Questa documentazione è stata ritirata e potrebbe non essere aggiornata.

La CLI basata air su Python, installata con il databricks-air pacchetto, è ora deprecata e non è più mantenuta attivamente.

Usa la CLI Databricks per i nuovi carichi di lavoro. Vedi Utilizzare la Databricks CLI con Runtime di AI.

Definisci il nome dell'esperimento, le risorse di calcolo, il comando, l'ambiente e il codice sorgente di un processo di training nel file di configurazione YAML del carico di lavoro che passi a air run --file. Questa pagina documenta ogni campo.

Note

Il riferimento autorevole per la configurazione YAML è la guida integrata nella CLI. Eseguire air -h config per la visualizzazione di primo livello e air -h config.<section> ( ad esempio , air -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 tramite:

air run --file train.yaml -p profile

Concetti di base

Campi principali

La maggior parte delle configurazioni di training include cinque componenti:

  1. experiment_name (Richiesto): Crea o aggiunge a un esperimento MLflow.
  2. environment(Opzionale): dipendenze Python e versione base dell'ambiente.
  3. compute (Richiesto): risorse GPU (tipo e conteggio).
  4. command (Richiesto): Il comando o i comandi bash usati per avviare l'addestramento.
  5. 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

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 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 train.py

I segreti usano il formato scope/key e devono essere configurati in Segreti di Databricks. Vedere Gestione dei segreti per la configurazione.

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

Ambiente

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: []

Se specifichi environment.version, devi anche fornire environment.dependencies come lista inline. Usa una lista vuota se non hai bisogno di installare pacchetti aggiuntivi.

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.
  • Wheels: il percorso assoluto di un file .whl, 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:

  • Si applica all'intera installazione: --index-url, --extra-index-url e --find-links (-f) impostano o estendono gli indici del pacchetto.
  • Applicato alla dipendenza che li segue: --no-deps, --no-build-isolation, --no-cache-dire --force-reinstall. Posiziona il flag su una riga separata (o prima della specifica), seguito dalla dipendenza a cui si applica.

Ad esempio, per installare flash-attn rispetto a torch già installato (senza isolamento della build) e senza risolvere le relative dipendenze:

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

Note

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

Immagini Docker personalizzate

In alternativa a environment.dependencies, è possibile specificare un'immagine del contenitore Docker personalizzata usando environment.docker_image.url. environment.docker_image.url è mutuamente esclusivo sia con environment.dependencies sia con environment.version: non è possibile utilizzare nessuno dei due nello stesso carico di lavoro.

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

Prima di usare un'immagine personalizzata, registrarla con air register image. Per dettagli completi, inclusi requisiti di immagine, immagini base Databricks e pattern Dockerfile, vedi Usa immagini Docker personalizzate con la CLI legacy di Python.

Lavorare con le sorgenti del codice

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

  • root_path è la directory locale di cui creare un'istantanea. Per impostazione predefinita, air archivia l'albero di lavoro così com'è (incluse eventuali modifiche non sottoposte a commit) in un semplice archivio tar.
  • Per creare invece uno snapshot di una versione Git bloccata, aggiungi un blocco git: con un branch o un commit. Ciò richiede che root_path sia un repository git e abilita la creazione di snapshot basata sulle versioni (memorizzazione nella cache, git archive).
  • 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 quel percorso assoluto, quindi usalo nel comando invece di codificare esplicitamente il percorso.

Repository Git: aggiungere per ramo o commit

Per i repository git, aggiungere un blocco git: per fissare la versione del codice in base al branch o al commit SHA. branch e commit si escludono a vicenda: specificare esattamente uno all'interno del blocco.

Fissa a un ramo (usa l'HEAD locale di quel ramo):

code_source:
  type: snapshot
  snapshot:
    root_path: /home/username/repo
    git:
      branch: main # Uses local HEAD of main (no remote fetch)
command: 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: train.sh

Campi chiave:

  • root_path (Obbligatorio): percorso locale alla radice del repository git.
  • git.branch (Facoltativo): nome del ramo. Utilizza HEAD locale; nessun recupero dal remoto. Si escludono con git.commit a vicenda.
  • git.commit (Facoltativo): SHA specifico del commit. Si escludono con git.branch a vicenda.
  • git.remote (Facoltativo): usa l'HEAD remoto del ramo anziché quello locale. Impostare su true per rilevare automaticamente il telecomando o su un nome remoto (ad esempio, upstream) per recuperare da un remoto specifico. Valido solo con git.branch.

Se si omette il blocco git:, air crea un semplice archivio tar dell'albero di lavoro, incluse eventuali modifiche di cui non è ancora stato eseguito il commit. Non è necessario alcun campo aggiuntivo.

Directory non Git

È possibile creare snapshot delle directory che non sono repository Git. Omettere il blocco git:, che richiede che root_path sia un repository Git. Senza di esso, non c'è alcuna memorizzazione nella cache della versione; viene caricato un nuovo tarball per ogni esecuzione.

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

Filtraggio delle cartelle con include_paths

Per i monorepo di grandi dimensioni, crea uno snapshot solo di cartelle specifiche per ridurre i tempi di caricamento e download e le dimensioni dello 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 viene omesso, l'intero repository viene incluso per impostazione predefinita.
  • I percorsi devono essere relativi alla radice del repository (nessun carattere iniziale /).
  • .. non è consentito; non è possibile fare riferimento alle directory parent.

Funzionalità avanzate

Iperparametri personalizzati

Passa la configurazione strutturata allo script di addestramento 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 train.py
parameters:
  model:
    name: 'gpt2'
    hidden_size: 768
  training:
    batch_size: 32
    learning_rate: 0.0001

Leggili nel tuo 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 train.py
max_retries: 2
timeout_minutes: 90

Se il carico di lavoro fallisce, viene ritentato due volte. Ogni tentativo ha 90 minuti da completare, quindi il budget totale di wall-clock è 90 × 3 = 270 minuti.

Attribuzione dei costi

Collega un carico di lavoro a un criterio di bilancio esistente tramite usage_policy_name. Il nome viene associato all'ID del criterio quando viene avviato il carico di lavoro. 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

Riferimenti

Riferimento del campo principale

Campo Tipo Description Example
experiment_name string Nome dell'esperimento per MLflow. "my-training-job"
mlflow_artifact_location string Posizione radice per gli artefatti MLflow registrati dalla run. Optional. /Volumes/main/default/mlflow-artifacts/my-training
environment.dependencies list Elenco in linea delle specifiche delle dipendenze di pip. ["torch", "transformers"]
environment.version string Versione dell'ambiente GPU serverless. Optional. Usa l'ambiente 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. Vedi Lavorare con le origini del codice sorgente.
command string Comandi Bash per avviare il training. torchrun --nproc_per_node=8 train.py

Configurazioni GPU supportate

accelerator_type GPU per nodo num_accelerators Requisito Note
GPU_1xA10 1 Qualsiasi intero positivo Un A10 singolo, ideale per lo sviluppo e carichi di lavoro ridotti.
GPU_1xH100 1 1 H100 singolo.
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

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.

Configurazione dell'immagine Docker personalizzata

environment:
  docker_image:
    url: myorg/myrepo:mytag

Si escludono a vicenda con environment.dependencies e environment.version. Registrare l'immagine con air register image prima dell'uso. Vedi Usa immagini Docker personalizzate con la CLI Python legacy.

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 # Branch name; uses local HEAD unless 'remote' is set
      # commit: abc1234567 # Mutually exclusive with 'branch'
      remote: false # Optional — true to auto-detect remote HEAD, or a remote name string
    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.
  • git.remote richiede git.branch (non ha alcun effetto con git.commit).
  • Se si omette il blocco git:, l'albero di lavoro viene impacchettato come un semplice tarball, incluse eventuali modifiche di cui non è stato eseguito il commit.

Parametri personalizzati

Passato al carico di lavoro tramite HYPERPARAMETERS_PATH:

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

Nome dell'esecuzione MLflow

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 air CLI converte un percorso /Volumes nell'URI dbfs: usato da MLflow.

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

Tutti i percorsi nel file YAML del carico di lavoro sono relativi al carico di lavoro YAML, a meno che non siano percorsi assoluti.

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
  • Last updated on