Aller au contenu principal
Page non répertoriée
Cette page n'est pas répertoriée. Les moteurs de recherche ne l'indexeront pas, et seuls les utilisateurs ayant un lien direct peuvent y accéder.
Dernière mise à jour le

Référence YAML de Workload pour le CLI Python legacy

important

Cette documentation a été supprimée et peut ne plus être mise à jour.

La CLI air basée sur Python, installée avec le package databricks-air, est désormais dépréciée et n'est plus activement maintenue.

Utilisez la CLI Databricks pour les nouvelles charges de travail. Consultez Utiliser la CLI Databricks avec AI Runtime.

Définissez le nom d'Experimentation, le compute, la commande, l'environnement et la source du code d'un Job d'entraînement dans la configuration YAML de charge de travail que vous transmettez à air run --file. Cette page documente chaque champ.

remarque

La vérité de terrain pour la configuration YAML est l’aide dans la CLI. Exécutez air -h config pour la vue de niveau supérieur et air -h config.<section> (par exemple air -h config.environment) pour les détails par section.

Configuration minimale​

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

Envoyer avec :

Bash
air run --file train.yaml -p profile

Concepts fondamentaux​

Champs cœur​

La plupart des configurations d'entraînement comprennent cinq composants :

  1. experiment_name (Obligatoire) : Créer ou ajouter à une experimentation MLflow.
  2. environment (Facultatif) : dépendances Python et version de l'environnement de base.
  3. compute (Obligatoire) : ressources GPU (type et nombre).
  4. command (Obligatoire) : La commande Bash ou les commandes utilisées pour lancer l'entraînement.
  5. code_source (Facultatif) : chemin d'accès à votre code d'entraînement, rendu disponible à distance.

Pour les valeurs prises en charge et les contraintes de champ, consultez la Référence.

Votre premier job d’entraînement​

YAML
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

Dans cette configuration :

  • experiment_name crée une Experimentation MLflow nommée simple-training (ou ajoute une nouvelle exécution si elle existe déjà).
  • environment utilise l'environnement par default et installe torch et transformers.
  • compute alloue un nœud H100 (8 GPU H100).
  • code_source upload le dossier repo sur le nœud, disponible sur $CODE_SOURCE_PATH.
  • command exécute train.py via torchrun sur les 8 GPU H100. Le fichier se trouve au niveau de /home/username/repo/train.py localement.

Cas d'utilisation courants​

Ajouter des variables d’environnement​

YAML
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

Utiliser des secrets (clés API, jetons)​

YAML
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

Les secrets utilisent le format scope/key et doivent être configurés dans Databricks Secrets. Voir la Gestion des secrets pour la configuration.

Lors du partage d’un template YAML, les autres utilisateurs doivent créer leurs propres secrets ou avoir accès au secret référencé.

Environnement​

Utilisez le bloc environment pour sélectionner un environnement GPU serverless et installer les dépendances Python. Par exemple, la configuration suivante sélectionne la version 4 de l'environnement standard et installe PyTorch et Transformers :

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

Version de l'environnement​

environment.version est facultatif et permet de sélectionner la version de l’environnement géré pour le workload.

Quelques exemples :

  • "4" ou "5" pour utiliser la version de l'environnement standard correspondante.
  • "databricks_ai_v5" pour utiliser Databricks AI environment version 5, qui inclut des packages ML préinstallés. (Liste complète des packages)

L’exemple suivant sélectionne la version 5 de l’environnement Databricks AI :

YAML
environment:
  version: 'databricks_ai_v5'
  dependencies: []

Si vous spécifiez environment.version, vous devez également fournir environment.dependencies en tant que liste inline. Utilisez une liste vide si vous n’avez pas besoin d’installer de packages supplémentaires.

Pour plus d'informations sur les environnements disponibles pour AI Runtime, consultez Configurer votre environnement.

Dépendances Python​

Listez les dépendances Python de votre charge de travail sous forme de liste en ligne sous environment.dependencies.

Format des dépendances

La liste des dépendances respecte la spécification d’environnement de base de Databricks. Chaque entrée correspond à une spécification de package de type pip (par exemple, my-library==6.1). La liste accepte également les entrées suivantes :

  • Fichiers des exigences : une référence à un requirements.txt existant utilisant -r, par exemple -r '/Workspace/Shared/requirements.txt'. Les variables d'environnement telles que $HOME sont développées.
  • Roues : chemin absolu vers un fichier .whl, par exemple /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl
  • URL d'index : une URL d'index, par exemple --index-url https://pypi.org/simple.
YAML
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

Indicateurs d'installation pris en charge

Les dépendances sont installées avec uv. Les drapeaux de style pip suivants sont pris en charge en tant qu'entrées de liste :

  • Appliqué à l'ensemble de l'installation : --index-url, --extra-index-url et --find-links (-f) définissent ou étendent les index de packages.
  • S'applique à la dépendance qui les suit : --no-deps, --no-build-isolation, --no-cache-dir et --force-reinstall. Placez l’indicateur sur sa propre ligne (ou avant la spécification), suivi de la dépendance à laquelle il s’applique.

