Dokumentacja YAML obciążenia

Ważna

Ta funkcja jest dostępna w publicznej wersji testowej.

Zdefiniuj nazwę eksperymentu zadania szkoleniowego, obliczenia, polecenie, środowisko i źródło kodu w konfiguracji YAML obciążenia przekazanej do air run --fileelementu . Ta strona dokumentuje każde pole.

Note

Podstawą konfiguracji YAML jest pomoc w interfejsie wiersza polecenia. Uruchom polecenie air -h config , aby wyświetlić widok najwyższego poziomu i air -h config.<section> (na przykład air -h config.environment) dla szczegółów poszczególnych sekcji.

Minimalna konfiguracja

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

Prześlij za pomocą:

air run --file train.yaml -p profile

Podstawowe pojęcia

Podstawowe pola

Większość konfiguracji trenowania obejmuje pięć składników:

  1. experiment_name (Wymagany): Tworzy lub dodaje do eksperymentu MLflow.
  2. environment(Opcjonalnie): zależności Python i wersja środowiska podstawowego.
  3. compute (Wymagane): zasoby GPU (typ i liczba).
  4. command (Wymagane): komenda uderzenia lub komendy używane do rozpoczęcia szkolenia.
  5. code_source (Opcjonalnie): Ścieżka do twojego kodu treningowego, udostępniona zdalnie.

Aby uzyskać wartości wspierane i ograniczenia pól, zobacz Referencja.

Pierwsze zadanie szkoleniowe

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

W tej konfiguracji:

  • experiment_name Tworzy eksperyment MLflow o nazwie simple-training (lub dołącza nowy przebieg, jeśli już istnieje).
  • environmentużywa domyślnego środowiska i instaluje torch oraz .transformers
  • compute przydziela jeden węzeł H100 (8 H100 GPU).
  • code_source przekazuje folder repo do węzła dostępnego pod adresem $CODE_SOURCE_PATH.
  • command działa train.py przez torchrun 8 procesorów GPU H100. Plik znajduje się lokalnie /home/username/repo/train.py .

Typowe przypadki użycia

Dodawanie zmiennych środowiskowych

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

Używanie wpisów tajnych (kluczy interfejsu API, tokenów)

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

Wpisy tajne używają formatu scope/key i muszą być skonfigurowane w wpisach tajnych usługi Databricks. Zobacz Zarządzanie wpisami tajnymi w celu skonfigurowania.

Podczas udostępniania szablonu YAML inni użytkownicy muszą utworzyć własne wpisy tajne lub mieć dostęp do przywoływanego wpisu tajnego.

Environment

Użyj blokuenvironment, aby wybrać środowisko GPU bez serwera i zainstalować zależności Python. Na przykład następująca konfiguracja wybiera środowisko standardowe w wersji 4 i instaluje PyTorch oraz Transformers:

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

Wersja środowiska

environment.version jest opcjonalne i wybiera wersję środowiska zarządzanego dla danego obciążenia.

Oto kilka przykładów:

  • "4" lub "5" używa odpowiedniej wersji środowiska Standardowego.
  • "databricks_ai_v5" aby korzystać z środowiska AI Databricks w wersji 5, które zawiera preinstalowane pakiety specyficzne dla ML. (Pełna lista pakietów)

Poniższy przykład wybiera środowisko AI Databricks w wersji 5:

environment:
  version: 'databricks_ai_v5'
  dependencies: []

Jeśli określisz environment.version, musisz również podać environment.dependencies jako listę inline. Używaj pustej listy, jeśli nie musisz instalować dodatkowych pakietów.

Aby uzyskać informacje o środowiskach dostępnych dla AI Runtime, zobacz: Skonfiguruj swoje środowisko.

Python zależności

Wypisz zależności Python swojego obciążenia jako listę inline pod .environment.dependencies

Format zależności

Lista zależności jest zgodna ze specyfikacją środowiska podstawowego usługi Databricks. Każdy wpis jest specyfikacją pakietu w stylu pip (na przykład my-library==6.1). Lista akceptuje również następujące wpisy:

  • Pliki wymagań: odwołanie do istniejącego requirements.txt przy użyciu -rmetody , na przykład -r '/Workspace/Shared/requirements.txt'. Zmienne środowiskowe, takie jak $HOME , są rozwinięte.
  • Koła: ścieżka bezwzględna do .whl pliku, na przykład /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl.
  • Adresy URL indeksu: adres URL indeksu, na przykład --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

Obsługiwane flagi instalacyjne

Zależności są instalowane z uv. Następujące flagi w stylu pip są obsługiwane jako wpisy listy:

  • Zastosowano do całej instalacji: --index-url, --extra-index-urli --find-links (-f) ustaw lub rozszerz indeksy pakietów.
  • Zastosowano do zależności, która jest zgodna z nimi: --no-deps, , --no-build-isolation--no-cache-diri --force-reinstall. Umieść flagę na własnym wierszu (lub przed specyfikacją), a następnie zależność, której dotyczy.

