DatabricksのCLIとAIランタイムを使いましょう

databricks airCLIは、オンデマンドのサーバーレスGPU計算プラットフォームであるAI Runtime上でシングルノードGPUワークロードを実行します。 ワークロードのコンピュート、環境、コマンドをYAMLで定義し、databricks air runで送信します。

AIランタイムはGPUのプロビジョニングと環境設定を担当し、実行状況、ログ、システム指標、MLflowの追跡を提供します。 YAMLおよびCLIのワークフローは、コーディングエージェントと自然に連携し、ワークロードの定義、提出、監視が可能です。

CLIを使って次の操作を行います:

  • ローカル環境からPythonアプリケーションを開発し、反復していく。
  • バージョン管理できるYAMLファイルで繰り返し可能なワークロードを定義しましょう。
  • 端末や自動化された開発ワークフローからワークロードを送信および管理します。

典型的なワークロードには、LLMのファインチューニングやポストトレーニング、分散トレーニング、バッチ推論、Ray アプリケーション、ハイパーパラメータ検索などがあります。

ワークスペースの要件については、「要件」を参照してください。 ワークロードを送信するには、クイックスタートに従ってください。

DatabricksのAIランタイムCLIコマンドは、AIランタイムワークロードと同じコンプライアンス基準を満たしています。 サポートされている標準と例外については、 コンプライアンス セキュリティ プロファイルを参照してください。

Note

databricks airコマンドやワークロードの設定は、databricks-airパッケージ内の従来のPythonベースのairCLIとは異なります。 Python CLI移行を参照してください。

実行可能な例を探る

AI Runtime Cookbookには、モデルトレーニング、ファインチューニング、バッチ推論、レイ、ハイパーパラメータ検索のための実行可能なDatabricks CLIワークロードが含まれています。 各レシピにはワークロードのYAMLファイル、ソースコード、実行手順が含まれています。

ゲートモデルレシピを実行する前に

Hugging Faceトークンとモデル承認は別々の要件です。 ゲーテッドモデルを使用するワークロードを送信する前に:

  1. レシピに記載された正確なモデルリポジトリを開き、トークンを所有しているHugging Faceアカウントにサインインし、その条件に同意するかアクセスを要求してください。 例えば、分散Llamaレシピではmeta-llama/Llama-3.1-8Bが使われています。 リポジトリにアクセスが許可されていることが表示されるまで待ちます。 別の Llama モデルの承認は、このリポジトリへのアクセスを許可しません。

  2. Hugging Faceトークンの要件を満たすトークンを作成しましょう。

  3. ワークロードを送信するワークスペースの Databricks シークレットにトークンを保存し、CLI プロファイルで認証されたユーザーまたはサービスプリンシパルがスコープに READ アクセス権を持っていることを確認します。 「シークレットを使用してワークロードに認証情報を渡す」を参照してください。

  4. GPUを要求する前に、同じトークンが該当するモデルリポジトリから config.json をダウンロードできることを確認してください。 ターゲットワークスペース内のCPUノートブックに、以下の huggingface_hubをインストールします:

    %pip install huggingface_hub
    

    別のセルで以下の Python コードを実行してください。 スコープとキーをワークロード YAML 内のものに置き換えてください。 ノートブックのIDは、その秘密スコープへの読み取りアクセス権を持っていなければなりません:

    from huggingface_hub import hf_hub_download
    
    config_path = hf_hub_download(
        repo_id="meta-llama/Llama-3.1-8B",
        filename="config.json",
        token=dbutils.secrets.get(scope="<scope-name>", key="<key-name>"),
        force_download=True,
    )
    print(f"Downloaded {config_path}")
    

    成功した呼び出しはダウンロードしたファイルのキャッシュパスを印刷します。 force_download=True ファイルがキャッシュされていてもアクセスを確認します。 コードは、ワークスペースシークレットからトークンを出力せずに読み取ります。 別のレシピの場合は、repo_id を対応する正確なモデルリポジトリ名に置き換えてください。 Hugging Faceのダウンロードガイドをご覧ください。

