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

プレビュー

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

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

要件

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

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

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

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

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

deploy() APIは、次の処理を行います。

  • ユーザー向けアプリケーションに統合できる、エージェント用の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

構造体

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

依存リソースの認証

エージェントデプロイ用のモデルサービングエンドポイントを作成するとき、 Databricks は、エンドポイントの作成者がエージェントが依存するすべてのリソースにアクセスするアクセス許可を持っていることを確認します。

LangChain フレーバー エージェントの場合、依存リソースはエージェントの作成およびログ記録中に自動的に推論されます。これらのリソースは、 resources.yaml ファイルの記録済みモデル アーティファクトに記録されます。 デプロイ中に、 databricks.agents.deploy は、これらの推測されたリソース依存関係にアクセスして通信するために必要な M2M OAuth トークンを自動的に作成します。

PyFuncフレーバーのエージェントの場合、デプロイされたエージェントのロギング中に、resourcesパラメーターでリソースの依存関係を手動で指定する必要があります。PyFuncまたはLangChainエージェントのリソースの指定を参照してください。デプロイ中に、databricks.agents.deploy は resources パラメーターで指定されたリソースにアクセスできる M2M OAuth トークンを作成し、デプロイされたエージェントにデプロイします。

自動認証パススルー

次の表に、自動認証パススルーをサポートする機能を示します。 自動認証パススルーでは、デプロイ作成者の資格情報を使用して、サポートされている機能に対して自動的に認証します。

特徴量

最小 mlflow バージョン

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

mlflow 2.13.1 以降が必要です

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

mlflow 2.13.1 以降が必要です

SQLウェアハウス

mlflow 2.16.1以降が必要です

Unity Catalog 機能

mlflow 2.16.1以降が必要です

手動認証

自動認証パススルーをサポートしていない依存リソースがある場合、またはデプロイメント作成者の認証情報以外の認証情報を使用する場合は、 シークレットベースの環境変数を使用して認証情報を手動で提供できます。 たとえば、エージェントで 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 のリクエストに対するエージェントの応答が正確で、取得ツールによってフェッチされたコンテキストに基づいていることを示しています。