Na przykład aby zainstalować program flash-attn na już zainstalowanym torch (bez izolacji kompilacji) i bez rozpoznawania własnych zależności:

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

Note

--trusted-host nie jest obsługiwana. Ponieważ uv konfiguruje zaufanie na adres URL indeksu, użyj polecenia --index-url lub --extra-index-url zamiast tego.

Niestandardowe obrazy platformy Docker

Alternatywą dla environment.dependenciesprogramu jest określenie niestandardowego obrazu kontenera platformy Docker przy użyciu polecenia environment.docker_image.url. environment.docker_image.url wzajemnie wyklucza się z obu environment.dependencies tych elementów i environment.version — nie można ich używać w tym samym obciążeniu.

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

Przed użyciem obrazu niestandardowego zarejestruj go w air register imagepliku . Aby uzyskać szczegółowe informacje, w tym wymagania dotyczące obrazów, obrazy podstawowe usługi Databricks i wzorce plików Dockerfile, zobacz Używanie niestandardowych obrazów platformy Docker.

Praca ze źródłami kodu

Blok code_source przekazuje kod lokalny, aby można było go uruchomić.

  • root_path to katalog lokalny do migawki. Domyślnie air pakuje drzewo robocze as-is (w tym wszelkie niezatwierdzone zmiany) jako zwykły tarball.
  • Aby utworzyć migawkę przypiętej wersji git, dodaj git: blok za pomocą elementu branch lub commit. root_path Wymaga to repozytorium Git i umożliwia tworzenie migawek obsługujących wersje (buforowanie, git archive).
  • W przypadku dużych repozytoriów include_paths można utworzyć migawkę podzestawu.

Minimalny przykład

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

Na maszynie zdalnej kod jest umieszczany w /databricks/code_source/<directory_name>lokalizacji , gdzie <directory_name> jest ostatnim składnikiem ścieżki .root_path $CODE_SOURCE_PATH jest ustawiona na ścieżkę bezwzględną, więc użyj jej w poleceniu, a nie na stałe kodowania lokalizacji.

Repozytoria Git: przypinanie według gałęzi lub zatwierdzenia

W przypadku repozytoriów git dodaj blok, aby przypiąć git: wersję kodu według gałęzi lub zatwierdź sha. branch i commit wykluczają się wzajemnie: określ dokładnie jedną w bloku.

Przypnij do gałęzi (używa lokalnej gałęzi HEAD tej gałęzi):

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

Przypnij do zatwierdzenia SHA (dokładna powtarzalność):

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

Pola klucza:

  • root_path (Wymagane): ścieżka lokalna do katalogu głównego repozytorium Git.
  • git.branch (Opcjonalnie): Nazwa gałęzi. Używa lokalnej funkcji HEAD; brak zdalnego pobierania. Wzajemnie wykluczające się z git.commit.
  • git.commit (Opcjonalnie): określone zatwierdzenie SHA. Wzajemnie wykluczające się z git.branch.
  • git.remote (Opcjonalnie): użyj zdalnej gałęzi HEAD zamiast lokalnej. Ustaw wartość na wartość w celu true automatycznego wykrywania zdalnego lub nazwy zdalnej (na przykład upstream) w celu pobrania z określonego zdalnego. Tylko prawidłowe z git.branch.

Jeśli pominięto git: blok, air pakuje drzewo robocze jako zwykły tarball, w tym wszelkie niezatwierdzone zmiany. Nie jest wymagane żadne dodatkowe pole.

Katalogi inne niż git

Możesz migawek katalogów, które nie są repozytoriami git. Pomiń git: blok, który wymaga root_path repozytorium git. Bez niego nie ma buforowania wersji; świeży tarball jest przekazywany na każdy bieg.

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

Filtrowanie folderów za pomocą polecenia include_paths

W przypadku dużych monorepos migawki tylko określone foldery zmniejszają czas przekazywania i pobierania oraz rozmiar migawki:

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

Najważniejsze kwestie:

  • Pole jest opcjonalne. Jeśli pominięto, całe repozytorium jest domyślnie dołączane.
  • Ścieżki muszą być względne względem katalogu głównego repozytorium (brak wiodącego /elementu ).
  • .. jest niedozwolona; nie można odwoływać się do katalogów nadrzędnych.

Zaawansowane funkcje

Niestandardowe hiperparametry

Przekaż konfigurację ustrukturyzowaną do skryptu szkoleniowego za pomocą polecenia 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

Przeczytaj je w skrycie:

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

Niezawodność zadania

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

Jeśli obciążenie zakończy się niepowodzeniem, zostanie ono ponowione dwukrotnie. Każda próba ma 90 minut do ukończenia, więc całkowity budżet zegara ściany wynosi 90 × 3 = 270 minut.

Przypisywanie kosztów

