Eski Python CLI için iş yükü YAML referansı

Important

Bu belge kullanımdan kaldırılmıştır ve güncelleştirilmeyebilir.

air paketiyle yüklenen Python tabanlı databricks-air CLI artık kullanımdan kaldırılmıştır ve artık aktif olarak bakımı yapılmamaktadır.

Yeni iş yükleri için Databricks CLI'sını kullanın. Bkz. Databricks CLI'yı AI Çalışma Zamanı ile Kullanın.

air run --file öğesine ilettiğiniz iş yükü YAML yapılandırmasında bir eğitim işinin deney adını, işlem kaynağını, komutunu, ortamını ve kod kaynağını tanımlayın. Bu sayfa her alanı belgelemektedir.

Uyarı

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

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 mevcut bir MLflow deneyine 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 Bash 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, simple-training adlı bir MLflow denemesi oluşturur (veya zaten varsa yeni bir çalıştırma ekler).
  • environment varsayılan ortamı kullanır ve transformers ile torch yükler.
  • compute 1 H100 düğümü (8 H100 GPU) tahsis eder.
  • code_source klasörü repo konumunda bulunan $CODE_SOURCE_PATHdüğüme yükler.
  • command, 8 H100 GPU’da torchrun aracılığıyla train.py çalıştırır. Dosya yerel olarak /home/username/repo/train.py konumundadır.

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 bilgileri kullanın (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 anahtarlar scope/key biçimindedir ve Databricks Secrets'ta yapılandırılmalıdır. Kurulum için Gizli bilgiler yönetimi bölümüne bakın.

Bir YAML şablonunu paylaşırken, diğer kullanıcılar kendi gizli anahtarlarını oluşturmalı veya başvurulan gizli anahtara erişime sahip olmalıdır.

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

environment.version belirtirseniz, environment.dependencies değerini de satır içi liste olarak sağlamalısınız. 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:

  • Gereksinim dosyaları: örneğin -r '/Workspace/Shared/requirements.txt', -r kullanarak mevcut bir requirements.txt başvurusu. 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, flash-attn paketini zaten yüklü olan torch paketine karşı (derleme yalıtımı olmadan) ve kendi bağımlılıklarını çözümlemeden yüklemek için:

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

Uyarı

--trusted-host desteklenmez. uv, güveni her dizin URL'si için yapılandırdığından, bunun yerine --index-url veya --extra-index-url kullanın.

Ö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 bir imajı kullanmadan önce, air register image ile kaydedin. Tam detaylar için, görüntü gereksinimleri, Databricks temel görüntüleri ve Dockerfile desenleri için bkz. Eski Python Komuta Sistemi ile özel Docker görüntülerini kullanın.

Kod kaynaklarıyla çalışma

code_source bloğu, eğitim işinin bunu çalıştırabilmesi için yerel kodu yükler.

  • root_path anlık görüntü için yerel dizindir. Varsayılan olarak, air çalışma ağacını, kaydedilmemiş değişiklikler dahil, olduğu gibi normal bir tar arşivi olarak paketler.
  • Bunun yerine, sabitlenmiş bir Git sürümünün anlık görüntüsünü almak için branch veya commit içeren bir git: bloğu 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, /databricks/code_source/<directory_name> konumuna yerleştirilir; burada <directory_name>, root_path’nin son yol bileşenidir. $CODE_SOURCE_PATH bu mutlak yola ayarlanır, bu nedenle konumu sabit kodlamak yerine komutunuzda kullanın.

Git depoları: dala veya commit’e göre sabitleme

git depoları için, kod sürümünü dala ya da commit SHA’sına göre sabitlemek üzere bir git: bloğu 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

Bir commit SHA’sına sabitleyin (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 dizinine giden yerel yol.
  • 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 bir commit SHA’sı. git.branch ile birbirini dışlar.
  • git.remote (İsteğe bağlı): Yerel HEAD yerine dalın uzak HEAD'ini kullanın. Uzak depoyu otomatik algılamak için true olarak ya da belirli bir uzak depodan çekmek için bir uzak depo adı (örneğin upstream) olarak ayarlayın. Yalnızca git.branch ile geçerlidir.

git: bloğunu atlarsanız, air çalışma ağacını, işlenmemiş değişiklikler de dahil olmak üzere, normal bir tar arşivi olarak paketler. Ek alan gerekmez.

Git dışı dizinler

Git depoları olmayan anlık görüntü dizinleri oluşturabilirsiniz. root_path öğesinin bir Git deposu olmasını gerektiren git: bloğunu hariç tut. Bu olmadan sürüm önbelleğe alma yapılmaz; her çalıştırmada yeni bir arşiv dosyası yüklenir.

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

include_paths ile klasör filtreleme

Büyük monorepo'larda, karşıya yükleme ve indirme süresini ve anlık görüntü boyutunu azaltmak için yalnızca belirli klasörlerin anlık görüntüsünü alın:

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. Belirtilmezse, deponun tamamı varsayılan olarak dahil edilir.
  • Yollar, depo kök dizinine göreli olmalıdır (başında / olmadan).
  • .. izin verilmiyor; üst dizinlere başvuramazsınız.

Gelişmiş özellikler

Özel hiper parametreler

Yapılandırılmış yapılandırmayı HYPERPARAMETERS_PATH aracılığıyla eğitim betiğinize iletin:

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ı komut dosyanızda 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ı

Bir iş yükünü usage_policy_name aracılığıyla mevcut bir bütçe ilkesine ekleyin. Ad, iş yükü başlatıldığında 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 Type 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ığı tanımlarının 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_type için düğüm başına GPU sayısının katı olmalıdır. 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 Bir adet 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 bkz. Donanım.

compute.num_accelerators iş yükü için toplam GPU sayısıdır. Seçilen compute.accelerator_type için düğüm başına GPU sayısının katı olmalıdır.

İ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üyü air register image ile kaydedin. Eski Python CLI'sı ile özel Docker imgelerini kullan bölümüne bakınız.

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 (git.commit ile hiçbir etkisi yoktur).
  • git: bloğunu atarsanız, çalışma ağacı, kaydedilmemiş değişiklikler de dahil olmak üzere düz bir tar arşivi olarak paketlenir.

Özel parametreler

HYPERPARAMETERS_PATH aracılığıyla iş yüküne iletilir:

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 artefaktları özel bir kök konumunda depolamak üzere mlflow_artifact_location ayarlayın. 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. experiment_name, mevcut bir deneyi tanımlıyorsa, mlflow_artifact_location onun artefakt konumuyla eşleşmeli veya belirtilmemelidir. Farklı bir konum kullanmak için yeni bir deney adı belirtin.

Yol çözümleme

İş 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
  • Son güncelleştirme: