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

プレビュー

この機能はパブリックプレビュー段階です。

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

要件

  • databricks.agentsのdeploy() 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モデルサービングエンドポイントを作成します。

  • エージェントのレビュー アプリ を有効にします。 レビューアプリを使用すると、関係者はレビューアプリのUIを使用してエージェントとチャットし、フィードバックを提供できます。

  • レビューアプリまたは REST API へのすべてのリクエストを推論テーブルに記録します。 ログに記録されるデータには、クエリ要求、応答、 MLflow トレースからの中間トレース データが含まれます。

  • デプロイしようとしているエージェントと同じカタログとスキーマを持つフィードバックモデルを作成します。 このフィードバックモデルは、レビューアプリからのフィードバックを受け入れ、それを推論テーブルに記録することを可能にするメカニズムです。 このモデルは、デプロイされたエージェントと同じ CPU モデルサービングエンドポイントで提供されます。 この配信エンドポイントでは推論テーブルが有効になっているため、レビューアプリからのフィードバックを推論テーブルに記録できます。

注：

デプロイが完了するまでに最大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 時間以内にデータがペイロード テーブルに格納されることを期待できます。

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

TABLE

Unity Catalogテーブル名の例

各テーブルの内容

ペイロード

{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

Date

リクエストの日付。

timestamp_ms

Long

タイムスタンプ (ミリ秒単位)。

timestamp

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

応答 Struct の databricks_options から抽出されたトレースの文字列表現。

sampling_fraction

Double

サンプリング分数。

request_metadata

Map[文字列, 文字列]

要求に関連付けられたモデルサービングエンドポイントに関連するメタデータのマップ。 このマップには、エンドポイントに使用されているエンドポイント名、モデル名、およびモデル バージョンが含まれています。

schema_version

String

スキーマ バージョンの整数。

評価ログ テーブルのスキーマを次に示します。

列名

タイプ

説明

request_id

String

Databricks 要求 ID。

step_id

String

検索評価から導き出されます。

source

構造体

評価を作成したユーザーに関する情報を含む構造体フィールド。

timestamp

Timestamp

要求のタイムスタンプ。

text_assessment

構造体

レビューアプリからのエージェントの応答に関するフィードバックのデータを含む構造体フィールド。

retrieval_assessment

構造体

応答のために取得されたドキュメントに関するフィードバックのデータを含む構造体フィールド。

依存リソースの認証

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

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

  1. 自動認証パススルー: ログ記録中にエージェントの Databricks リソースの依存関係を宣言します。 Databricks は、エージェントがデプロイされるときに、リソースに安全にアクセスするために、有効期間の短い資格情報を自動的にプロビジョニング、ローテーション、管理できます。 Databricks では、可能な限り自動認証パススルーを使用することをお勧めします。

  2. 手動認証: エージェントのデプロイ中に、有効期間の長い資格情報を手動で指定します。 自動認証パススルーをサポートしていない Databricks リソース、または外部 API アクセスには、手動認証を使用します。

自動認証パススルー

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

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

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

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

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

    注：

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

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

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

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

注：

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

リソースタイプ

権限

SQLウェアハウス

エンドポイントを使用

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

CAN QUERY

Unity Catalog 機能

実行する

Genieスペース

実行可能

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

使用可能

Unity Catalog テーブル

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

この動作は 実験的なものであり、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 のリクエストに対するエージェントの応答が正確で、取得ツールによってフェッチされたコンテキストに基づいていることを示しています。