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

[アーティクル]
02/04/2025

重要

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

要件

deploy() の databricks.agents API を使用してエージェントをデプロイするには、MLflow 2.13.1 以降が必要です。
AI エージェントを Unity Catalog に登録します。「Unity Catalog にチェーンを登録する」をご覧ください。
Databricks ノートブックの外部からエージェントをデプロイするには、databricks-agents SDK バージョン 0.12.0 以降が必要です。

databricks-agents SDK をインストールする。

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

`deploy()` を使用してエージェントをデプロイする

deploy()関数は次の処理を行います。

ユーザー向けアプリケーションに統合できる、エージェントの CPU モデルサービングエンドポイントを作成します。
- アイドル状態のエンドポイントのコストを削減するために (初期クエリの処理にかかる時間の増加を犠牲にして)、 scale_to_zero_enabled=True を deploy()に渡すことで、サービスエンドポイントのスケールをゼロにできます。エンドポイントのスケーリングの期待を参照してください。
- エンドポイントを提供するモデルで AI Gateway を使用して推論テーブルを有効にします。 AI ゲートウェイ対応推論テーブルを使用して提供されるモデルを監視するを参照してください。
Note

ストリーミング応答ログの場合、ChatCompletion と互換性のあるフィールドとトレースのみが集計されます。
- Databricks は、エンドポイントで実行されているエージェントコードに、有効期間の短いサービスプリンシパル資格情報を自動的に提供します。モデルのログ記録時に定義されたように、資格情報には Databricks が管理するリソースにアクセスするための最小限のアクセス許可があります
  。これらの資格情報を生成する前に、Databricks は、エンドポイント所有者が特権エスカレーションと未認可のアクセスを防ぐための適切なアクセス許可を持っていることを確認します。「依存リソースの認証」を参照してください。
  - たとえば Pinecone の使用など、Databricks で管理されないリソース依存関係がある場合は、シークレットを含む環境変数を deploy() API に渡すことができます。「モデル提供エンドポイントからリソースへのアクセスを構成する」を参照してください。
エージェントのレビューアプリを有効にします。レビューアプリを使うと、関係者はレビューアプリ UI を使ってエージェントとチャットし、フィードバックを提供できます。
レビューアプリまたは REST API に対するすべての要求を推論テーブルにログします。ログされるデータには、クエリ要求、応答、および MLflow Tracing からの中間トレースデータが含まれます。
デプロイしようとしているエージェントと同じカタログとスキーマを持つフィードバックモデルを作成します。このフィードバックモデルは、レビューアプリからのフィードバックを受け取り、それを推論テーブルにログすることを可能にするメカニズムです。このモデルは、デプロイされたエージェントと同じ CPU モデル提供エンドポイント内で提供されます。この提供エンドポイントでは推論テーブルが有効になっているため、レビューアプリからのフィードバックを推論テーブルへログすることが可能です。

Note

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


from databricks.agents import deploy
from mlflow.utils import databricks_utils as du

deployment = deploy(model_fqn, uc_model_info.version)

# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint

# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url

エージェント拡張推論テーブル

deploy() では、エージェントサービスエンドポイントとの間で要求と応答をログするために、デプロイごとに 3 つの推論テーブルが作成されます。ユーザーは、デプロイを操作してから 1 時間以内にデータがペイロードテーブルに反映されます。

ペイロード要求ログと評価ログの設定には時間がかかる場合がありますが、最終的には生のペイロードテーブルから派生します。ペイロードテーブルから要求と評価のログを自分で抽出できます。ペイロードテーブルの削除と更新は、ペイロード要求ログまたはペイロード評価ログには反映されません。

Note

Azure Storage ファイアウォールを有効にしている場合は、Databricks アカウントチームに連絡して、エンドポイントの推論テーブルを有効にします。

テーブル	Unity Catalog テーブル名の例	各テーブルの内容
Payload	`{catalog_name}.{schema_name}.{model_name}_payload`	生の JSON 要求と応答のペイロード
ペイロード要求ログ	`{catalog_name}.{schema_name}.{model_name}_payload_request_logs`	フォーマット化された要求と応答、MLflow トレース
ペイロード評価ログ	`{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs`	レビューアプリで提供されているフォーマット化されたフィードバック (要求ごと)

以下は、要求ログテーブルのスキーマです。

列名	種類	説明
`client_request_id`	String	クライアント要求 ID (通常は `null`)。
`databricks_request_id`	String	Databricks 要求 ID。
`date`	日	要求の日付。
`timestamp_ms`	Long	ミリ秒で表されたタイムスタンプ。
`timestamp`	タイムスタンプ	要求のタイムスタンプ。
`status_code`	Integer	エンドポイントの状態コード。
`execution_time_ms`	Long	合計実行時間 (ミリ秒)。
`conversation_id`	String	要求ログから抽出された会話 ID。
`request`	String	ユーザーの会話からの最後のユーザークエリ。これは RAG 要求から抽出されます。
`response`	String	ユーザーへの最後の応答。これは RAG 要求から抽出されます。
`request_raw`	String	要求の文字列表現。
`response_raw`	String	応答の文字列表現。
`trace`	String	応答構造体の `databricks_options` から抽出されたトレースの文字列表現。
`sampling_fraction`	倍精度浮動小数点型	サンプリングの割合。
`request_metadata`	Map[String, String]	要求に関連付けられたモデルサービスエンドポイントに関連するメタデータのマップ。このマップには、エンドポイントに使用されるエンドポイント名、モデル名、およびモデルバージョンが含まれています。
`schema_version`	String	スキーマバージョンを示す整数。

