従来のPython CLIでカスタムDockerイメージを使用
このドキュメントは廃止されており、更新されない可能性があります。
databricks-air パッケージでインストールされる Python ベースの air CLI は廃止されており、現在はアクティブにメンテナンスされていません。
新しいワークロードには Databricks CLI を使用します。AI ランタイム で Databricks CLI を使用するを参照してください。
Docker Container Services（DCS）を使用すると、独自のDockerコンテナイメージを air ワークロードに持ち込むことができます。カスタムイメージが必要な場合:
- 特定のシステムライブラリのバージョン。
environment.dependenciesにうまく適合しない複雑な依存関係。- 研究結果を再現するための正確な環境
- 組織のプラットフォームまたはセキュリティチームによって構築された標準イメージ。
前提条件
- AI ランタイム CLIのインストール。
- ワークスペース管理者は、 AI ランタイム ベータ版機能 プレビューを有効にしました。手順については、 ワークスペース レベルのプレビューを管理するを参照してください。
- プライベートイメージの場合は、イメージにアクセスできるDocker Hubアカウント。
イメージを登録する
カスタムイメージを使用してワークロードを実行する前に、air register image に登録してください。登録では、イメージがプルされ、Databricks プラットフォームにキャッシュされます。各ユーザーは、イメージタグごとに 1 回イメージを登録する必要があります。新しいタグをプッシュする場合、または認証情報をローテーションする場合にのみ再登録するしてください。登録には 2～6 分かかり、イメージが準備できるまでブロックされます。
パブリックイメージ
DockerイメージURLとDatabricksプロファイルを提供して、パブリックイメージを登録します:
air register image docker.io/nvidia/cuda:12.9.0-devel-ubuntu24.04 -p my-databricks-profile
短い形式の画像参照も機能します。たとえば、 library/ubuntu:latest。
プライベートDocker Hubイメージ
プライベートDocker Hubイメージを登録するには、最初に個人用アクセストークンを生成します。Docker Hubアカウント設定で、 Personal アクセストークン → Generate new token をクリックします。読み取り専用アクセスで十分です。
以下の認証方法のいずれかを選択してください：
docker loginの使用（対話型使用に推奨）
ターミナルでDocker Hubにログインします。Docker Hubのユーザー名と個人用アクセストークンの入力を求められます：
docker login
これは資格情報を ~/.docker/config.json に保存します。次に、イメージを登録します — air は資格情報を自動的に読み取ります。
air register image myorg/myrepo:mytag -p my-databricks-profile
対話型認証の使用
認証を実行し、ワンステップで Databricks Secret Scope に認証情報を格納する：
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile
Docker Hubのユーザー名と個人アクセストークンの入力を求められます。認証情報は、将来の登録のためにワークスペースのSecret Scopeに保存されます。
事前に保存されたDatabricksシークレットを使用する（CI/スクリプトに推奨）
資格情報を Databricks シークレットに格納し、それを直接参照します。
air register image myorg/myrepo:mytag --scope my-secret-scope --key my-docker-key -p my-databricks-profile
ワークロードで Docker イメージを使用する
ワークロード YAML の environment.docker_image.url で Docker イメージを指定します。
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
独自の Dockerイメージを持ち込む場合、environment.dependencies と environment.version はサポートされません。どちらかのフィールドに environment.docker_image.url を指定するとエラーをTriggerします。追加の依存関係がある場合は、代わりに Dockerfile にパッケージをインストールします。
ワークロードを送信する:
air run --file workload.yaml -p my-databricks-profile
コンテナに注入される環境変数
AIランタイムは、実行時にすべてのコンテナに次の環境変数を挿入します。
NUM_NODES— ノードの合計数。LOCAL_WORLD_SIZE— ノードあたりの GPU 数。WORLD_SIZE— プロセスの総数。POD_RANK— 現在のノードランク（0から始まります）。NODE_RANKとしてインジェクションされます。LOCAL_ADDR— ローカルノードIP（マルチノードのみ）。MASTER_ADDR— rank-0調整アドレス（マルチノードのみ）。MASTER_PORT— rank-0調整ポート（マルチノードのみ）。
例
シングルノード 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を使用するマルチノードH100
AWS p5インスタンスでフルネットワーク帯域幅を必要とするマルチノードH100ジョブの場合、NCCLとEFAが事前に設定されたDatabricksベース画像のいずれかをベースに画像を作成します。
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
独自のイメージを構築する
独自のイメージを構築する場合、Databricksでは、コーディングエージェントと共に databricks-ai-runtime スキルを使用するか、Databricksベースイメージから開始することをお勧めします。
コーディングエージェントを使用してください
databricks-ai-runtime Claude Code スキルをインストールすると、ゼロからの構築、CUDA/NCCL/EFA の互換性、一般的な問題、プレビルドチェックリストなど、Dockerfile に関する手順を追ったガイダンスが得られます。このスキルには、Databricks CLI バージョン 1.0.0 以降が必要です。
databricks aitools install --skills databricks-ai-runtime
Databricks 基本イメージ
Databricksは、CUDA、NCCL、およびクラウド固有のネットワーキング（AWS EFAまたはAzure InfiniBand）が事前に構成されたベースイメージをDocker Hub（databricksruntime/air）で公開しています。
タグ | バリアント | CUDA | 使用する場合 |
|---|---|---|---|
| ランタイム | 12 | ビルド済み wheel のみインストール |
| 開発 | 12 | CUDA 拡張機能のコンパイル（ |
| ランタイム | 13 | CUDA 13でビルド済みのwheelのみをインストールする |
| 開発 | 13 | CUDA 13 での CUDA 拡張機能のコンパイル ( |
DatabricksベースイメージにPyTorchを追加するDockerファイルの例。ベースイメージは/opt/venvでPythonを提供し、uvによって管理されます。uv pip installはdefaultでその環境をターゲットにします。別の環境を使用するには、uv pip installを実行する前にvenvを作成してアクティブ化してください。
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
ビルド、プッシュ、登録する：
docker build -t myorg/myrepo:mytag .
docker push myorg/myrepo:mytag
air register image myorg/myrepo:mytag --interactive-authenticate -p my-databricks-profile
要件
- イメージはDocker Hubでホストされている必要があります。ECR、Google GCR、GitHub GHCRはサポートされていません。
- イメージサイズは20 GB未満である必要があります。
WORKDIRは実行時には適用されません。イメージに焼き込まれたファイルには絶対パスを使用します。たとえば、python train.pyではなくpython /app/train.pyを使用します。environment.docker_image.urlでenvironment.dependenciesまたはenvironment.versionを使用することはできません。イメージに含まれているもの以外の追加パッケージが必要な場合は、それらをDockerfileに追加する必要があります。
トラブルシューティング
ssl.SSLError: [CRYPTO] unknown error (_ssl.c)依存関係の読み込み中
ライブラリがSSLコンテキストを作成しようとしたときに、カスタムイメージがランタイムでOpenSSLエラーで失敗する場合があります。例：
ssl.SSLError: [CRYPTO] unknown error (_ssl.c:3076)
このエラーは、huggingface_hubのようにネットワーク接続を開くライブラリをインポートする際に発生し、それらのライブラリが読み込まれないようにします。
これは、 air ワークロードが FIPS 対応ホストでランされるために発生します。イメージの暗号化ライブラリが FIPS 準拠でない場合、 OpenSSL は FIPS モードで初期化に失敗するため、 SSL コンテキストの作成が失敗します。
推奨ソリューション：
企業、政府、医療、および金融のワークロードは、多くの場合、 FedRAMP、 CMMC、または HIPAA の監査のために FIPS 140-2 または 140-3 のコンプライアンスに依存しています。ワークロードが FIPS コンプライアンスを維持する必要がある場合は、 FIPS コンプライアンスの暗号化ライブラリを使用してイメージをビルドします。
ワークロードでFIPSコンプライアンスが不要な場合、環境変数 OPENSSL_FORCE_FIPS_MODEを 0に設定することでFIPSモードを無効にできます。そうすると、コンプライアンス要件が警告なしに損なわれる可能性があります。
FIPSモードを無効にするには、ワークロードYAMLの env_variables に設定します：
env_variables:
OPENSSL_FORCE_FIPS_MODE: '0'
あるいは、Dockerfileで変数を設定して、そのイメージを使用するすべてのワークロードに適用するようにします：
ENV OPENSSL_FORCE_FIPS_MODE=0
ワークロードを再送信し、依存関係の読み込み時にSSLエラーが表示されなくなったことを確認します。