シークレットの欠落、認証エラー、ゲートリポジトリエラーについては、「 シークレットおよびモデルアクセスのトラブルシューティング」を参照してください。 接続障害によりダウンロードチェックが行われない場合、アクセスはまだ未確認のままです。 接続の問題を解決して再試行してからトレーニングを送信してください。

ゲートモデルの承認なしで始めるには、Qwen レシピなど、AI Runtime Cookbook から承認不要のレシピを選びましょう。 そのレシピの設定と依存関係を活用しましょう。 LlamaのレシピでモデルIDを置き換えるには、トレーニングコードやGPUサイズの変更が必要になることがあります。

ワークロードの実行方法

ワークロードのYAMLファイル、必要に応じてアプリケーションコード、そしてアプリケーションを起動するコマンドを提供します。 ワークロードを送信する際:

  1. ワークロードの定義は、サポートされたスキーマおよび構成制約に対して検証されます。
  2. code_sourceが設定されている場合、選択したコードはスナップショットとしてパッケージ化されアップロードされます。
  3. 要求された GPU コンピューティングと環境は各ノードで準備されます。
  4. ワークロードYAMLで提供されたコマンドは各ノードで実行されます。

送信すると、ワークロードを識別するジョブ実行 ID が返されます。 ステータス確認、ログや設定の確認、ワークロードのキャンセルなどに使えます。 また、ジョブ実行ページやMLflow実験で実行の詳細、システム指標、ログ、アーティファクトも閲覧できます。

このワークフローは、GPUインフラの設定や保守を必要とせずに、管理されたGPUプロビジョニング、再現可能な環境設定、組み込みの可観測性を提供します。

ワークロード構成

ワークロードYAMLファイルは以下のコンポーネントを記述します:

  • Experiment: ワークロードを追跡する MLflow の Experiment と Run。
  • 環境:管理された環境、依存関係、または使用する カスタムDockerイメージ 。
  • コンピューティング: 提供するアクセラレータの種類と数。
  • コードソース:ワークロードに提供するためのアプリケーションコードのオプションスナップショット。
  • コマンド:アプリケーションを起動するシェルコマンドです。
  • ランタイム設定: リトライ、タイムアウト、環境変数、シークレット、権限などのオプション。

構成フィールドや例については、 Workload YAMLリファレンスを参照してください。

カスタム Docker イメージを使用する

マネージド環境の代わりに、独自のDockerイメージでワークロードを実行できます。 ワークロードがシステムライブラリやCUDA拡張機能、または environment.dependenciesではインストールできない依存関係が必要な場合はカスタムイメージを使いましょう。 カスタムDockerイメージは パブリックプレビュー中です。 これらを使用するには、ワークスペース管理者がワークスペースのプレビュー ページからDatabricks Artifact Registryのプレビューを有効にする必要があります。

linux/amd64用のイメージを作成し、ワークスペースのArtifact Registryにプッシュし、ワークロードのYAMLでenvironment.unity_catalog_imageをイメージのUnity Catalog名に設定します。 手順、Databricksのベースイメージ、Docker認証、トラブルシューティングについては、「 AI RuntimeでカスタムDockerイメージを使用する」をご覧ください。

アプリケーションコードをアップロード

code_source を使って、ワークロードとともにアプリケーション ファイルをアップロードします。 AI ランタイムはアップロードされたディレクトリをすべてのノードで利用可能にし、$CODE_SOURCE_PATH をその場所に設定します。 たとえば、以下のコマンドを実行すると、アップロードしたディレクトリから train.py が実行されます。

command: python "$CODE_SOURCE_PATH/train.py"

現在の作業ツリーをアップロードするか、Gitブランチやコミットを選択できます。 完全な例は クイックスタートをご覧ください。

