メインコンテンツまでスキップ

生成AI アプリケーション用のエージェントをデプロイする

この記事では、 Agent Framework Python API のdeploy() 関数を使用して 、AI エージェント を Mosaic AI Model Servingにデプロイする方法を示します。

Mosaic AI Model Serving にエージェントをデプロイすると、次のような利点があります。

  • モデルサービングは、オートスケール、ロギング、バージョン管理、アクセス制御を管理し、高品質なエージェントの開発に集中することができます。
  • 対象分野の専門家は、レビューアプリを使用して、デプロイされたエージェントと対話し、モニタリングと評価に組み込むフィードバックを提供できます。
  • エージェントは、ライブトラフィックで評価を実行することで監視できます。ユーザートラフィックにはグラウンドトゥルースは含まれませんが、LLM の審査員 (および作成したカスタムメトリクス) は教師なし評価を実行します。

必要条件​

  • databricks.agentsのdeploy() APIを使用してエージェントをデプロイするには、MLflow 2.13.1以上が必要です。

  • AI エージェントを Unity Catalogに登録します。 エージェントを Unity Catalog に登録するを参照してください。

  • Databricks ノートブックの外部からエージェントをデプロイするには databricks-agents SDK バージョン 0.12.0 以降が必要です。

  • エンドポイント作成者 (エージェントをデプロイするユーザー) は、デプロイ時に推論テーブルを格納するために選択された Unity Catalog スキーマに対する CREATE VOLUME アクセス許可を持っている必要があります。これにより、関連する評価テーブルとログ記録テーブルをスキーマに作成できます。推論テーブルの有効化と無効化を参照してください。

  • databricks-agents SDK をインストールします。

    Python
    %pip install databricks-agents
    dbutils.library.restartPython()

エージェントのデプロイ deploy()​

deploy() を使用して、エージェントをモデルサービングエンドポイントにデプロイします。

Python
from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

deploy() 関数は、デフォルトで次のアクションを実行します。

deploy() 操作

説明

Create CPU モデルサービング エンドポイント

エージェントをモデルサービング エンドポイント経由で提供することにより、ユーザー向けアプリケーションからエージェントにアクセスできるようにします。

プロビジョニング short-lived サービスプリンシパル credentials

Databricks は、 モデルのログ記録時に定義された Databricks マネージド リソースにアクセスするための最小限のアクセス許可を持つ、有効期間の短い資格情報を自動的に提供します。

Databricks は、資格情報を発行する前に、エンドポイントの所有者が必要なアクセス許可を持っていることを確認し、特権の昇格や不正アクセスを防ぎます。従属リソースの認証を参照してください。

エージェントが Databricks で管理されていないリソースに依存している場合は、シークレットを含む環境変数を deploy()に渡すことができます。「モデルサービングエンドポイントからリソースへのアクセスを設定する」を参照してください。

レビューアプリを有効にする

利害関係者がエージェントと対話し、フィードバックを提供できるようにします。「レビュー アプリを使用して、AI 世代のアプリを人間がレビューする」を参照してください。

推論テーブルを有効にする

エージェントを監視およびデバッグするには、要求の入力と応答をログに記録します。

  • ChatAgent エージェントと ChatModel エージェントの場合、推論テーブルは AI Gateway で有効になります。
  • ストリーミング応答ログの場合、 ChatAgent と ChatCompletion と互換性のあるフィールドとトレースのみが集約されます。

REST API 要求のログ記録とアプリのフィードバックの確認

API 要求とフィードバックを推論テーブルに記録します。

  • レビューアプリからのフィードバックを受け入れてログに記録するための フィードバックモデルを作成します 。
  • このモデルは、デプロイされたエージェントと同じ CPU モデルサービングエンドポイントで提供されます。

Lake House モニタリング for Gen AI (beta) を有効にする

Gen AIベータ版のレイクハウスモニタリングへの登録が必要です。基本モニタリングは、デプロイされたエージェントトレースに対して自動的に有効になります。

MLflow 3 (beta) でリアルタイム トレースとモニタリングを有効にする

Gen AIベータ版のレイクハウスモニタリングへの登録と、MLflow 3.0以上の利用が必要です。

