Menggunakan gambar Docker kustom

Important

Fitur ini ada di Beta. Perangkat ini tidak kompatibel dengan workspace yang menggunakan serverless egress control (SEG).

Docker Container Services (DCS) memungkinkan Anda membawa gambar kontainer Docker Anda sendiri ke air beban kerja. Gunakan gambar kustom saat Anda membutuhkan:

Versi pustaka sistem tertentu.
Dependensi kompleks yang tidak dapat dimasukkan dengan rapi ke dalam environment.dependencies.
Lingkungan yang tepat untuk mereproduksi hasil penelitian.
Gambar standar yang dibangun oleh platform organisasi atau tim keamanan Anda.

Prasyarat

Instal AI Runtime CLI.
Untuk gambar privat, akun Docker Hub dengan akses ke gambar Anda.

Mendaftarkan gambar

Sebelum menjalankan beban kerja dengan gambar kustom, daftarkan dengan air register image. Proses pendaftaran mengambil dan menyimpannya di cache pada platform Databricks. Setiap pengguna harus mendaftarkan gambar sekali per tag gambar. Daftar ulang hanya saat Anda mengirim tag baru atau mengganti kredensial. Pendaftaran memerlukan waktu 2–6 menit dan akan tertahan hingga gambar siap.

Gambar publik

Daftarkan gambar publik dengan menyediakan URL gambar Docker dan profil Databricks Anda:

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

Referensi gambar bentuk singkat juga berfungsi. Contohnya, library/ubuntu:latest.

Gambar Docker Hub privat

Untuk mendaftarkan gambar Docker Hub privat, buat token akses pribadi terlebih dahulu. Di pengaturan akun Docker Hub Anda, klik Token akses pribadi → Hasilkan token baru. Akses hanya baca sudah cukup.

Pilih salah satu metode autentikasi berikut:

Masuk ke Docker Hub di terminal. Anda akan dimintai nama pengguna Docker Hub dan token akses pribadi Anda:

docker login

Ini menyimpan kredensial Anda di ~/.docker/config.json. Kemudian daftarkan gambar — air membaca kredensial secara otomatis:

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

Menggunakan autentikasi interaktif

Autentikasi dan simpan kredensial dalam cakupan rahasia Databricks dalam satu langkah:

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

Anda akan diminta untuk Docker Hub nama pengguna dan token akses pribadi Anda. Kredensial disimpan dalam cakupan rahasia ruang kerja Anda untuk pendaftaran di masa mendatang.

Menggunakan rahasia Databricks yang telah disimpan sebelumnya (disarankan untuk CI/skrip)

Simpan kredensial dalam rahasia Databricks dan referensikan secara langsung:

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

Menggunakan gambar Docker dalam beban kerja

Tentukan image Docker dalam YAML workload Anda di bagian environment.docker_image.url:

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

Saat membawa gambar Docker Anda sendiri, environment.dependencies dan environment.version tidak didukung. Menentukan environment.docker_image.url dengan salah satu bidang memicu kesalahan. Jika Anda memiliki dependensi tambahan, instal paket di Dockerfile sebagai gantinya.

Kirimkan beban kerja:

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

Variabel lingkungan yang disuntikkan ke dalam kontainer Anda

Runtime AI menyuntikkan variabel lingkungan berikut ke setiap kontainer saat runtime:

NUM_NODES — jumlah total simpul.
LOCAL_WORLD_SIZE — GPU per node.
WORLD_SIZE — jumlah total proses.
POD_RANK — peringkat simpul saat ini (terindeks 0). Juga diinjeksikan sebagai NODE_RANK.
LOCAL_ADDR — IP simpul lokal (hanya untuk multi-simpul).
MASTER_ADDR — alamat untuk koordinasi rank-0 (khusus multi-node).
MASTER_PORT — porta koordinasi rank 0 (khusus multi-node).

Examples

Node tunggal 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

H100 multinode dengan RDMA

Untuk job H100 multinode yang memerlukan bandwidth jaringan penuh pada instans AWS p5, gunakan salah satu image dasar Databricks sebagai basis image Anda dengan NCCL dan EFA yang telah diprakonfigurasi:

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

Bangun gambar Anda sendiri

