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

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

モザイク 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 カタログ スキーマに対する CREATE VOLUME アクセス許可が必要です。 これにより、スキーマに関連する評価テーブルとログ テーブルを作成できます。 推論 テーブルの有効化と無効化を参照してください。

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

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

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

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

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()に追加の引数を渡します。 たとえば、アイドル状態のエンドポイントに対して 0 にスケールを有効にするには、 scale_to_zero_enabled=Trueを渡します。 これにより、コストは削減されますが、初期クエリを処理する時間が長くなります。

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

エージェントのデプロイを取得および削除する

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

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

自動認証パススルー

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

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

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

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

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

   注

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

3. 資格情報のプロビジョニングとローテーション: サービス プリンシパルの有効期間が短い資格情報 (M2M OAuth トークン) がエンドポイントに挿入されて、エージェントのコードが Databricks のリソースにアクセスできるようになります。 また、Databricks によって資格情報のローテーションが行われ、エージェントは依存リソースへのセキュリティ保護されたアクセスを確実に継続できます。

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

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

ユーザー代理認証

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

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

手動認証

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

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

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

デプロイされたエージェントを監視する

エージェントが Databricks Model Serving にデプロイされたら、AI Gateway 推論テーブルを使用して、デプロイされたエージェントを監視できます。 推論テーブルには、レビュー アプリからの要求、応答、エージェント トレース、エージェントフィードバックの詳細なログが含まれています。 この情報を使用すると、問題のデバッグ、パフォーマンスの監視、オフライン評価用のゴールデン データセットの作成を行うことができます。

「 デバッグ」および「トレースを使用してアプリを観察する」を参照してください。

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

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

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

Databricks Agents Python API を参照してください。

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

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

この動作は実験的です: 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 Lakeflow Declarative Pipelines"
                      }
                  ],
                  "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 エージェントのクエリを実行する
• Mosaic AI Agent Evaluation (MLflow 2)
• Gen AI アプリの人間によるレビューにレビュー アプリを使用する (MLflow 2)
• デプロイされた AI エージェントをデバッグする