Databricks は、デプロイされたエージェントからのトレースを推論テーブルにログ記録して長期保存するだけでなく、デプロイされたエージェントからのトレースを MLflow エクスペリメントにログに記録し、リアルタイムの可視性を確保します。これにより、モニタリングとデバッグのレイテンシーが短縮されます。

  • agents.deploy()を使用して新しいエンドポイントを作成すると、モニタリングとトレースは、現在アクティブなMLflowエクスペリメントからの読み取りと書き込みで構成されます。

  • 特定のエンドポイントのエクスペリメントを設定するには、agents.deploy()を呼び出してエンドポイントを作成する前に mlflow.set_experiment() を呼び出します。

  • エンドポイントで提供されているすべてのエージェント ( agents.deploy()への後続の呼び出しによってエンドポイントに追加されたエージェントを含む) からのトレースは、このエクスペリメントに書き込まれます。

  • モニタリング コンピュート quality メトリクス on traces in this エクスペリメント.

  • デフォルトでは、basic モニタリング メトリクスのみが設定されています。 LLM審査員などを追加するには、「モニタリングを設定する」を参照してください。

注記

デプロイが完了するまでに最大15分かかる場合があります。未加工のJSONペイロードは到着するまでに10〜30分かかり、フォーマットされたログは未加工のペイロードから約1時間ごとに処理されます。

デプロイのカスタマイズ​

デプロイメントをカスタマイズするには、追加の引数を deploy()に渡します。たとえば、アイドル状態のエンドポイントに対して 0 へのスケールを有効にするには、 scale_to_zero_enabled=True.これにより、コストは削減されますが、初期クエリの処理にかかる時間が長くなります。

その他のパラメーターについては、「 Databricks Agents Python API」を参照してください。

エージェントのデプロイメントの取得と削除​

既存のエージェント・デプロイメントを取得または管理します。

Python
from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

依存リソースの認証​

AIエージェントは、タスクを完了するために他のリソースに対して認証を必要とすることがよくあります。 たとえば、エージェントは、非構造化データをクエリするためにベクトル検索インデックスにアクセスする必要がある場合があります。

エージェントは、モデルサービングエンドポイントの背後でリソースを提供するときに、依存リソースに対して認証するために、次のいずれかの方法を使用できます。

  1. 自動認証パススルー: ログ記録中にエージェントの Databricks リソースの依存関係を宣言します。 Databricks は、エージェントがデプロイされるときに、リソースに安全にアクセスするために、有効期間の短い資格情報を自動的にプロビジョニング、ローテーション、管理できます。 Databricks では、可能な限り自動認証パススルーを使用することをお勧めします。
  2. On-behalf-of-user authentication: エージェントのエンドユーザー認証情報を使用して、 Databricks REST API とリソースにアクセスできるようにします。
  3. 手動認証: エージェントのデプロイ中に、有効期間の長い資格情報を手動で指定します。 自動認証パススルーをサポートしていない Databricks リソース、または外部 API アクセスには、手動認証を使用します。

自動認証パススルー​

モデルサービングは、エージェントが使用する最も一般的なタイプの Databricks リソースの自動認証パススルーをサポートしています。

自動認証パススルーを有効にするには、 エージェントのログ記録中に依存関係を指定する必要があります。

その後、エンドポイントの背後にあるエージェントにサービスを提供すると、Databricks は次の手順を実行します。

  1. 権限の確認: Databricks は、エンドポイント作成者がエージェントのログ記録中に指定されたすべての依存関係にアクセスできることを確認します。

  2. サービスプリンシパルの作成と権限付与 : エージェント モデル バージョンに対してサービスプリンシパルが作成され、エージェント リソースへの読み取りアクセスが自動的に付与されます。

注記

システムによって生成されたサービスプリンシパルは、 API またはUIリストに表示されません。 エージェント・モデル・バージョンがエンドポイントから削除されると、サービスプリンシパルも削除されます。

  1. 資格情報のプロビジョニングとローテーション : サービスプリンシパルの有効期間の短い資格情報 ( M2M OAuth トークン) がエンドポイントに挿入され、エージェント コードが Databricks リソースにアクセスできるようになります。 また、Databricks は資格情報をローテーションし、エージェントが依存リソースに継続的かつ安全にアクセスできるようにします。

この認証動作は、 Databricks ダッシュボードの "所有者として実行" 動作と似ています - Unity Catalog テーブルなどのダウンストリーム リソースは、依存リソースへの最小特権アクセス権を持つサービスプリンシパルの資格情報を使用してアクセスされます。

次の表に、自動認証パススルーをサポートする Databricks リソースと、エージェントをデプロイするときにエンドポイント作成者に必要なアクセス許可を示します。

注記

Unity Catalog リソースには、親スキーマのUSE SCHEMAと親カタログのUSE CATALOGも必要です。

リソースタイプ

権限

