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

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

要件

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

• AI エージェントを Unity Catalog に登録します。 「エージェントを Unity カタログに登録する」を参照してください。

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

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 時間以内にデータがペイロード テーブルに反映されます。

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

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

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

依存リソースの認証

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

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

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

自動認証パススルー

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

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

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

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

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

   Note

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

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

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

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

手動認証

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

• 依存リソースは、自動認証パススルーをサポートしていません。
• エージェントが外部リソースまたは 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 を持つ要求に対するエージェントの応答が、取得ツールによってフェッチされたコンテキストで正しく、正確で、接地されていることを示しています。

その他のリソース

• Mosaic AI エージェント評価とは？
• エージェント アプリケーションの品質に関するフィードバックを得る