YAML-verwijzing voor workload

Definieer de experimentnaam, berekening, opdracht, omgeving en codebron van een trainingstaak in de YAML-configuratie van de workload die air run --fileu doorgeeft. Op deze pagina wordt elk veld gedocumenten.

Minimale configuratie

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

Verzenden met:

air run --file train.yaml -p profile

Basisconcepten

Kernvelden

De meeste trainingsconfiguraties bevatten vijf onderdelen:

1. experiment_name: Vereist. Hiermee maakt of voegt u een MLflow-experiment toe.
2. environment: optioneel. Python afhankelijkheden en basisomgeving.
3. compute: Vereist. GPU-resources (type en aantal).
4. command: Vereist. De bash-opdracht of -opdrachten die worden gebruikt om training te starten.
5. code_source: optioneel. Pad naar uw trainingscode, op afstand beschikbaar gemaakt.

Uw eerste trainingstaak

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 deze configuratie:

• experiment_name maakt een MLflow-experiment met de naam simple-training (of voegt een nieuwe uitvoering toe als deze al bestaat).
• environmentinstalleert de vermelde Python afhankelijkheden (hier torch en transformers).
• compute wijst één H100-knooppunt toe (8 H100 GPU's).
• code_source uploadt de map repo naar het knooppunt, beschikbaar op $CODE_SOURCE_PATH.
• command wordt uitgevoerd train.py via torchrun de 8 H100 GPU's. Het bestand bevindt zich /home/username/repo/train.py lokaal.

Veelvoorkomende gebruiksvoorbeelden

Omgevingsvariabelen toevoegen

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

Geheimen gebruiken (API-sleutels, tokens)

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

Geheimen gebruiken de indeling scope/key en moeten worden geconfigureerd in Databricks Secrets. Zie Geheimbeheer voor installatie.

Wanneer u een YAML-sjabloon deelt, moeten andere gebruikers hun eigen geheimen maken of toegang hebben tot het geheim waarnaar wordt verwezen.

afhankelijkheden Python

Geef de Python afhankelijkheden van uw workload weer als een inlinelijst onderenvironment.dependencies:

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

environment.version selecteert de versie van de serverloze GPU-omgeving. Het is optioneel en wordt standaard ingesteld op "4".

Afhankelijkheidsindeling

De afhankelijkheidslijst volgt de Databricks Base Environment-specificatie. Elke vermelding is een pip-stijl pakketspecificatie (bijvoorbeeld my-library==6.1). De lijst accepteert ook de volgende vermeldingen:

• Vereistenbestanden: een verwijzing naar een bestaand requirements.txt gebruik -r, bijvoorbeeld -r '/Workspace/Shared/requirements.txt'. Omgevingsvariabelen zoals $HOME uitgevouwen.
• Wielen: een absoluut pad naar een .whl bestand, bijvoorbeeld /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl.
• Index-URL's: bijvoorbeeld een index-URL --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

Ondersteunde installatievlagmen

Afhankelijkheden worden geïnstalleerd met uv. De volgende pip-stijlvlagmen worden ondersteund als lijstvermeldingen:

• Toegepast op de hele installatie: --index-url, --extra-index-urlen --find-links (-f) stel de pakketindexen in of breid ze uit.
• Toegepast op de afhankelijkheid die deze volgt: --no-deps, --no-build-isolation, --no-cache-diren --force-reinstall. Plaats de vlag op een eigen regel (of vóór de specificatie), gevolgd door de afhankelijkheid waarop deze van toepassing is.

Als u bijvoorbeeld wilt installeren flash-attn op basis van de reeds geïnstalleerde torch installatie (geen buildisolatie) en zonder dat u de eigen afhankelijkheden hoeft op te lossen:

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

Aangepaste Docker-installatiekopieën

Als alternatief environment.dependencieskunt u een aangepaste Docker-containerinstallatiekopieën opgeven met behulp van environment.docker_image.url. environment.docker_image.url is wederzijds exclusief met beide environment.dependencies en environment.version : u kunt geen van beide gebruiken in dezelfde workload.

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

Voordat u een aangepaste installatiekopieën gebruikt, moet u deze registreren bij air register image. Zie Aangepaste Docker-installatiekopieën gebruiken voor meer informatie, waaronder vereisten voor installatiekopieën, Databricks-basisinstallatiekopieën en Dockerfile-patronen.

Werken met codebronnen

Het code_source blok uploadt lokale code, zodat de trainingstaak deze kan uitvoeren.

• root_path is de lokale map om een momentopname te maken. air Verpakt standaard de actieve boomstructuur as-is (inclusief eventuele niet-doorgevoerde wijzigingen) als een gewone tarball.
• Als u in plaats daarvan een momentopname wilt maken van een vastgemaakte Git-versie, voegt u een git: blok toe met een branch of commit. Dit moet root_path een Git-opslagplaats zijn en maakt versiebewuste momentopnamen mogelijk (caching, git archive).
• Voor grote opslagplaatsen include_paths kunt u een momentopname maken van een subset.

Minimaal voorbeeld

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

Op de externe computer wordt de code geplaatst op /databricks/code_source/<directory_name>, waar <directory_name> is het laatste padonderdeel van root_path. $CODE_SOURCE_PATH is ingesteld op dat absolute pad, dus gebruik het in uw opdracht in plaats van de locatie hard te coderen.

Git-opslagplaatsen: vastmaken per vertakking of doorvoer

Voor Git-opslagplaatsen voegt u een git: blok toe om de codeversie per vertakking of door sha vast te maken. branch en commit sluiten elkaar wederzijds uit: geef precies één op binnen het blok.

Vastmaken aan een vertakking (gebruikt de lokale HEAD van die vertakking):

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

Vastmaken aan een doorvoer-SHA (exacte reproduceerbaarheid):

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

Sleutelvelden:

• root_path (Vereist): Lokaal pad naar de hoofdmap van uw Git-opslagplaats.
• git.branch (Optioneel): Naam van de vertakking. Maakt gebruik van lokale HEAD; geen externe ophalen. Wederzijds uitsluiten met git.commit.
• git.commit (Optioneel): Specifieke doorvoer-SHA. Wederzijds uitsluiten met git.branch.
• git.remote (Optioneel): Gebruik de externe HEAD van de vertakking in plaats van de lokale. Ingesteld op true automatisch detecteren van de externe locatie of op een externe naam (bijvoorbeeld upstream) om op te halen van een specifieke externe. Alleen geldig met git.branch.

Als u het git: blok weglaat, air verpakt u de werkstructuur als een gewone tarball, inclusief eventuele niet-doorgevoerde wijzigingen. Er is geen extra veld vereist.

Niet-Git-mappen

U kunt momentopnamen maken van mappen die geen Git-opslagplaatsen zijn. Laat het git: blok weg. Dit moet root_path een Git-opslagplaats zijn. Zonder deze is er geen versiecache; voor elke uitvoering wordt een nieuwe tarball geüpload.

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

Mappen filteren met include_paths

Voor grote monoreposen maakt u alleen een momentopname van specifieke mappen om de upload- en downloadtijd en de grootte van momentopnamen te verminderen:

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

Belangrijkste punten:

• Het veld is optioneel. Als u dit weglaat, wordt de hele opslagplaats standaard opgenomen.
• Paden moeten relatief zijn ten opzichte van de hoofdmap van de opslagplaats (geen voorlooppad /).
• .. is niet toegestaan; u kunt niet verwijzen naar bovenliggende mappen.

Geavanceerde functies

Aangepaste hyperparameters

Geef gestructureerde configuratie door aan uw trainingsscript via 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

Lees ze in uw 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']

Betrouwbaarheid van taken

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

Als de workload mislukt, wordt deze twee keer opnieuw geprobeerd. Elke poging heeft 90 minuten om te voltooien, dus het totale budget voor wandklok is 90 × 3 = 270 minuten.

Kostentoeschrijving

Koppel een workload aan een bestaand budgetbeleid via usage_policy_name. De naam wordt omgezet in de id van het beleid wanneer de workload wordt gestart. Zie Kenmerkgebruik met serverloze gebruiksbeleidsregels voor de installatie.

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

Kernvelden

Ondersteunde GPU-typen

Zie Hardwareopties voor meer mogelijkheden en aanbevolen gebruiksvoorbeelden.

Optionele velden

Omgevingsconfiguratie

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

Zie Python afhankelijkheden voor de afhankelijkheidsindeling, ondersteunde installatievlagmen en environment.versionzie Python afhankelijkheden.

Aangepaste Configuratie van Docker-installatiekopieën

environment:
  docker_image:
    url: myorg/myrepo:mytag

Wederzijds uitsluiten met environment.dependencies en environment.version. Registreer de installatiekopieën bij air register image voordat u deze gebruikt. Zie Aangepaste Docker-installatiekopieën gebruiken.

Codebronconfiguratie

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/

Veldbeperkingen:

• git.branch en git.commit sluiten elkaar wederzijds uit: geef precies één op binnen het git: blok.
• git.remote vereist git.branch (het heeft geen effect met git.commit).
• Als u het git: blok weglaat, wordt de werkstructuur verpakt als een gewone tarball, inclusief eventuele niet-doorgevoerde wijzigingen.

Aangepaste parameters

Doorgegeven aan de workload via HYPERPARAMETERS_PATH:

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

Naam van MLflow-uitvoering

mlflow_run_name: 'experiment-001-baseline'

Padomzetting

Alle paden in de YAML van de workload zijn relatief ten opzichte van de YAML van de workload, tenzij ze absolute paden zijn.

Mapstructuur:

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

YAML-configuratie:

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