メインコンテンツまでスキップ
に最終更新

Model ServingからDatabricks Appsへのエージェントの移行

既存のAIエージェントをModel ServingエンドポイントからDatabricks Appsに移行します。

Databricks は、Model Serving よりも以下の利点があるため、Databricks Apps 上でエージェントをオーサリングすることを推奨しています。

  • 迅速なイテレーション : ローカルデバッグとログおよびエージェントの動作を完全に可視化して、エージェントのコードとデプロイ設定を数秒で反復します。
  • Gitベースのバージョン管理とCI/CD ：モジュール式のPythonエージェントコードをGitでパッケージ化およびバージョン管理し、宣言型オートメーションバンドルでデプロイします。
  • AIコーディングアシスタントのサポート ：AIコーディングアシスタントを使用して、エージェントをローカルで開発および移行します。
  • スケーラブルな非同期エージェント : ネイティブのPython非同期パターンで非同期エージェントを構築し、high concurrencyを実現します。
  • 柔軟なサーバーのカスタマイズ : 任意のフレームワークまたはスタックを使用し、カスタムルートとミドルウェアを追加し、LLM エンドポイントとツールに対するユーザーおよびエージェント認証を構成します。
  • MLflowトレース : MLflowのGitベースの記録済みモデルとリアルタイムトレースを使用して、エージェントの動作を監視します。
  • 組み込みチャット UI ：会話エージェントテンプレートには、ストリーミング、認証、永続的な履歴を備えたすぐに使えるチャットインターフェースが含まれています。

要件​

移行テンプレートを複製します​

移行テンプレートは、Databricks Appsでエージェントを開発およびデプロイするための足場を、AIコーディングアシスタントに各移行**ステップ**の実行方法を教えるエージェントスキルファイルとともに提供します。

テンプレートをクローンして、フォルダに移動します。

Bash
git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-migration-from-model-serving

テンプレートフォルダーには、次のものが含まれます。

  • AGENTS.md: 移行ワークフローを説明するAIコーディングアシスタント向けの手順
  • skills/：移行の各ステップ用のスキルファイル。アシスタントによって順番に実行されます。
  • agent_server/ターゲット Databricks Apps エージェントのスカフォールディング（@invoke() および @stream() ハンドラーのプレースホルダー コードを使用）です。
  • databricks.yml：プレースホルダーのリソース宣言を含む宣言型オートメーションバンドル構成テンプレート。

AIアシスト付き移行 (推奨)​

AI アシストによる移行は、このテンプレートを使用するための推奨される方法です。AI コーディング アシスタントは AGENTS.md とスキルファイルを読み取り、コードと構成の変更を自動的に処理します。

  1. Cursor、GitHub Copilot、またはClaudeなどのAIコーディングアシスタントでテンプレートフォルダーを開いてください。
  2. アシスタントに、エンドポイント名を提供して移行を実行してもらうよう依頼してください：
Prompt
"Migrate my Model Serving endpoint `my-agent-endpoint` to a Databricks App"
  1. アシスタントは移行計画を生成し、各ステップを実行します：

AIコーディングアシスタントが、Model Serving から Databricks Apps へのエージェント移行のためのステップバイステップのTODOリストを表示しているスクリーンショット。

手動移行​

Databricks では、移行を実行するために AI コーディングアシスタントを使用することをお勧めします。AI コーディングアシスタントを使用せずに移行する場合は、次の高レベルのステップでそのプロセスを説明します。

重要

これらのステップは概要であり、ステートフルエージェント、非同期と同期のトレードオフ、Unity Catalog アーティファクトアクセス、複雑なリソース設定など、すべての移行シナリオを網羅しているわけではありません。

AIコーディングアシスタントを使用して移行を支援するか、テンプレートのmigrate-from-model-servingスキルで詳細情報を参照してください。

ステップ1. エージェントアーティファクトをダウンロード​

  1. エンドポイントからモデル名とバージョンを取得します。
Bash
databricks serving-endpoints get <endpoint-name> --output json
  1. 応答でserved_entities[0].entity_name（モデル名）とentity_versionを検索し、アーティファクトをダウンロードします。
Bash
DATABRICKS_CONFIG_PROFILE=<profile> uv run --no-project \
  --with "mlflow[databricks]>=2.15.0" \
  python3 << 'EOF'
import mlflow
mlflow.set_tracking_uri("databricks")
mlflow.artifacts.download_artifacts(
    artifact_uri="models:/<model-name>/<version>",
    dst_path="./original_mlflow_model"
)
EOF

ダウンロードされたフォルダーには、以下が含まれます：

  • MLmodel — 元のエージェントのリソース宣言
  • code/ — エージェントのPythonソースファイル
  • artifacts/ — オプションの構成ファイルとプロンプト
  • input_example.json テスト用のサンプルリクエスト

