メインコンテンツまでスキップ
非公開のページ
このページは非公開です。 検索対象外となり、このページのリンクに直接アクセスできるユーザーのみに公開されます。
に最終更新

レガシー Python CLI でカスタム Dockerイメージを使用する

重要

このドキュメントは廃止されており、更新されない可能性があります。

databricks-airパッケージでインストールされたPythonベースのair CLIは、現在非推奨であり、積極的なメンテナンスは終了しています。

新しいワークロードには Databricks CLI を使用します。「Use the Databricks CLI with AI ランタイム」を参照してください。

重要

この機能はベータ版です。これを使用するには、ワークスペース管理者がワークスペースのプレビューページ から AI Runtimeベータ機能 プレビューを有効にする必要があります。

Docker Container Services (DCS) を使用すると、独自の Docker コンテナイメージを air のワークロードに取り込むことができます。カスタムイメージが必要な場合：

  • 特定のシステムライブラリのバージョン。
  • environment.dependencies にきれいに収まらない複雑な依存関係。
  • 研究結果を再現するための正確な環境。
  • 組織のプラットフォームまたはセキュリティチームによって構築された標準イメージ。

前提条件​

イメージを登録する​

カスタムイメージを使用してワークロードを実行する前に、air register image に登録してください。登録により、Databricks プラットフォームでイメージのプルとキャッシュが行われます。各ユーザーは、イメージタグごとに 1 回イメージを登録する必要があります。新しいタグをプッシュする場合、または認証情報をローテーションする場合のみ、再登録を行ってください。登録には 2～6 分かかり、イメージの準備ができるまでブロックされます。

パブリックイメージ​

Dockerイメージの URL と Databricks プロファイルを指定して、パブリックイメージを登録します。

Shell
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 アカウントの設定で、 [パーソナルアクセストークン] → [新しいトークンを生成] の順にクリックします。読み取り専用アクセス権で十分です。

次のいずれかの認証方法を選択します。

docker login の使用（インタラクティブな使用に推奨）​

ターミナルで Docker Hub にログインします。Docker Hub のユーザー名とアクセストークンの入力を求められます。

Shell
docker login

これにより、資格情報が ~/.docker/config.json に保存されます。次に画像を register します — air は自動的に資格情報を読み取ります：

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

インタラクティブ認証の使用​

1 つのステップで認証を行い、Databricks Secret Scopeに資格情報を保存します。

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

Docker Hub のユーザー名とアクセストークンの入力を求められます。今後の登録のために、認証情報はワークスペースの Secret Scope に保存されます。

事前に保存した Databricks シークレットの使用 (CI/スクリプトに推奨)​

認証情報を Databricks シークレットに格納し、直接参照します:

Shell
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イメージを指定します：

YAML
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 内にパッケージをインストールしてください。

ワークロードを送信します:

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

コンテナーに注入される環境変数​

AI Runtime は、ランタイム時にすべてのコンテナに次の環境変数をインジェクションします。

  • NUM_NODES — ノードの総数。
  • LOCAL_WORLD_SIZE — ノードあたりの GPU 数。
  • WORLD_SIZE — プロセスの総数。
  • POD_RANK — 現在のノードランク（0 からインデックス付け）。NODE_RANK としてもインジェクションされます。
  • LOCAL_ADDR — ローカルノードIP（マルチノードのみ）。
  • MASTER_ADDR — ランク 0 コーディネーションアドレス (マルチノードのみ)。
  • MASTER_PORT — ランク 0 コーディネーションポート (マルチノードのみ)。

例​

シングルノード A10​

YAML
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 ベースイメージのいずれかにイメージの基礎を置きます:

YAML
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のベースイメージから開始することを推奨しています。

コーディングエージェントの使用​

ゼロからの構築、CUDA/NCCL/EFA の互換性、一般的な問題、プレビルドチェックリストなど、Docker に関するステップバイステップのガイダンスを得るには、 databricks-ai-runtime Claude Code スキルをインストールしてください。このスキルには、Databricks CLI バージョン 1.0.0 以降が必要です。

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

Databricks ベースイメージ​

Databricks は、CUDA、NCCL、およびクラウド固有のネットワーキング (AWS EFA または Azure InfiniBand) が事前に構成されたベースイメージを Docker Hub (databricksruntime/air) で公開しています。

タグ

バリアント

CUDA

使用する場合

dcs-base-aws-runtime

ランタイム

12

ビルド済みの wheel のみのインストール

dcs-base-aws-devel

開発

12

CUDA 拡張機能のコンパイル（nvccが必要）

dcs-base-aws-runtime-cu13

ランタイム

13

CUDA 13 でのビルド済み wheel のみのインストール

dcs-base-aws-devel-cu13

開発

13

CUDA 13 での CUDA 拡張機能のコンパイル（nvcc が必要）

タグ

バリアント

CUDA

使用する場合

dcs-base-aws-runtime

ランタイム

12

ビルド済みの wheel のみのインストール

dcs-base-aws-devel

開発

12

CUDA 拡張機能のコンパイル（nvccが必要）

dcs-base-aws-runtime-cu13

ランタイム

13

CUDA 13 でのビルド済み wheel のみのインストール

dcs-base-aws-devel-cu13

開発

13

CUDA 13 での CUDA 拡張機能のコンパイル（nvcc が必要）

Databricks ベースイメージに PyTorch を追加する Dockerfile の例。ベースイメージでは、uv によって管理される Python が /opt/venv で提供されます。uv pip install は default でその環境をターゲットとします。別の環境を使用するには、uv pip install を実行する前に venv を作成してアクティブ化してください。

Dockerfile
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

構築、プッシュ、登録:

Shell
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 でホストされている必要があります。Amazon 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 エラーにより失敗する可能性があります（例：

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

The error appears while importing ライブラリ that open network connections, such as huggingface_hub, and prevents them from loading.

これは、air ワークロードが FIPS 対応ホスト上で実行されるために発生します。イメージの暗号化ライブラリが FIPS に準拠していない場合、OpenSSL は FIPS モードでの初期化に失敗するため、SSL コンテキストの作成に失敗します。

おすすめのソリューション：

エンタープライズ、政府機関、医療、金融のワークロードでは、FedRAMP、CMMC、またはHIPPAの監査におけるFIPS 140-2または140-3準拠が必要になることがよくあります。ワークロードをFIPS準拠の状態に維持する必要がある場合は、FIPS準拠の暗号化ライブラリを使用してイメージをビルドしてください。

ワークロードでFIPS コンプライアンスが不要な場合は、環境変数 OPENSSL_FORCE_FIPS_MODE を 0 に設定することでFIPSモードを無効にできます。これにより、コンプライアンス要件が気付かないうちに満たされなくなる可能性があります。

FIPS モードを無効にするには、ワークロードの YAML の env_variables の下に設定します：

YAML
env_variables:
  OPENSSL_FORCE_FIPS_MODE: '0'

または、そのイメージを使用するすべてのワークロードに適用されるように、Dockerfile で変数を設定します。

Dockerfile
ENV OPENSSL_FORCE_FIPS_MODE=0

ワークロードを再送信し、依存関係の読み込み時に SSL エラーが表示されなくなることを確認します。

See also​

このページの見出し