İş yükü YAML başvurusu

Important

Bu özellik Genel Önizleme aşamasındadır.

öğesine geçirdiğiniz air run --fileiş yükü YAML yapılandırmasında bir eğitim işinin deneme adını, işlemini, komutunu, ortamını ve kod kaynağını tanımlayın. Bu sayfa her alanı belgelemektedir.

Note

YAML yapılandırması için temel gerçek, CLI içi yardımdır. En üst düzey görünümde ve air -h config (örneğin, air -h config.<section>) bölüm başına ayrıntı için komutunu çalıştırınair -h config.environment.

En az yapılandırma

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

Şu şekilde gönder:

air run --file train.yaml -p profile

Temel kavramlar

Çekirdek alanlar

Çoğu eğitim yapılandırması beş bileşenden oluşur:

  1. experiment_name (Zorunlu): Bir MLflow deneyi oluşturur veya ekler.
  2. environment(İsteğe bağlı): Python bağımlılıkları ve temel ortam sürümü.
  3. compute (Gerekli): GPU kaynakları (tip ve sayı).
  4. command (Gerekli): Eğitimi başlatmak için kullanılan basma komutu veya komutlar.
  5. code_source (Isteğe bağlı): Uzaktan erişilebilir eğitim koduna giden yol.

Desteklenen değerler ve alan kısıtlamaları için bkz. Referans.

İlk eğitim işiniz

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

Bu yapılandırmada:

  • experiment_name adlı simple-training bir MLflow denemesi oluşturur (veya zaten varsa yeni bir çalıştırma ekler).
  • environmentVarsayılan ortamı kullanır ve ve ve transformerskurulurtorch.
  • compute bir H100 düğümü (8 H100 GPU) ayırır.
  • code_source klasörü repo konumunda bulunan $CODE_SOURCE_PATHdüğüme yükler.
  • command8 H100 GPU üzerinden train.py çalışırtorchrun. Dosya yerel olarak bulunur /home/username/repo/train.py .

Yaygın kullanım örnekleri

Ortam değişkenleri ekleme

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

Gizli dizileri kullanma (API anahtarları, belirteçler)

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

Gizli diziler biçimini scope/key kullanır ve Databricks Gizli Dizileri'nde yapılandırılmalıdır. Bkz. Kurulum için gizli dizi yönetimi .

Bir YAML şablonunu paylaşırken, diğer kullanıcıların kendi gizli dizilerini oluşturması veya başvuruda bulunan gizli diziye erişmesi gerekir.

Environment

Bloğu environment kullanarak Sunucusuz GPU ortamı seçin ve Python bağımlılıklarını kurun. Örneğin, aşağıdaki yapılandırma Standard ortam sürüm 4'ü seçer ve PyTorch ile Transformers'ı yükler:

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

Ortam sürümü

environment.version isteğe bağlıdır ve iş yükü için yönetilen ortam sürümünü seçer.

Örnekler şunları içerir:

  • "4" veya "5" ilgili Standard ortam versiyonunu kullanmak gerekir.
  • "databricks_ai_v5" Databricks AI ortamı sürüm 5'i kullanmak için, bu sürüm önceden yüklenmiş ML'ye özgü paketleri içerir. (Tam paket listesi)

Aşağıdaki örnek, Databricks AI ortam sürüm 5'i seçer:

environment:
  version: 'databricks_ai_v5'
  dependencies: []

Eğer belirtirseniz environment.version, ayrıca satır içi liste olarak da sunmalısınız environment.dependencies . Ek paket yüklemenize gerek yoksa, boş bir liste kullanın.

AI Çalışma Zamanı için mevcut ortamlar hakkında bilgi için bkz. Ortamınızı kurun.

Python bağımlılıkları

İş yükünüzün Python bağımlılıklarını satır içi liste olarak listeleyin.environment.dependencies

Bağımlılık formatı

Bağımlılık listesi Databricks Temel Ortam Belirtimini izler. Her giriş bir pip stili paket belirtimidir (örneğin, my-library==6.1). Liste aşağıdaki girdileri de kabul eder:

  • Gereksinimler dosyaları: kullanarak requirements.txtvar olan -r bir başvuru, örneğin-r '/Workspace/Shared/requirements.txt'. gibi $HOME ortam değişkenleri genişletilir.
  • Tekerlekler: bir dosyanın mutlak yolu .whl , örneğin /Workspace/Shared/path/to/simplejson-3.19.3-py3-none-any.whl.
  • Dizin URL'leri: dizin URL'si, örneğin --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

Desteklenen kurulum bayrakları

