生成 AI アプリケーション用のエージェントをデプロイする
重要
この機能はパブリック プレビュー段階にあります。
この記事では、deploy() から databricks.agents API を使用して AI エージェントを配置する方法について説明します。
要件
databricks.agentsのdeploy()API を使用してエージェントをデプロイするには、MLflow 2.13.1 以降が必要です。AI エージェントを Unity Catalog に登録します。 「チェーンを Unity Catalog に登録する」を参照してください。
databricks-agentsSDK をインストールする。%pip install databricks-agents dbutils.library.restartPython()
deploy() を使用してエージェントをデプロイする
deploy() API では以下が実行されます。
- ユーザー向けアプリケーションに統合できる、エージェントの CPU モデル サービング エンドポイントを作成します。
- これらのモデル提供エンドポイントでは、推論テーブルが有効にされます。 「モデルの監視とデバッグのための推論テーブル」を参照してください。
- 認証資格情報は、モデルをログ記録する際に指定対象として、エージェントから要求されるすべての Databricks 管理対象リソースに自動的に渡されます。 Databricks はこれらのリソースにアクセスできるサービス プリンシパルを作成し、エンドポイントに自動的に渡します。 「依存リソースの認証」を参照してください。
- たとえば Pinecone を使用しているなど、Databricks で管理されていないリソース依存関係がある場合は、シークレットを含む環境変数を
deploy()API に渡すことができます。 「モデル提供エンドポイントからリソースへのアクセスを構成する」を参照してください。
- これらのモデル提供エンドポイントでは、推論テーブルが有効にされます。 「モデルの監視とデバッグのための推論テーブル」を参照してください。
- エージェントのレビュー アプリを有効にします。 レビュー アプリを使用すると、関係者はレビュー アプリ UI を使用してエージェントとチャットし、フィードバックを提供できます。
- レビュー アプリまたは REST API に対するすべての要求を推論テーブルにログします。 ログされるデータには、クエリ要求、応答、および MLflow Tracing からの中間トレース データが含まれます。
- デプロイしようとしているエージェントと同じカタログとスキーマを持つフィードバック モデルを作成します。 このフィードバック モデルは、レビュー アプリからのフィードバックを受け取り、それを推論テーブルにログすることを可能にするメカニズムです。 このモデルは、デプロイされたエージェントと同じ CPU モデル提供エンドポイント内で提供されます。 この提供エンドポイントでは推論テーブルが有効になっているため、レビュー アプリからのフィードバックを推論テーブルへログすることが可能です。
Note
デプロイの完了までに最大で 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 時間以内にデータがペイロード テーブルに反映されます。
ペイロード要求ログと評価ログの設定には時間がかかる場合がありますが、最終的には生のペイロード テーブルから派生します。 ペイロード テーブルから要求と評価のログを自分で抽出できます。 ペイロード テーブルの削除と更新は、ペイロード要求ログまたはペイロード評価ログには反映されません。
Note
Azure Storage ファイアウォールを有効にしている場合は、Databricks アカウント チームに連絡して、エンドポイントの推論テーブルを有効にします。
| テーブル | Unity Catalog テーブル名の例 | 各テーブルの内容 |
|---|---|---|
| Payload | {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 |
日 | 要求の日付。 |
timestamp_ms |
Long | ミリ秒で表されたタイムスタンプ。 |
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 | 応答構造体の databricks_options から抽出されたトレースの文字列表現。 |
sampling_fraction |
倍精度浮動小数点型 | サンプリングの割合。 |
request_metadata |
Map[String, String] | 要求に関連付けられたモデル サービス エンドポイントに関連するメタデータのマップ。 このマップには、エンドポイントに使用されるエンドポイント名、モデル名、およびモデル バージョンが含まれています。 |
schema_version |
String | スキーマ バージョンを示す整数。 |
以下は、評価ログ テーブルのスキーマです。
| 列名 | 種類 | 説明 |
|---|---|---|
request_id |
String | Databricks 要求 ID。 |
step_id |
String | 取得評価から派生します。 |
source |
構造体 | 評価を作成したユーザーに関する情報を含む構造体フィールド。 |
timestamp |
タイムスタンプ | 要求のタイムスタンプ。 |
text_assessment |
構造体 | レビュー アプリからのエージェントの応答に関するフィードバックのデータを含む構造体フィールド。 |
retrieval_assessment |
構造体 | 応答用に取得されたドキュメントに関するフィードバックのデータを含む構造体フィールド。 |
依存リソースの認証
エージェント デプロイ用のモデル サービング エンドポイントを作成するときに、Databricks は、エンドポイントの作成者がエージェント依存のすべてのリソースに対するアクセス許可を持っていることを確認します。
LangChain フレーバー エージェントの場合、依存リソースはエージェントの作成とログ時に自動的に推測されます。 これらのリソースは、ログされたモデル成果物内の resources.yaml ファイル内にログされます。 デプロイ時に、databricks.agents.deploy はこれらの推測リソースの依存関係にアクセスして通信するために必要な M2M OAuth トークンを自動的に作成します。
PyFunc フレーバー エージェントの場合、デプロイされたエージェントのログ中に、resources パラメーター内でリソースの依存関係をすべて手動で指定する必要があります。 PyFunc エージェントまたは LangChain エージェント Specify リソースを参照してください。
デプロイ時に、databricks.agents.deploy は resources パラメーター内で指定されたリソースにアクセスできる M2M OAuth トークンを作成し、それをデプロイされたエージェントにデプロイします。
自動認証パススルー
次の表に、自動パススルー認証をサポートする機能を示します。 自動認証パススルーでは、デプロイ作成者の認証情報を使用して、サポートされている機能に対して自動的に認証を行います。
| 機能 | 最小 mlflow バージョン |
|---|---|
| ベクトル検索インデックス | mlflow 2.13.1 以上が必要です。 |
| モデルの提供のエンドポイント | mlflow 2.13.1 以上が必要です。 |
| SQL ウェアハウス | mlflow 2.16.1 以上が必要です。 |
| Unity カタログ関数 | 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()を使用してエージェントをデプロイすると、エージェント フレームワークは同じエンドポイント内に "フィードバック" モデル バージョンを作成してデプロイします。このバージョンでは、クエリを実行してエージェント アプリケーションに関するフィードバックを提供できます。 フィードバック エントリは、エージェント サービス エンドポイントに関連付けられている 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 を持つ要求に対するエージェントの応答が、取得ツールによってフェッチされたコンテキストで正しく、正確で、接地されていることを示しています。