Dołącz obciążenie do istniejących zasad budżetu za pomocą polecenia usage_policy_name. Nazwa jest rozpoznawana jako identyfikator zasad podczas uruchamiania obciążenia. Aby uzyskać informacje na temat konfiguracji, zobacz Użycie atrybutów z zasadami użycia bezserwerowego.

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

Podstawowe odniesienie terenowe

Pole Typ Description Example
experiment_name ciąg Nazwa eksperymentu dla biblioteki MLflow. "my-training-job"
mlflow_artifact_location ciąg Lokalizacja roota artefaktów MLflow rejestrowanych przez uruchomienie. Optional. /Volumes/main/default/mlflow-artifacts/my-training
environment.dependencies list Wbudowana lista specyfikacji zależności pip. ["torch", "transformers"]
environment.version ciąg Wersja środowiska bezserwerowego procesora GPU. Optional. Używa domyślnego środowiska, jeśli zostanie pominięty. Zobacz wersję środowiskową. "4", , "5""databricks_ai_v5"
compute.num_accelerators int Liczba procesorów graficznych. Musi być wielokrotnością GPU na każdy węzeł dla wybranego compute.accelerator_type. 1, , 48
compute.accelerator_type ciąg Konfiguracja akceleratora, w tym typ GPU i kształt węzła. Zobacz Obsługiwane konfiguracje GPU. "GPU_1xA10", , "GPU_1xH100""GPU_8xH100"
code_source dict Konfiguracja źródła kodu. Zobacz Praca ze źródłami kodu.
command ciąg Polecenia powłoki Bash służące do uruchamiania szkolenia. torchrun --nproc_per_node=8 train.py

Obsługiwane konfiguracje GPU

accelerator_type Liczba GPU na węzeł num_accelerators Wymóg Notatki
GPU_1xA10 1 Dowolna dodatnia liczba całkowita Pojedynczy A10, dobry dla programowania i małych obciążeń.
GPU_1xH100 1 1 Pojedynczy H100.
GPU_8xH100 8 Dodatnia wielokrotność 8 Pełny węzeł H100, typowy dla trenowania rozproszonego.

Aby zapoznać się z możliwościami akceleratora i zalecanymi przypadkami użycia, zobacz Opcje sprzętu.

compute.num_accelerators to całkowita liczba GPU dla obciążenia. Musi to być wielokrotność GPU na każdy węzeł dla wybranego compute.accelerator_type.

Pola opcjonalne

Konfiguracja środowiska

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

Aby poznać wersje środowiska, format zależności oraz wspierane flagi instalacyjne, zobacz Środowisko.

Niestandardowa konfiguracja obrazu platformy Docker

environment:
  docker_image:
    url: myorg/myrepo:mytag

Wzajemnie wykluczające się z i environment.dependenciesenvironment.version. Zarejestruj obraz air register image przed użyciem. Zobacz Używanie niestandardowych obrazów platformy Docker.

Konfiguracja źródła kodu

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/

Ograniczenia pól:

  • git.branch i git.commit wykluczają się wzajemnie: określ dokładnie jedną w git: bloku.
  • git.remote wymaga git.branch (nie ma wpływu na git.commitwartość ).
  • Jeśli pominięto git: blok, drzewo robocze jest pakowane jako zwykły tarball, w tym wszelkie niezatwierdzone zmiany.

Parametry niestandardowe

Przekazano do obciążenia za pośrednictwem polecenia HYPERPARAMETERS_PATH:

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

Nazwa przebiegu platformy MLflow

mlflow_run_name: 'experiment-001-baseline'

Lokalizacja artefaktu MLflow

Ustaw mlflow_artifact_location przechowywanie artefaktów dla eksperymentu MLflow w niestandardowej lokalizacji root. Jeśli pominiesz to pole, nowy eksperyment używa domyślnej lokalizacji DBFS, takiej jak dbfs:/databricks/mlflow-tracking/<experiment-id>/....

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

Jeśli dostęp do DBFS jest ograniczony lub wolisz Unity Catalog, określ ścieżkę /Volumes/<catalog>/<schema>/<volume>/... lub dbfs:/Volumes/<catalog>/<schema>/<volume>/... odpowiedni URI. CLI konwertuje air ścieżkę /Volumes do dbfs: URI, którą używa MLflow.

Użyj lokalizacji unikalnej dla każdego eksperymentu. Lokalizacja artefaktu eksperymentu MLflow jest ustalona w momencie jego tworzenia. Jeśli identyfikuje experiment_name istniejący eksperyment mlflow_artifact_location , musi odpowiadać lokalizacji artefaktu lub zostać pominięty. Aby użyć innej lokalizacji, podaj nową nazwę eksperymentu.

Rozdzielczość ścieżki

Wszystkie ścieżki w obciążeniu YAML są względem obciążenia YAML, chyba że są to ścieżki bezwzględne.

Struktura folderów:

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

Konfiguracja 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