Bağımlılıklar uv ile yüklenir. Aşağıdaki pip stili bayraklar liste girdileri olarak desteklenir:

  • Yüklemenin tamamına uygulanır: --index-url, --extra-index-url, ve --find-links (-f) paket dizinlerini ayarlayın veya genişletin.
  • Aşağıdaki bağımlılıklara uygulanır: --no-deps, --no-build-isolation, --no-cache-dirve --force-reinstall. Bayrağı kendi satırına (veya belirtimden önce) ve ardından uygulandığı bağımlılığı yerleştirin.

Örneğin, zaten yüklü flash-attn (derleme yalıtımı olmadan) ve kendi bağımlılıklarını çözmeden yüklemek torch için:

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

Note

--trusted-host desteklenmez. uv dizin URL'si başına güveni yapılandırdığından veya --index-url kullanın--extra-index-url.

Özel Docker görüntüleri

seçeneğine environment.dependenciesalternatif olarak, kullanarak environment.docker_image.urlözel bir Docker kapsayıcı görüntüsü belirtebilirsiniz. environment.docker_image.url hem hem de environment.dependenciesenvironment.version ile birbirini dışlar; ikisini de aynı iş yükünde kullanamazsınız.

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

Özel görüntü kullanmadan önce ile air register imagekaydedin. Görüntü gereksinimleri, Databricks temel görüntüleri ve Dockerfile desenleri gibi tüm ayrıntılar için bkz. Özel Docker görüntüleri kullanma.

Kod kaynaklarıyla çalışma

Blok, code_source eğitim işinin çalıştırabilmesi için yerel kodu karşıya yükler.

  • root_path anlık görüntü için yerel dizindir. Varsayılan olarak, air çalışma ağacını as-is (kaydedilmemiş değişiklikler dahil) düz tarball olarak paketler.
  • Bunun yerine sabitlenmiş git sürümünün anlık görüntüsünü almak için veya git:ile branch bir commit blok ekleyin. Bunun bir git deposu olması gerekir root_path ve sürüme duyarlı anlık görüntü oluşturmayı (önbelleğe alma, git archive) etkinleştirir.
  • Büyük depolar için bir include_paths alt kümenin anlık görüntüsünü almanızı sağlar.

En küçük örnek

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

Uzak makinede kod konumuna yerleştirilir /databricks/code_source/<directory_name>; burada <directory_name> son yol bileşenidir root_path. $CODE_SOURCE_PATH bu mutlak yola ayarlanır, bu nedenle konumu sabit kodlamak yerine komutunuzda kullanın.

Git depoları: dal veya işlemeye göre sabitleme

Git depoları için kod sürümünü dal veya işleme SHA'sı ile sabitlemek için bir git: blok ekleyin. branch ve commit birbirini dışlar: blok içinde tam olarak bir tane belirtin.