Saat membangun image Anda sendiri, Databricks merekomendasikan penggunaan databricks-ai-runtime skill dengan agen coding atau memulai dari image dasar Databricks.

Menggunakan agen pengodian

Instal keterampilan Claude Code databricks-ai-runtime untuk panduan langkah demi langkah tentang Dockerfile, termasuk membangun dari nol, kompatibilitas CUDA/NCCL/EFA, masalah umum, dan daftar periksa sebelum proses pembangunan. Keterampilan ini membutuhkan Databricks CLI versi 1.0.0 atau yang lebih baru.

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

Gambar dasar Databricks

Databricks menerbitkan gambar dasar pada Docker Hub di databricksruntime/air dengan CUDA, NCCL, dan jaringan khusus cloud (AWS EFA atau Azure InfiniBand) yang telah dikonfigurasi sebelumnya.

Tag	Cloud	Variant	Gunakan ketika diperlukan
`dcs-base-aws-runtime`	AWS	Runtime	Menginstal roda bawaan saja
`dcs-base-aws-devel`	AWS	Devel	Mengkompilasi ekstensi CUDA (memerlukan `nvcc`)
`dcs-base-azure-runtime`	Azure	Runtime	Menginstal roda bawaan saja
`dcs-base-azure-devel`	Azure	Devel	Mengkompilasi ekstensi CUDA (memerlukan `nvcc`)

Gunakan varian runtime kecuali Dockerfile Anda mengkompilasi ekstensi CUDA seperti flash-attn, apex, atau kernel kustom.

Contoh Dockerfile menambahkan PyTorch ke gambar dasar Databricks. Gambar dasar menyediakan Python di /opt/venv, dikelola oleh uv. uv pip install menargetkan lingkungan tersebut secara default; untuk menggunakan lingkungan yang berbeda, buat dan aktifkan venv sebelum menjalankan uv pip install.

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

Buat, kirim, dan daftarkan:

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

Requirements

Gambar harus dihosting di Docker Hub. Amazon ECR, Google GCR, dan GitHub GHCR tidak didukung.
Ukuran gambar harus di bawah 20 GB.
WORKDIR tidak diterapkan saat dijalankan. Gunakan path absolut untuk file yang sudah disertakan di dalam image. Misalnya, gunakan python /app/train.py, bukan python train.py.
Anda tidak dapat menggunakan environment.dependencies atau environment.version dengan environment.docker_image.url. Jika Anda membutuhkan paket tambahan di luar apa yang ada dalam gambar, Anda harus menambahkannya ke Dockerfile.

Troubleshooting

Gambar kustom dapat gagal pada runtime dengan kesalahan OpenSSL saat pustaka mencoba membuat konteks SSL, misalnya:

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

Kesalahan muncul saat mengimpor pustaka yang membuka koneksi jaringan, seperti huggingface_hub, dan mencegah pustaka tersebut dimuat.

Ini terjadi karena air beban kerja berjalan pada host yang diaktifkan FIPS. Ketika pustaka kriptografi gambar tidak sesuai FIPS, OpenSSL gagal menginisialisasi dalam mode FIPS, sehingga pembuatan konteks SSL gagal.

Solusi yang direkomendasikan:

Beban kerja perusahaan, pemerintah, layanan kesehatan, dan keuangan sering bergantung pada kepatuhan FIPS 140-2 atau 140-3 untuk audit FedRAMP, CMMC, atau HIPAA. Jika beban kerja Anda harus tetap sesuai dengan FIPS, buat image Anda dengan pustaka kriptografis yang sesuai dengan FIPS.

Jika beban kerja Anda tidak memerlukan kepatuhan FIPS, Anda dapat menonaktifkan mode FIPS dengan mengatur OPENSSL_FORCE_FIPS_MODE variabel lingkungan ke 0. Melakukannya dapat secara diam-diam melanggar persyaratan kepatuhan.

Untuk menonaktifkan mode FIPS, atur di YAML beban kerja Anda pada bagian env_variables:

env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

Atau, atur variabel di Dockerfile Anda sehingga berlaku untuk setiap beban kerja yang menggunakan gambar:

ENV OPENSSL_FORCE_FIPS_MODE=0

Kirim ulang beban kerja dan konfirmasikan kesalahan SSL tidak lagi muncul saat dependensi dimuat.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-30