Özel Docker görüntüleri kullanma

Önemli

Bu özellik Beta sürümündedir. Sunucusuz çıkış kontrolü (SEG) kullanan çalışma alanlarıyla uyumlu değildir.

Docker Container Services (DCS), kendi Docker konteyner görüntünüzü air iş yüklerinize getirmenize olanak tanır. İhtiyaç duyduğunuzda özel görüntü kullanın:

• Belirli sistem kitaplığı sürümleri.
• environment.dependencies içine tam olarak oturmayan karmaşık bağımlılıklar.
• Araştırma sonuçlarını yeniden oluşturmak için tam bir ortam.
• Kuruluşunuzun platformu veya güvenlik ekibi tarafından oluşturulan standart görüntüler.

Prerequisites

• AI Runtime CLI'sını yükleyin.
• Özel görüntüler için, resminize erişimi olan bir Docker Hub hesabı.

Görüntü kaydetme

Özel bir imajla bir iş yükü çalıştırmadan önce, iş yükünü air register image ile kaydedin. Kayıt işlemi, görüntüyü Databricks platformunda alır ve önbelleğe kaydeder. Her kullanıcının görüntü etiketi başına bir kez resim kaydetmesi gerekir. Yalnızca yeni bir etiketi gönderdiğinizde veya kimlik bilgilerini yenilediğinizde yeniden kaydedin. Kayıt 2–6 dakika sürer ve görüntü hazır olana kadar bekler.

Genel görüntüler

Docker imaj URL’sini ve Databricks profilinizi belirterek herkese açık imajları kaydedin:

air register image docker.io/nvidia/cuda:12.9.0-devel-ubuntu24.04 -p my-databricks-profile

Kısa biçimli görüntü referansı da çalışır. Örneğin, library/ubuntu:latest.

Özel Docker Hub görüntüleri

Özel Docker Hub görüntüsünü kaydetmek için önce kişisel erişim belirteci oluşturun. Docker Hub hesap ayarlarınızda Kişisel erişim belirteçleri → Yeni belirteç oluştur'a tıklayın. Yalnızca okuma erişimi yeterlidir.

Aşağıdaki kimlik doğrulama yöntemlerinden birini seçin:

Docker oturum açma bilgilerini kullanma (etkileşimli kullanım için önerilir)

Terminalde Docker Hub oturum açın. Docker Hub kullanıcı adınız ve kişisel erişim belirteciniz istenir:

docker login

Bu, kimlik bilgilerinizi içinde ~/.docker/config.jsondepolar. Ardından görüntüyü kaydedin; air kimlik bilgilerini otomatik olarak okur:

air register image myorg/myrepo:mytag -p my-databricks-profile

Etkileşimli kimlik doğrulamasını kullanma

Kimlik bilgilerini bir Databricks gizli dizi kapsamında tek adımda doğrulayın ve depolayın:

air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile

Docker Hub kullanıcı adınız ve kişisel erişim belirteciniz istenir. Kimlik bilgileri, ileride yapılacak kayıt işlemleri için çalışma alanınızdaki gizli kapsamda saklanır.

Önceden kaydedilmiş bir Databricks gizli anahtarını kullanma (CI/betikler için önerilir)

Kimlik bilgilerini bir Databricks gizli anahtarında depolayın ve doğrudan buna referans verin:

air register image myorg/myrepo:mytag --scope my-secret-scope --key my-docker-key -p my-databricks-profile

İş yükünde Docker görüntüsü kullanma

İş yükü YAML dosyanızda, environment.docker_image.url altında Docker imajını belirtin:

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

Kendi Docker imajınızı kullandığınızda, environment.dependencies ve environment.version desteklenmez. environment.docker_image.url öğesinin iki alandan herhangi biriyle belirtilmesi hataya neden olur. Ek bağımlılıklarınız varsa bunun yerine paketleri Dockerfile dosyasına yükleyin.

İş yükünü gönderin:

air run --file workload.yaml -p my-databricks-profile

Kapsayıcınıza eklenen ortam değişkenleri

AI Runtime, çalışma zamanında her kapsayıcıya aşağıdaki ortam değişkenlerini ekler:

• NUM_NODES — toplam düğüm sayısı.
• LOCAL_WORLD_SIZE — Düğüm başına GPU sayısı.
• WORLD_SIZE — toplam işlem sayısı.
• POD_RANK — geçerli düğüm sıralaması (0 dizinli). Ayrıca NODE_RANK olarak eklendi.
• LOCAL_ADDR — yerel düğümün IP adresi (yalnızca çok düğümlü kurulumlarda).
• MASTER_ADDR — derece-0 koordinasyon adresi (yalnızca çok düğümlü).
• MASTER_PORT — rank-0 eşgüdüm bağlantı noktası (yalnızca çok düğümlü yapılandırmalarda).

Examples

Tek düğümlü A10

experiment_name: my-dcs-single-node
environment:
  docker_image:
    url: myorg/myrepo:mytag
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
command: python3 /app/train.py

RDMA ile çok düğümlü H100

AWS p5 örneklerinde tam ağ bant genişliği gerektiren çok düğümlü H100 işleri için görüntünüzü önceden yapılandırılmış NCCL ve EFA ile Databricks temel görüntülerinden birine dayandırın:

experiment_name: my-dcs-distributed
environment:
  docker_image:
    url: myorg/myrepo:mytag
compute:
  num_accelerators: 16 # 2 nodes × 8 H100
  accelerator_type: GPU_8xH100