Bir dala sabitleyin (bu dalın yerel HEAD'ini kullanır):

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

İşleme SHA'sına sabitle (tam yeniden üretilebilirlik):

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

Anahtar alanları:

  • root_path (Gerekli): Git deponuzun kökünün yerel yolu.
  • git.branch (İsteğe bağlı): Dal adı. Yerel HEAD kullanır; uzaktan getirme yok. git.commit ile birbirini dışlar.
  • git.commit (İsteğe bağlı): Belirli işleme SHA'sı. git.branch ile birbirini dışlar.
  • git.remote (İsteğe bağlı): Yerel olan yerine dalın uzak HEAD'ini kullanın. Uzak öğeyi otomatik olarak algılamak true için olarak veya belirli bir uzak bilgisayardan getirmek için uzak bir ada (örneğin, upstream) ayarlayın. Yalnızca ile git.branchgeçerlidir.

Bloğu atlarsanız git: , air iş ağacını, kaydedilmemiş değişiklikler de dahil olmak üzere düz bir tarball olarak paketler. Ek alan gerekmez.

Git dışı dizinler

Git depoları olmayan anlık görüntü dizinleri oluşturabilirsiniz. Git deposu olmasını gerektiren git: bloğu atlaroot_path. Bu olmadan, sürüm önbelleğe alma yoktur; Her çalıştırma için yeni bir tarball yüklenir.

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

ile klasör filtreleme include_paths

Büyük monorepolar için, karşıya yükleme ve indirme süresini ve anlık görüntü boyutunu azaltmak için anlık görüntü yalnızca belirli klasörler:

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

Önemli noktalar:

  • Alan isteğe bağlıdır. Atlanırsa, deponun tamamı varsayılan olarak eklenir.
  • Yollar depo köküne göre olmalıdır (başta /değil).
  • .. izin verilmiyor; üst dizinlere başvuramazsınız.

Gelişmiş özellikler

Özel hiper parametreler

ile yapılandırılmış yapılandırmayı eğitim betiğinize geçirin 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

Bunları betiğinizde okuyun:

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

İş güvenilirliği

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

İş yükü başarısız olursa iki kez yeniden denenir. Her denemenin tamamlanması 90 dakika olduğundan toplam duvar saati bütçesi 90 × 3 = 270 dakika olur.

Maliyet atfı

aracılığıyla usage_policy_namemevcut bir bütçe ilkesine iş yükü ekleme. İş yükü başlatıldığında ad ilkenin kimliğine çözümlenir. Kurulum için bkz . Sunucusuz kullanım ilkeleriyle öznitelik kullanımı.

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

Çekirdek alan referansı

Alan Türü Description Example
experiment_name String MLflow için deneme adı. "my-training-job"
mlflow_artifact_location String Çalıştırma tarafından kaydedilen MLflow artefaktlarının kök konumu. Optional. /Volumes/main/default/mlflow-artifacts/my-training
environment.dependencies liste Pip bağımlılığı belirtimlerinin satır içi listesi. ["torch", "transformers"]
environment.version String Sunucusuz GPU ortamı sürümü. Optional. Eğer hariç tutulursa varsayılan ortamı kullanır. Çevre versiyonuna bakınız. "4", "5", "databricks_ai_v5"
compute.num_accelerators int GPU sayısı. Seçilen compute.accelerator_typedüğüm için GPU'ların katı olmalı. 1, 4, 8
compute.accelerator_type String GPU tipi ve düğüm şekli dahil hızlayıcı konfigürasyonu. Desteklenen GPU yapılandırmalarına bakınız. "GPU_1xA10", "GPU_1xH100", "GPU_8xH100"
code_source dict Kod kaynağı yapılandırması. Bkz . Kod kaynaklarıyla çalışma.
command String Eğitimi başlatmak için Bash komutları. torchrun --nproc_per_node=8 train.py

Desteklenen GPU yapılandırmaları

accelerator_type Düğüm başına GPU sayısı num_accelerators Gereksinim Notlar
GPU_1xA10 1 Herhangi bir pozitif tam sayı Tek A10, geliştirme ve küçük iş yükleri için uygundur.
GPU_1xH100 1 1 Tek H100.
GPU_8xH100 8 8'in pozitif katı Dağıtılmış eğitim için tipik olan tam H100 düğümü.

Hızlandırıcı yetenekleri ve önerilen kullanım senaryoları için Donanım seçenekleri bölümüne bakınız.

compute.num_accelerators iş yükü için toplam GPU sayısıdır. Seçilen compute.accelerator_typeiçin her düğüm için GPU'ların katı olmalı.

İsteğe bağlı alanlar

Ortam yapılandırması

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

Ortam sürümleri, bağımlılık formatı ve desteklenen kurulum bayrakları için Çevre'ye bakınız.

Özel Docker görüntü yapılandırması

environment:
  docker_image:
    url: myorg/myrepo:mytag

ve environment.dependenciesile environment.version birbirini dışlar. Kullanmadan önce görüntüsünü ile air register image kaydedin. Bkz. Özel Docker görüntülerini kullanma.

Kod kaynağı yapılandırması

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/

Alan kısıtlamaları:

  • git.branch ve git.commit birbirini dışlar: blok içinde git: tam olarak bir tane belirtin.
  • git.remote git.branch gerektirir (ile git.commithiçbir etkisi yoktur).
  • Bloğu atlarsanız git: , çalışma ağacı, kaydedilmemiş değişiklikler de dahil olmak üzere düz bir tarball olarak paketlenmiş olur.

Özel parametreler

aracılığıyla HYPERPARAMETERS_PATHiş yüküne geçirilir:

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

MLflow çalıştırma adı

mlflow_run_name: 'experiment-001-baseline'

MLflow artefakt konumu

MLflow deneyi için eserleri özel bir kök konumunda depolamak için ayarlandı mlflow_artifact_location . Bu alanı atlarsanız, yeni bir deney varsayılan DBFS konumunu kullanır, örneğin dbfs:/databricks/mlflow-tracking/<experiment-id>/....

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

DBFS erişimi kısıtlıysa veya Unity Catalog'u tercih ediyorsanız, ya bir /Volumes/<catalog>/<schema>/<volume>/... yol ya da eşdeğer dbfs:/Volumes/<catalog>/<schema>/<volume>/... URI'yi belirtin. CLI, air MLflow'un kullandığı bir /Volumes yolu dbfs: URI'ye dönüştürür.

Her deneye özgü bir konum kullanın. Bir MLflow deneyinin artefakt konumu, deney oluşturulduğunda sabitlenir. Mevcut experiment_name bir deney tespit edilirse, mlflow_artifact_location onun eser konumuyla eşleşmeli veya çıkarılmalıdır. Farklı bir konum kullanmak için yeni bir deney adı belirtin.

Yol çözünürlüğü

İş yükü YAML'deki tüm yollar, mutlak yollar olmadığı sürece iş yükü YAML'sine göredir.

Klasör yapısı:

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

YAML yapılandırması:

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