AI ランタイム環境の設定

AI Runtimeは2つのマネージドPython環境を提供します。 標準環境には cudaが含まれています。 環境バージョン 5 の時点では、 torch と torchvision はプレインストールされなくなりました。 DatabricksのAI環境にはPyTorch、Transformers、その他の機械学習やディープラーニングフレームワークがあらかじめインストールされています。 依存関係スタックを完全に制御する Standard 環境を選択するか、すぐに使用できるトレーニングセットアップ用の AI 環境を選択します。 どちらの環境から始めて、自分でさらに多くのパッケージをインストールすることができます。

このページの重要なポイント:

  • 依存関係を完全に制御するには Standard 環境を、すぐに使えるMLスタックを用意するには Databricks AI 環境を選びましょう。
  • 標準には cudaが含まれます。 環境バージョン5以降、 torch と torchvision は事前インストールされていません。 AI環境にはPyTorchやTransformersなどが追加されています。
  • %uv pip install(環境バージョン 5 以上)、またはノートブック内の environment.dependencies、あるいは CLI の %pip install を使って、さらにパッケージをインストールできます。

使用する環境は何か

AI ランタイムには、Standard 環境と Databricks AI 環境という 2 つのマネージド Python環境が用意されています。 Databricks CLI で送信したワークロードは、カスタム Docker イメージを使用して実行することもできます。

Environment 主要な特徴 いつ使用するか
標準環境 最小限。cuda を含みます。 環境バージョン 5 の時点では、torchとtorchvisionはプレインストールされなくなりました。 依存関係スタックを完全に制御し、必要なもののみをインストールする必要がある場合
Databricks AI 環境 人気のある機械学習(ML)フレームワーク(PyTorch、Transformers など)が事前にインストールされています 手動の依存関係管理を使用せずに、トレーニング、微調整、実験のための完全な環境が必要です
カスタム Docker イメージ (パブリックプレビュー) 通常はDatabricksのベースイメージから構築されたアーティファクトレジストリに保存された独自のイメージです。 Databricks CLIワークロード向けに利用可能。 ワークスペース管理者は Databricksアーティファクトレジストリ プレビューを有効にする必要があります。 システムライブラリ、コンパイル済みのCUDA拡張、あるいは再現できない既存のコンテナ構成が必要です environment.dependencies

また、ワークスペース管理者がAIランタイム用に構築した ワークスペースベース環境 を使うこともできます。 サーバーレス GPU コンピューティング (AI ランタイム) のビルドを参照してください。

ノートブックで環境を選択するには、 Environment サイドパネルを開き、 ベース環境を選択してください:

ノートブックの環境サイドパネルでベース環境を選択すること。

標準環境 (最小環境)

AI ランタイム操作に必要なパッケージのみを含む、最小限の安定した環境。 この環境には、GPU サポート用の cuda が含まれています。 環境バージョン 5 の時点では、 torch と torchvision はプレインストールされなくなりました。 必要なバージョンを %uv pip install または %pip installでインストールしてください。 各環境バージョンにインストールされているパッケージについては、以下のリリース ノートを参照してください。

最適: 依存関係スタックを完全に制御し、必要なものだけをインストールするユーザー。

選択方法: 環境 サイドパネルで、基準環境として Standard v6 を選択してください。

さまざまなバージョンにインストールされているパッケージ バージョンの詳細については、リリース ノートを参照してください。

Databricks AI 環境

環境 4 以降で使用できます。 AI 環境は、GPU 上の機械学習に固有の一般的なランタイム パッケージとパッケージを使用して、Standard 環境の上に構築されています。 プレインストールされたパッケージには、次のものが含まれます。

  • PyTorch (CUDA サポートあり)
  • トランスフォーマー (ハギングフェイス)
  • その他の ML/DL 依存関係

最適: 手動の依存関係管理を使用せずに、ワークロードのトレーニング、微調整、実験のための完全な環境を必要とする ML 専門家。

選択方法: 環境 サイドパネルで、ベース環境として AI v6 を選択します。

さまざまなバージョンにインストールされているパッケージ バージョンの詳細については、リリース ノートを参照してください。

追加パッケージをインストールする

マネージド環境かワークスペースベースの環境のいずれかから始めて、その上に自分だけのPythonパッケージをインストールすることができます。 インストール方法はAIランタイムへの接続方法によります。

ノートの中で

ノートブックやトレーニング スクリプトの先頭で %uv pip を使ってパッケージをインストールできます。これは uv を使用してインストールし、%pip よりも高速です。 実行の再現性を保つために、バージョンを固定します:

%uv pip install "trl==1.1.0"
%uv pip install "transformers==5.5.4"

すべての%pipおよび%uv pip参照、どの環境バージョンがそれぞれをサポートするかについては、「%uvコマンドでライブラリを管理する」を参照してください。