command: |-
  torchrun \
    --nnodes="${NUM_NODES}" \
    --nproc_per_node="${LOCAL_WORLD_SIZE}" \
    --node_rank="${POD_RANK}" \
    --rdzv_endpoint="${MASTER_ADDR}:${MASTER_PORT}" \
    /app/train.py

Kendi görüntünüzü oluşturma

Databricks, kendi imajınızı oluştururken bir kodlama aracısıyla databricks-ai-runtime becerisini kullanmanızı veya bir Databricks temel imajından başlamanızı önerir.

Kodlama aracısı kullanma

Sıfırdan oluşturma, CUDA/NCCL/EFA uyumluluğu, yaygın sorunlar ve derleme öncesi denetim listesi de dahil olmak üzere adım adım Dockerfile kılavuzu için databricks-ai-runtime Claude Code becerisini yükleyin. Bu beceri için Databricks CLI sürüm 1.0.0 veya üzeri gerekir.

databricks aitools install --skills databricks-ai-runtime --experimental

Databricks temel görüntüleri

Databricks, databricksruntime/air adresindeki Docker Hub’da CUDA, NCCL ve buluta özgü ağ yapılandırmaları (AWS EFA veya Azure InfiniBand) önceden yapılandırılmış temel imajlar yayımlar.

Tag	Bulut	Variant	Şu durumlarda kullanın:
dcs-base-aws-runtime	AWS	Runtime	Yalnızca önceden oluşturulmuş tekerlekleri yükleme
dcs-base-aws-devel	AWS	Devel	CUDA uzantılarını derleme (gerektirir nvcc)
dcs-base-azure-runtime	Azure	Runtime	Yalnızca önceden oluşturulmuş tekerlekleri yükleme
dcs-base-azure-devel	Azure	Devel	CUDA uzantılarını derleme (gerektirir nvcc)

Dockerfile'ınız flash-attn, apex veya özel çekirdekler gibi CUDA uzantılarını derlemediği sürece çalışma zamanı değişkenini kullanın.

Databricks temel imajına PyTorch ekleyen örnek Dockerfile. Temel görüntüler, /opt/venv konumunda uv tarafından yönetilen Python sağlar. uv pip install varsayılan olarak bu ortamı hedefler; farklı bir ortam kullanmak için çalıştırmadan önce uv pip installvenv oluşturup etkinleştirin.

FROM databricksruntime/air:dcs-base-aws-runtime

RUN uv pip install --no-cache \
    torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0

RUN uv pip install --no-cache \
    transformers==4.45.0 \
    accelerate==0.34.0 \
    'mlflow>=3.6'

COPY ./train /app/train

Derle, gönder ve kaydet:

docker build -t myorg/myrepo:mytag .
docker push myorg/myrepo:mytag
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile

Requirements

• Görüntülerin Docker Hub üzerinde barındırılması gerekir. Amazon ECR, Google GCR ve GitHub GHCR desteklenmez.
• Görüntü boyutu 20 GB'ın altında olmalıdır.
• WORKDIR çalışma zamanında dikkate alınmaz. İmaja dahil edilen dosyalar için mutlak yollar kullanın. Örneğin, python /app/train.pydeğil python train.pykullanın.
• environment.dependencies ile environment.version veya environment.docker_image.url kullanamazsınız. Görüntüdekilerin ötesinde ek paketlere ihtiyacınız varsa bunları Dockerfile dosyasına eklemeniz gerekir.

Sorun giderme

Ssl. SSLError: Bağımlılıkları yüklerken [CRYPTO] bilinmeyen hata (_ssl.c)

Bir kitaplık SSL bağlamı oluşturmaya çalıştığında özel görüntü çalışma zamanında OpenSSL hatasıyla başarısız olabilir, örneğin:

ssl.SSLError: [CRYPTO] unknown error (_ssl.c:3076)

huggingface_hub gibi ağ bağlantıları kuran kitaplıklar içeri aktarılırken hata oluşur ve bunların yüklenmesini engeller.

Bunun nedeni air iş yüklerinin FIPS özellikli konaklarda çalıştırılmasıdır. Görüntünün şifreleme kitaplıkları FIPS uyumlu olmadığında, OpenSSL FIPS modunda başlatılamaz, bu nedenle SSL bağlamı oluşturma başarısız olur.

Önerilen çözüm:

Kurumsal, kamu, sağlık ve finans iş yükleri genellikle FedRAMP, CMMC veya HIPAA denetimleri için FIPS 140-2 veya 140-3 uyumluluğuna bağlıdır. İş yükünüzün FIPS uyumlu kalması gerekiyorsa görüntünüzü FIPS uyumlu şifreleme kitaplıklarıyla derleyin.

İş yükünüz FIPS uyumluluğu gerektirmiyorsa, ortam değişkenini OPENSSL_FORCE_FIPS_MODE0olarak ayarlayarak FIPS modunu devre dışı bırakabilirsiniz. Bunu yapmak, uyumluluk gereksinimlerini sessizce bozabilir.

FIPS modunu devre dışı bırakmak için, iş yükü YAML dosyanızda env_variables altında bunu ayarlayın:

env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

Alternatif olarak Dockerfile'ınızdaki değişkeni görüntüyü kullanan her iş yükü için geçerli olacak şekilde ayarlayın:

ENV OPENSSL_FORCE_FIPS_MODE=0

İş yükünü yeniden gönderin ve bağımlılıklar yüklendiğinde SSL hatasının artık görünmediğinden emin olun.

Ayrıca bakınız

• AI Runtime CLI Hızlı Başlangıç
• İş yükü YAML başvurusu
• AI Runtime CLI komut referansı