以下は、評価ログテーブルのスキーマです。

列名	種類	説明
`request_id`	String	Databricks 要求 ID。
`step_id`	String	取得評価から派生します。
`source`	構造体	評価を作成したユーザーに関する情報を含む構造体フィールド。
`timestamp`	タイムスタンプ	要求のタイムスタンプ。
`text_assessment`	構造体	レビューアプリからのエージェントの応答に関するフィードバックのデータを含む構造体フィールド。
`retrieval_assessment`	構造体	応答用に取得されたドキュメントに関するフィードバックのデータを含む構造体フィールド。

依存リソースの認証

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

モデルサービングエンドポイントの内側で提供されているエージェントは、次のいずれかの方法を使って、依存リソースに対する認証を行うことができます。

自動認証パススルー: ログの間に、エージェントに対して Databricks リソースの依存関係を宣言します。リソースに対してセキュリティ保護されたアクセスを行うようにエージェントがデプロイされていると、Databricks は有効期間の短い資格情報を自動的にプロビジョニング、ローテーション、管理できます。 Databricks では、可能な場合は自動認証パススルーを使うことをお勧めします。
手動認証: エージェントのデプロイ時に、有効期間の長い資格情報を手動で指定します。自動認証パススルーをサポートしていない Databricks リソースまたは外部 API アクセスの場合は、手動認証を使います。

自動認証パススルー

Model Serving では、エージェントによって使われる最も一般的な種類の Databricks リソースについて、自動認証パススルーがサポートされています。

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

その後、エンドポイントの内側でエージェントを提供すると、Databricks は次の手順を実行します。

アクセス許可の検証: Databricks は、エージェントのログの間に指定されたすべての依存関係に、エンドポイント作成者がアクセスできることを確認します。
サービスプリンシパルの作成と許可: サービスプリンシパルがエージェントモデルのバージョンに対して作成されて、エージェントリソースへの読み取りアクセスを自動的に許可されます。

Note

システムによって生成されたサービスプリンシパルは、API または UI の一覧には表示されません。エージェントモデルのバージョンがエンドポイントから削除されると、サービスプリンシパルも削除されます。
資格情報のプロビジョニングとローテーション: サービスプリンシパルの有効期間が短い資格情報 (M2M OAuth トークン) がエンドポイントに挿入されて、エージェントのコードが Databricks のリソースにアクセスできるようになります。また、Databricks によって資格情報のローテーションが行われ、エージェントは依存リソースへのセキュリティ保護されたアクセスを確実に継続できます。

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

次の表は、自動認証パススルーをサポートしている Databricks リソースと、エージェントのデプロイ時にエンドポイント作成者が持っている必要のあるアクセス許可の一覧です。

Note

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

リソースの種類	権限
SQL ウェアハウス	エンドポイントの使用
モデルサービングエンドポイント	クエリ可能
Unity カタログ関数	EXECUTE
Genie スペース	実行可能
ベクトル検索インデックス	使用可能
Unity カタログテーブル	SELECT

手動認証

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

依存リソースが、自動認証パススルーをサポートしていません。
エージェントが外部のリソースまたは API にアクセスしています。
エージェントで、エージェントをデプロイしたユーザーのものとは異なる資格情報を使う必要があります。

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

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

デプロイされたエージェントを取得する方法は、次のとおりです。

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()を使用してエージェントをデプロイすると、エージェントフレームワークは同じエンドポイント内に "フィードバック" モデルバージョンを作成してデプロイします。このバージョンでは、クエリを実行してエージェントアプリケーションに関するフィードバックを提供できます。フィードバックエントリは、エージェントサービスエンドポイントに関連付けられている inference テーブル内の要求行として表示されます。

この動作は experimental: 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 トークンに設定されていることを前提としています。

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 Delta Live Tables"
                      }
                  ],
                  "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 を持つ要求に対するエージェントの応答が、取得ツールによってフェッチされたコンテキストで正しく、正確で、接地されていることを示しています。

次の方法で共有

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

要件

`deploy()` を使用してエージェントをデプロイする

エージェント拡張推論テーブル

依存リソースの認証

自動認証パススルー

手動認証

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

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

その他のリソース

フィードバック

その他のリソース

次の方法で共有

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

要件

deploy() を使用してエージェントをデプロイする

エージェント拡張推論テーブル

依存リソースの認証

自動認証パススルー

手動認証

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

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

その他のリソース

フィードバック

その他のリソース

`deploy()` を使用してエージェントをデプロイする