@distributedデコレーターをマルチGPUワークロードに使うと、.distributed()呼び出す前にインストールしたパッケージは自動的にスナップショットされ、すべての分散プロセスに伝播されます。 インストールされているパッケージの合計サイズは、15 GB を超えてはなりません。 詳細については、「 ノートブックへの依存関係の追加」を参照してください。

CLI で

airCLIも同じ管理環境を使用しています。 environment.version付きのものを選び、その上にインストールするパッケージをワークロードYAMLのenvironment.dependencies欄にリストアップしてください。 CLIは選択した環境に UVをインストールし、別の仮想環境を自分で管理する必要がなくなります。

environment:
  version: '6'
  dependencies:
    - trl==1.1.0
    - transformers==5.5.4

標準環境には torch や torchvisionが含まれていないので、ワークロードでそれらをインポートする場合は dependenciesに追加してください。 代わりに Databricks の AI 環境(PyTorch を含む)から始めるには、 version を databricks_ai_v6 のような AI 環境識別子に設定してください。 完全な依存関係の形式およびサポートされているインストール フラグについては、environmentを参照してください。 ワークロードを管理環境ではなく自社のイメージで実行する場合は、「 AI ランタイムでカスタム Docker イメージを使用する」を参照してください。

シークレットを使用してワークロードに認証情報を渡す

ワークスペースのシークレットを使用して、Databricks CLI を使用して送信したワークロードに認証情報を渡します。 ワークロードは、選択した CLI プロファイルによって認証されたユーザーまたはサービスプリンシパルとして実行されます。 以下の手順では、Hugging Faceトークンを例として使用します。 別の認証情報を渡すには、 HF_TOKEN をアプリケーションが読み取る環境変数に置き換えてください。 Hugging Faceトークンの要件については、Hugging Face tokensを参照してください。

  1. ワークロードを送信するワークスペースを選択し、そのホストを確認してください:

    export DATABRICKS_CONFIG_PROFILE=<profile>
    databricks auth describe
    
  2. Databricks をバックエンドとするシークレット スコープを作成するか、書き込み可能な既存のスコープを使用します。 スコープとキーのプレースホルダーを、ワークロード YAML で使用している名前に置き換えてください:

    databricks secrets create-scope <scope-name>
    databricks secrets put-secret <scope-name> <key-name>
    

    インタラクティブなプロンプトでトークンを入力します。 トークンはYAMLやコマンド引数、ソースコントロールから外してください。 既存のスコープを使用する場合は、create-scopeをスキップしてください。 キーネームには /が含まれることはできません。 キーがすでに存在する場合、 put-secret はその値を上書きします。

  3. 認証済みユーザーまたはサービスプリンシパルがスコープへの READ アクセス権を持っていない場合は、スコープに対して MANAGE 権限を持つユーザーにアクセス権を付与するよう依頼してください。 同じアイデンティティでスコープを作成した場合、すでにREADを含むMANAGEが存在しているため、このステップをスキップできます。 <principal>を認証済みユーザーのメールアドレス、サービスプリンシパルのアプリケーションID、またはグループ名に置き換えます:

    databricks secrets put-acl <scope-name> <principal> READ
    

    シークレットスコープの権限付与には プレミアムプランが必要です。 スコープ権限はスコープ内のすべてのシークレットに適用されます。 アクセスを制限する必要がある場合は専用のスコープを使用してください。 秘密スコープの権限を参照してください。

  4. ワークロード YAML でシークレットを参照してください:

    secrets:
      HF_TOKEN: <scope-name>/<key-name>
    

    AI ランタイムは参照を解決し、ワークロードの HF_TOKEN 環境変数としてトークンを提供します。 ローカルシェルで HF_TOKEN を設定するだけではリモートワークロードは設定されません。

  5. トークンを取得したり印刷したりせずに、キーおよびスコープの権限を確認します:

    databricks secrets list-secrets <scope-name>
    databricks secrets list-acls <scope-name>
    

    期待されるキーが存在し、認証済みユーザーまたはサービスプリンシパルが直接またはグループを通じて READ 以上の権限を持っていることを確認してください。 これらのコマンドは、キーメタデータとスコープの権限を表示します。 トークンやモデルの承認は検証しません。 スコープの権限を一覧表示できない場合は、スコープに対して MANAGE 権限を持つユーザーにアクセスの確認を依頼してください。

シークレットはワークスペース単位です。 CLIプロファイルやワークスペースを変更するときは、ホスト、キー、アクセスチェックを宛先ワークスペースで繰り返し行ってください。 同じスコープとキー名でも、異なるワークスペース内の異なるシークレットを参照できます。

シークレットを更新すると、再試行されたワークロードは新しい値を受け取ります。 ノートブックコードでは、更新された値を取得するためにシークレットを再度読み込みます。