ワークロードを開発および管理する

開発は通常以下のプロセスを踏みます。

  1. アプリケーション コードとワークロード YAML をローカルで開発します。
  2. databricks air run --file <file> --dry-runでYAMLをローカルで検証してください。
  3. databricks air run --file <file> --watch でワークロードを送信し、実行が終了するまでログをストリーミングしてください。
  4. databricks air get、databricks air list、databricks air logsを使ってワークロードやログを検査します。
  5. 必要に応じて、実行中のワークロードを databricks air cancel で停止することも可能です。

バックグラウンドで送信し、後でログに接続する場合は、--watch を省略してください:

databricks air run --file workload.yaml
databricks air get <job-run-id>
databricks air logs <job-run-id>

提出時に返されたジョブランIDを使いましょう。 3つのコマンドすべてで同じワークスペースプロファイルを保ちましょう。 デフォルトプロファイルの設定および検証については 、「設定プロファイルに関する情報を得る」をご覧ください。

すべてのコマンドおよびフラグについては、airコマンドグループをご覧ください。

スケジュールされた実行、マルチタスクワークフロー、環境をまたぐプロモーションのために、 databricks air convert-to-dabs をバンドルの出発点として使うことができます。 「GPU ワークロードのスケジュール設定とタスクの作成」を参照してください。

MLflowでワークロードを追跡する

提出された各ワークロードはDatabricksのジョブ実行で表され、MLflow実験を通じて追跡されます:

  • Databricksジョブ実行:ジョブ実行ページにワークロードの状態、実行試行、出力を表示します。
  • MLflow experiment: 自動取得されたシステム指標、ワークロード設定、ログを含むMLflow runを含みます。 また、MLflow APIを使ってカスタムパラメータ、指標、アーティファクトをログに記録することも可能です。

ジョブ実行IDを databricks air get、 databricks air logs、 databricks air cancelなどのコマンドで使用してください。 「 実験の追跡と観測可能性」を参照してください。

シングルノードおよび分散ワークロードを実行

AI Runtimeは、プロビジョニングされたノード上で設定されたコマンドを実行します。 マルチGPUワークロードに対しては、 LOCAL_WORLD_SIZE や WORLD_SIZEなどの調整変数を提供します。

この実行モデルはフレームワークに依存しません。 コマンドは分散フレームワークを起動し設定しなければなりません。例えば、 torchrun、Rayブートストラップスクリプト、または他のフレームワークランチャーを呼び出して設定する必要があります。 完全なワークロードについては、 AI Runtime Cookbookをご覧ください。

AIエージェントを使いましょう

databricks-ai-runtimeエージェントスキルは、Claude Code、Cursor、CodexなどのAIエージェントがDatabricks CLIを通じてAI Runtimeを扱うのを支援する指示を提供します。 これを使ってワークロードYAMLの作成、GPUトレーニングジョブの提出、実行状況の確認、ログのストリーミング、実行のキャンセルなどに使えます。 また、カスタムDockerイメージのガイダンスも含まれています。

Databricks CLIをインストールし認証を設定した後、以下のコマンドを実行します。

databricks aitools install --skills-only --skills databricks-ai-runtime

AIエージェントとインストール範囲を選択するには、プロンプトに従ってください。 AIエージェントがコマンドを実行するような非インタラクティブなセッションでは、プロンプトは出ず、検出されたすべてのエージェントごとにスキルがグローバルにインストールされます。 エージェントとスコープを選択するには、それらをフラグとして渡してください。 たとえば、次のコマンドは現在のプロジェクトに Claude Code のスキルをインストールします。

databricks aitools install --skills-only --skills databricks-ai-runtime --agents claude-code --scope project

インストール オプションについては、aitoolsコマンド グループを参照してください。 スキルが扱う内容については、「AI Runtime でエージェントスキルを使用する」をご覧ください。

その他のリソース