生成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 以降が必要です。

• 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() 関数は、デフォルトで次のアクションを実行します。

• CPU モデルサービング エンドポイントを作成して 、エージェントをユーザー向けアプリケーションに統合します。

• 推論テーブル が要求の入力と応答をログに記録することで、エージェントを監視およびデバッグできるようにします。

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

• エンドポイントで実行されているエージェント コードに 、有効期間の短いサービスプリンシパル credentials をプロビジョニング します。

  • Databricks は、 モデルのログ記録中に定義されたように、Databricks で管理されるリソースにアクセスするための最小限のアクセス許可を持つ有効期間の短い資格情報を自動的に提供します。
  • これらの認証情報を生成する前に、Databricks は、エンドポイントの所有者が特権昇格や不正アクセスを防ぐために必要な権限を持っていることを確認します。従属リソースの認証を参照してください。
  • Databricks で管理されていないリソースの依存関係がある場合は、シークレットを含む環境変数を deploy()に渡すことができます。「モデルサービングエンドポイントからリソースへのアクセスを設定する」を参照してください。

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

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

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

注記

デプロイが完了するまでに最大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 APIs とリソースにアクセスできるようにします。
3. 手動認証: エージェントのデプロイ中に、有効期間の長い資格情報を手動で指定します。 自動認証パススルーをサポートしていない Databricks リソース、または外部 API アクセスには、手動認証を使用します。

自動認証パススルー

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

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

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

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

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

注記

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

3. 資格情報のプロビジョニングとローテーション : サービスプリンシパルの有効期間の短い資格情報 ( 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 推論テーブルを使用してデプロイされたエージェントをモニタリングできます。 推論テーブルには、レビューアプリからのリクエスト、レスポンス、エージェントトレース、エージェントフィードバックの詳細なログが含まれています。 この情報により、問題のデバッグ、パフォーマンスの監視、オフライン評価用のゴールデンデータセットの作成が可能になります。

推論テーブルを使用してデプロイされたエージェントを監視するを参照してください。

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

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

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

追加のリソース

• デプロイされた Mosaic AI エージェントのクエリ
• Mosaic AIエージェント評価とは?
• レビューアプリを使用して、生成AIアプリの人間によるレビューを行います