ノートブックのワークロードでは、 dbutils.secrets.get を使ってワークスペースのシークレットを読み取ってください。 例えば、ノートブックのPythonプロセスでHF_TOKENを設定するには:

import os

os.environ["HF_TOKEN"] = dbutils.secrets.get(scope="<scope-name>", key="<key-name>")

秘密を印刷しないでください。 ノートブックのIDには、スコープへのアクセスがREAD必要です。 「 get コマンド (dbutils.secrets.get)」を参照してください。

Hugging Face トークン

プライベートまたはゲートモデルを読み込むワークロードを実行する前に、モデルリポジトリへの読み取りアクセス権を持つ Hugging Faceアクセストークン を作成します。 細分化されたトークンの場合は、そのリポジトリへの読み取りアクセスを付与します。 トークンを所有しているHugging Faceアカウントは、そのモデルへのアクセス権を持っている必要があります。 トークンの作成はモデル承認を付与しません。

手順内のシークレットマッピングはトークンを HF_TOKENとして提供し、Hugging Face ライブラリはこれをワークロード環境から読み取ります。

シークレットおよびモデルアクセスのトラブルシューティング

ワークロードが失敗した場合は、以下の表で症状を確認してください。

現象 固定
ワークロードがスコープやキーを見つけられない。 ワークロードの YAML にあるスコープとキーが、ワークロードを送信するワークスペースで作成したものと一致していることを確認してください。
シークレットのアクセス許可エラー。 CLI READ で認証されたユーザーまたはサービスプリンシパルにスコープへのアクセスを許可します。 前述の手順を参照してください。
Hugging Face はトークンを拒否します (401)。 トークンが有効で、モデルリポジトリへの読み取りアクセス権があることを確認してください。 期限切れまたは取り消されたトークンを置き換えます。
GatedRepoError またはゲート付きリポジトリの403応答。 トークン所有者のモデルへのアクセスが承認され、トークンがそのリポジトリに対して読み取りアクセス権を持っていることを確認してください。

ワークスペースの基本環境

ワークスペース管理者は、AI Runtime用の ワークスペースベース環境 を構築でき、ワークスペース内のすべてのユーザーが Base environment ドロップダウンメニューを通じて利用できるようにします。 詳細については、「 サーバーレス GPU コンピューティング用のビルド (AI ランタイム)」を参照してください。

スケジュールされたワークロードでベース環境を使用するには、ジョブやバンドルの environments ブロック内の識別子で参照してください。 例えば、この宣言的自動化バンドルタスクではDatabricksのAI環境を選択します:

resources:
  jobs:
    train:
      tasks:
        - task_key: train
          environment_key: default
      environments:
        - environment_key: default
          spec:
            base_environment: databricks_ai_v6

完全なジョブ例については、GPU ワークロードのスケジュール設定とタスクの作成を参照してください。

環境キャッシュとカスタム モジュール

環境はいつキャッシュされますか?

AIランタイムはノートブックの環境をキャッシュするので、ノートブックを再起動してもパッケージを再インストールする必要はありません。 詳細は「 環境依存関係のリセット」を参照してください。

キャッシュはインタラクティブノートに適用されます。 airCLIを経由するかジョブとしてスケジューリングされたワークロードはこのキャッシュを使用しません。各実行は依存関係を新規インストールします。

ベストプラクティスとして、パッケージを特定のバージョンにピン留めすることで、キャッシュ環境が有効で実行が再現可能になります。

カスタム モジュールをインポートする方法

以下の手順では、自分のPythonモジュールの使い方を示します。

  1. コードをワークスペースに同期してください。 Gitリポジトリをワークスペースにクローンし、 Gitフォルダを作ってもいいか、ファイルを ワークスペースファイルとして直接アップロードする方法もあります。 共有コードをチームプロジェクト用の /Workspace/Shared の下に保存するか、個人開発用のユーザーフォルダに保存してください。 コードをGitフォルダに保管することでバージョン管理ができます。
  2. フォルダを sys.path に追加し、 ノートブックやトレーニングスクリプトの上部にインポートしてください:
import sys
sys.path.append("/Workspace/Shared/my-project/src")
from my_module import my_function

Limitations

次の機能は、AI ランタイムでは使用できません。

  • Spark 関数: PySpark 関数を直接インポートまたは使用することはできません。 AI ランタイムは Python 専用の環境です。Spark はローカル ランタイムとして使用できません。 ただし、Spark Connect はデータの読み込みに使用できます。 AI ランタイムでのデータの読み込みを参照してください。
  • Databricks ランタイム ML ライブラリ: プレインストールされたパッケージは、Databricks Runtime ML の代わりではありません。 Databricks Runtime ML で使用できる一部の ML ライブラリは、AI ランタイムにプレインストールされない場合があります。
  • プライベート成果物: AI ランタイムは、特定の場合にプライベート成果物をサポートします。 詳細については、アカウント チームにお問い合わせください。