SQLウェアハウス

エンドポイントを使用

モデルサービングエンドポイント

Can Query

Unity Catalog 関数

EXECUTE

Genieスペース

Can Run

ベクトル検索インデックス

Can Use

Unity Catalog テーブル

SELECT

ユーザー代理認証​

ユーザー代理認証により、エージェント開発者は、エージェントのエンド ユーザー資格情報を使用して機密性の高い Databricks リソースにアクセスできます。 リソースへのユーザー代理アクセスを有効にするには、次の 2 つの手順があります。

  1. エージェント コードで、ユーザー代理認証が有効になっているクライアントで Databricks リソースにアクセスしていることを確認します。詳細については 、「On-behalf-of-user authentication 」を参照してください。
  2. エージェントのロギング時に、エージェントに必要なエンドユーザーのREST APIスコープ( vectorsearch.vector-search-endpointsなど)を指定します。その後、エージェントがデプロイされると、エージェントはエンドユーザーの代わりに Databricks リソースにアクセスできますが、指定されたスコープを使用する必要があります。APIスコープの詳細については、「ユーザー代理認証」を参照してください。

手動認証​

シークレットベースの環境変数を使用して、認証情報を手動で提供することもできます。手動認証は、次のシナリオで役立ちます。

  • 依存リソースは、自動認証パススルーをサポートしていません。
  • エージェントが外部リソースまたは API にアクセスしています。
  • エージェントは、エージェントデプロイヤの認証情報以外の認証情報を使用する必要があります。

たとえば、エージェントで Databricks SDK を使用して他の依存リソースにアクセスするには、 Databricks クライアント統合認証で説明されている環境変数を設定できます。

デプロイされたエージェントの監視​

エージェントが Databricks モデルサービングにデプロイされた後、 AI Gateway 推論テーブルを使用してデプロイされたエージェントをモニタリングできます。 推論テーブルには、レビューアプリからのリクエスト、レスポンス、エージェントトレース、エージェントフィードバックの詳細なログが含まれています。 この情報により、問題のデバッグ、パフォーマンスの監視、オフライン評価用のゴールデンデータセットの作成が可能になります。

「MLflow トレースの表示」を参照してください。

デプロイされたアプリケーションを取得する​

配備されたエージェントを取得する方法を以下に示します。

Python
from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

deployments = list_deployments()
# Print all the current deployments
deployments

デプロイされたエージェントに関するフィードバックを提供する (実験的)​

agents.deploy()を使用してエージェントをデプロイすると、エージェントフレームワークは同じエンドポイント内に「フィードバック」モデルバージョンも作成およびデプロイし、エージェントアプリケーションに関するフィードバックを提供するためにクエリを実行できます。フィードバックエントリは、エージェントサービスエンドポイントに関連付けられた 推論テーブル 内のリクエスト行として表示されます。

この動作は 実験的なものであり、Databricks は将来、デプロイされたエージェントに関するフィードバックを提供するためのファーストクラス API を提供する可能性があり、将来の機能ではこの API への移行が必要になる可能性があることに注意してください。

この API の制限事項は次のとおりです。

  • フィードバック API には入力検証がありません - 無効な入力が渡された場合でも、常に正常に応答します。
  • フィードバック API では、フィードバックを提供するエージェント エンドポイント要求の Databricks によって生成された request_id を渡す必要があります。 databricks_request_idを取得するには、エージェント サービス エンドポイントへの元の要求に {"databricks_options": {"return_trace": True}} を含めます。エージェント エンドポイントの応答には、要求に関連付けられている databricks_request_id が含まれるため、エージェントの応答に関するフィードバックを提供するときに、その要求 ID をフィードバック API に戻すことができます。
  • フィードバックは推論テーブルを使用して収集されます。 推論テーブルの制限を参照してください。

次の要求例では、"your-agent-endpoint-name" という名前のエージェント エンドポイントに関するフィードバックを提供し、 DATABRICKS_TOKEN 環境変数が Databricks REST API トークンに設定されていることを前提としています。

Bash
curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about DLT"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

text_assessments.ratings フィールドと retrieval_assessments.ratings フィールドに追加のキーと値のペアまたは異なるキーと値のペアを渡して、さまざまな種類のフィードバックを提供できます。この例では、フィードバックペイロードは、ID が 573d4a61-4adb-41bd-96db-0ec8cebc3744 のリクエストに対するエージェントの応答が正確で、取得ツールによってフェッチされたコンテキストに基づいていることを示しています。

追加のリソース​

に最終更新