ステップ 2. エージェントコードを移行する​

code/からagent_server/へすべてのPythonファイルをコピーし、artifacts/からagent_server/artifacts/へすべてのアーティファクトをコピーします。

ファイルの移動後、新しいフォルダ構造を反映するように、相対インポートとハードコードされたファイルパスを更新してください。次に、ステップ3で示されているパターンを使用するようにagent_server/agent.pyを書き換えます。

ステップ 3: エージェントコードを変換する​

Model Serving では、エージェントは predict() および predict_stream() メソッドを持つクラスベースの ResponsesAgent を使用します。Databricks Apps では、MLflow AgentServer は @invoke() および @stream() で装飾されたモジュールレベルの関数を提供します。

移行時に、次のいずれかのパターンを選択します。

  • **非同期 (推奨)**: Pythonasync def およびawait を使用して、複数のリクエストを同時に処理します。1つのリクエストがLLMの応答を待っている間、サーバーは他のリクエストを処理します。
  • 同期 ：Model Servingエージェントから同期Pythonパターンを維持します。最小限の移行の場合、またはコードが同期専用のライブラリに依存している場合は、こちらを選択してください。

元のクラスベースのエージェントの構造。

Python
from mlflow.pyfunc import ResponsesAgent, ResponsesAgentRequest, ResponsesAgentResponse

class MyAgent(ResponsesAgent):
  def predict(self, request: ResponsesAgentRequest, params=None) -> ResponsesAgentResponse:
    # Synchronous implementation
    ...
    return ResponsesAgentResponse(output=outputs)

  def predict_stream(self, request: ResponsesAgentRequest, params=None):
    # Synchronous generator
    for chunk in ...:
      yield ResponsesAgentStreamEvent(...)

ステップ4. アプリをセットアップする​

依存関係をインストールし、クイックスタートスクリプトを実行して、認証を設定し、MLflowエクスペリメントを作成し、.envファイルを生成します。

ステップ 5. ローカルでテストする​

アプリサーバーを起動し、エージェントが正しく応答することを確認してからデプロイしてください。

元のinput_example.jsonを使用してcurlでテストし、エージェントが期待どおりに応答したらデプロイします。

ステップ 6: リソースを構成する​

Model Servingエージェントは、MLmodel ファイルでリソースを宣言します。Databricks Appsエージェントは、Declarative Automation Bundlesを使用して、databricks.yml 構成ファイルでリソースを宣言します。

AIエージェントの認証を参照してください。

リソース宣言を同等の宣言型オートメーションバンドルの形式にマッピングします。

MLmodel リソースタイプ

databricks.yml 同等

権限

serving_endpoint

serving_endpoint

CAN_QUERY

lakebase

database

CAN_CONNECT_AND_CREATE

vector_search_index

uc_securable (securable_type: TABLE)

SELECT

function

uc_securable (securable_type: FUNCTION)

EXECUTE

table

uc_securable (securable_type: TABLE)

SELECT または MODIFY

uc_connection

uc_securable (securable_type: CONNECTION)

USE_CONNECTION

sql_warehouse

sql_warehouse

CAN_USE

genie_space

genie_space

CAN_RUN

ステップ 7. 宣言型オートメーションバンドルを使用してエージェントをデプロイする​

宣言型オートメーションバンドルを使用して、エージェントをDatabricks Appsにデプロイします。

デプロイする前に、フォルダ構造が次のようになっていることを確認してください：

<working-directory>/
├── original_mlflow_model/    # Downloaded artifacts from Model Serving
│   ├── MLmodel
│   ├── code/
│   │   └── agent.py
│   ├── input_example.json
│   └── requirements.txt
│
└── <app-name>/               # New Databricks App (ready to deploy)
    ├── agent_server/
    │   ├── agent.py          # Migrated agent code
    │   └── ...
    ├── app.yaml
    ├── databricks.yml        # Bundle config with resources
    ├── pyproject.toml
    ├── requirements.txt
    └── ...
注記

アプリに pyproject.toml と uv.lock の両方が含まれている場合、Databricks Apps は uv を使用して依存関係をインストールします。requirements.txt も存在する場合は、そちらが優先され、代わりに pip が使用されます。uvを使用したPythonの依存関係の定義を参照してください。

  1. バンドル構成を検証：

    Bash
    databricks bundle validate

  2. バンドルをワークスペースにデプロイします（bundle deployはファイルをアップロードしますが、アプリは起動しません）。

    Bash
    databricks bundle deploy

  3. アプリを起動：

    Bash
    databricks bundle run <app-resource-name>

追加のリソース​

エージェントの移行後、以下を参照してください:

このページの見出し