Par exemple, pour installer flash-attn par rapport au torch déjà installé (pas d'isolement de build) et sans résoudre ses propres dépendances :

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

--trusted-host n'est pas pris en charge. Comme uv configure la confiance par URL d’index, utilisez plutôt --index-url ou --extra-index-url.

Images Docker personnalisées​

Alternativement à environment.dependencies, vous pouvez spécifier une image de conteneur Docker personnalisée en utilisant environment.docker_image.url. environment.docker_image.url est mutuellement exclusif avec environment.dependencies et environment.version : vous ne pouvez pas utiliser les deux dans la même charge de travail.

YAML
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

Avant d'utiliser une image personnalisée, enregistrez-la auprès de air register image. Pour plus de détails, y compris les exigences en matière d’images, les images de base Databricks et les modèles Dockerfile, voir Utiliser des images Docker personnalisées avec la CLI Python héritée.

Travailler avec des sources de code​

Le bloc code_source upload le code local pour que le job d’entraînement puisse l’exécuter.

  • root_path est le répertoire local à capturer dans un snapshot. default, air package l'arborescence de travail telle quelle (y compris les modifications non validées) sous forme d'un simple tarball.
  • Pour créer un instantané d'une version git pin à la place, ajoutez un bloc git: avec un branch ou commit. Cela nécessite que root_path soit un repository git et active l'instantané prenant en charge les versions (mise en cache, git archive).
  • Pour les grands repository, include_paths vous permet d’effectuer un snapshot d’un sous-ensemble.

Exemple minimal​

YAML
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

Sur la machine distante, le code est placé à /databricks/code_source/<directory_name>, où <directory_name> est le dernier composant de chemin de root_path. $CODE_SOURCE_PATH est défini sur ce chemin absolu, utilisez-le donc dans votre commande au lieu de coder en dur l'emplacement.

repository Git : pin par Branch ou commit​

Pour les repository git, ajoutez un bloc git: pour pin la version du code par Branch ou par commit SHA. branch et commit s’excluent mutuellement : indiquez-en exactement un dans le bloc.

pin à une Branch (utilise le HEAD local de cette Branch) :

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

Pin à un SHA de commit (reproductibilité exacte) :

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

Champs clés :

  • root_path (Obligatoire) : Chemin d'accès local vers la racine de votre repository git.
  • git.branch (Facultatif) : nom de la Branch. Utilise HEAD local ; aucune extraction distante. Mutuellement exclusif avec git.commit.
  • git.commit (Facultatif) : AHS du commit spécifique. Mutuellement exclusif avec git.branch.
  • git.remote (Facultatif) : utilisez la tête distante de la Branch au lieu de la tête locale. Réglez sur true pour détecter automatiquement la distance, ou sur un nom distant (par exemple, upstream) pour récupérer à partir d’une distance spécifique. Uniquement valide avec git.branch.

Si vous omettez le bloc git:, air package l'arborescence de travail sous la forme d'une simple archive tar, y compris les modifications non validées. Aucun champ supplémentaire n'est requis.

Répertoires hors Git​

Vous pouvez prendre un instantané des répertoires qui ne sont pas des repository git. Omettez le bloc git:, qui nécessite que root_path soit un repository git. Sans cela, il n’y a pas de mise en cache de version ; une archive tar fraîche est upload à chaque exécution.

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

Filtrage de dossier avec include_paths​

Pour les gros monorepos, prenez un instantané uniquement des dossiers spécifiques pour réduire le temps d'upload et de download ainsi que la taille de l'instantané :

YAML
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

Points clés :

  • Le champ est facultatif. S'il n'est pas précisé, l'ensemble du repository est inclus par default.
  • Les chemins d'accès doivent être relatifs à la racine du repository (sans / au début).
  • .. n’est pas autorisée ; vous ne pouvez pas référencer des répertoires parents.

Fonctionnalités avancées​

Hyperparamètres personnalisés​

Transmettez la configuration structurée à votre script de formation via HYPERPARAMETERS_PATH:

YAML
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

Lisez-les dans votre script :

Python
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']

Fiabilité du job​

YAML
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

Si la charge de travail échoue, elle est relancée deux fois. Chaque tentative dispose de 90 minutes pour se terminer, soit un budget total de 90 × 3 = 270 minutes.

Attribution des coûts​

Joindre une charge de travail à une politique budgétaire existante via usage_policy_name. Le nom est résolu en identifiant de la politique lors du lancement de la charge de travail. Pour la configuration, voir Attribuer l’utilisation avec des politiques d’utilisation serverless.

YAML
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

Référence​

Référence de champ de base​

Champ

Type

Description

Exemple

experiment_name

chaîne

Nom de l'Experimentation pour MLflow.

"my-training-job"

mlflow_artifact_location

chaîne

Emplacement racine des artefacts MLflow enregistrés par l’exécution. Facultatif.

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

environment.dependencies

liste

Liste en ligne des spécifications de dépendance pip.

["torch", "transformers"]

environment.version

chaîne

Version de l’environnement GPU serverless. Facultatif. Utilise l’environnement default si omis. Consultez Version de l’environnement.

"4", "5", "databricks_ai_v5"

compute.num_accelerators

int

Nombre de GPU. Doit être un multiple des GPU par nœud pour le compute.accelerator_type sélectionné.

1, 4, 8

compute.accelerator_type

chaîne

Configuration de l’accélérateur, y compris le type de GPU et la forme du nœud. Voir Configurations GPU prises en charge.

"GPU_1xA10", "GPU_1xH100", "GPU_8xH100"

code_source

dict

Configuration du code source.

Consultez Travailler avec les codes source.

command

chaîne

Commandes Bash pour lancer l’entraînement.

torchrun --nproc_per_node=8 train.py

Champ

Type

Description

Exemple

experiment_name

chaîne

Nom de l'Experimentation pour MLflow.

"my-training-job"

mlflow_artifact_location

chaîne

Emplacement racine des artefacts MLflow enregistrés par l’exécution. Facultatif.

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

environment.dependencies

liste

Liste en ligne des spécifications de dépendance pip.

["torch", "transformers"]

environment.version

chaîne

Version de l’environnement GPU serverless. Facultatif. Utilise l’environnement default si omis. Consultez Version de l’environnement.

"4", "5", "databricks_ai_v5"

compute.num_accelerators

int

Nombre de GPU. Doit être un multiple des GPU par nœud pour le compute.accelerator_type sélectionné.

1, 4, 8

compute.accelerator_type

chaîne

Configuration de l’accélérateur, y compris le type de GPU et la forme du nœud. Voir Configurations GPU prises en charge.

"GPU_1xA10", "GPU_1xH100", "GPU_8xH100"

code_source

dict

Configuration du code source.

Consultez Travailler avec les codes source.

command

chaîne

Commandes Bash pour lancer l’entraînement.

torchrun --nproc_per_node=8 train.py

Configurations GPU prises en charge​

accelerator_type

GPU par nœud

num_accelerators exigence

Notes

GPU_1xA10

1

Tout entier positif

Un seul A10, idéal pour le développement et les petites charges de travail.

GPU_1xH100

1

1

Un seul H100.

GPU_8xH100

8

Un multiple positif de 8

Nœud H100 complet, typique pour l'entraînement distribué.

accelerator_type

GPU par nœud

num_accelerators exigence

Notes

GPU_1xA10

1

Tout entier positif

Un seul A10, idéal pour le développement et les petites charges de travail.

GPU_1xH100

1

1

Un seul H100.

GPU_8xH100

8

Un multiple positif de 8

Nœud H100 complet, typique pour l'entraînement distribué.

Pour connaître les fonctionnalités d'accélération et les cas d'utilisation recommandés, consultez la section Matériel.

compute.num_accelerators est le nombre total de GPU pour le workload. Il doit s'agir d'un multiple du nombre de GPU par nœud pour le compute.accelerator_type sélectionné.

Champs optionnels​

Configuration de l’environnement

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

Pour les versions d’environnement, le format des dépendances et les flags d’installation pris en charge, consultez Environnement.

Configuration d’image Docker personnalisée

YAML
environment:
  docker_image:
    url: myorg/myrepo:mytag

Mutuellement exclusif avec environment.dependencies et environment.version. Enregistrez l'image avec air register image avant de l'utiliser. Voir Utiliser des images Docker personnalisées avec l'ancienne CLI Python.

Configuration du code source

YAML
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/

Contraintes de champ :

  • git.branch et git.commit sont mutuellement exclusifs : spécifiez-en exactement un dans le bloc git:.
  • git.remote nécessite git.branch (cela n'a aucun effet avec git.commit).
  • Si vous omettez le bloc git:, l’arborescence de travail est package sous forme d’archive tar simple, y compris les modifications non validées.

Paramètres personnalisés

Transmis à la charge de travail via HYPERPARAMETERS_PATH:

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

Nom de l’exécution MLflow

YAML
mlflow_run_name: 'experiment-001-baseline'

Emplacement des artefacts MLflow

Définissez mlflow_artifact_location pour stocker des artefacts pour une Experimentation MLflow dans un emplacement racine personnalisé. Si vous omettez ce champ, une nouvelle expérimentation utilise l’emplacement DBFS default, tel que dbfs:/databricks/mlflow-tracking/<experiment-id>/....

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

Si l'accès à DBFS est restreint ou si vous préférez Unity Catalog, spécifiez un chemin /Volumes/<catalog>/<schema>/<volume>/... ou l'URI dbfs:/Volumes/<catalog>/<schema>/<volume>/... équivalent. La CLI air convertit un chemin /Volumes en l'URI dbfs: utilisée par MLflow.

Utilisez un emplacement unique pour chaque expérience. L'emplacement de l'artefact d'une Experimentation MLflow est fixe lors de sa création. Si experiment_name identifie une Experimentation existante, mlflow_artifact_location doit correspondre à son emplacement d'artefact ou être omis. Pour utiliser un emplacement différent, spécifiez un nouveau nom d'expérience.

Résolution du chemin​

Tous les chemins dans le YAML de workload sont relatifs au YAML de workload, sauf s'il s'agit de chemins absolus.

Structure des dossiers :

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

Configuration YAML :

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
Sur cette page