生成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モデルサービングエンドポイントを作成します。
アイドル状態のエンドポイントのコストを削減するために (初期クエリの処理時間が長くなります)、
scale_to_zero_enabled=True
をdeploy()
に渡すことで、サービス エンドポイントのスケールを 0 にすることができます。 「エンドポイントのスケーリングの期待」を参照してください。推論テーブルは、これらのモデルサービングエンドポイントで有効になります。 モニタリングモデルとデバッグモデルの推論テーブルを参照してください。
認証資格情報は、モデルのログ記録時に指定されたように、エージェントが必要とするすべての Databricks マネージド リソースに自動的に渡されます。 Databricks は、これらのリソースにアクセスできる サービスプリンシパル を作成し、それをエンドポイントに自動的に渡します。 従属リソースの認証を参照してください。
Pinecone を使用するなど、 Databricks管理されていないリソース依存関係がある場合は、シークレットを含む環境変数を
deploy()
APIに渡すことができます。 「モデルサービングエンドポイントからリソースへのアクセスを設定する」を参照してください。
エージェントのレビュー アプリ を有効にします。 レビューアプリを使用すると、関係者はエージェントとチャットし、レビューアプリの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テーブル名の例 |
各テーブルの内容 |
---|---|---|
ペイロード |
|
生の JSON 要求と応答のペイロード |
ペイロードリクエストログ |
|
書式設定されたリクエストと応答、MLflowトレース |
ペイロード評価ログ |
|
レビューアプリで提供されるフォーマットされたフィードバック(各リクエストに対して) |
次に、リクエストログテーブルのスキーマを示します。
列名 |
タイプ |
説明 |
---|---|---|
|
String |
クライアント要求 ID (通常は |
|
String |
Databricks 要求 ID。 |
|
Date |
リクエストの日付。 |
|
Long |
タイムスタンプ (ミリ秒単位)。 |
|
Timestamp |
要求のタイムスタンプ。 |
|
Integer |
エンドポイントのステータスコード。 |
|
Long |
合計実行時間 (ミリ秒)。 |
|
String |
要求ログから抽出された会話 ID。 |
|
String |
ユーザーの会話からの最後のユーザー クエリ。 これはRAGリクエストから抽出されます。 |
|
String |
ユーザーに対する最後の応答。 これはRAGリクエストから抽出されます。 |
|
String |
要求の文字列表現。 |
|
String |
応答の文字列表現。 |
|
String |
応答 Struct の |
|
Double |
サンプリング分数。 |
|
Map[文字列, 文字列] |
要求に関連付けられたモデルサービングエンドポイントに関連するメタデータのマップ。 このマップには、エンドポイントに使用されているエンドポイント名、モデル名、およびモデル バージョンが含まれています。 |
|
String |
スキーマ バージョンの整数。 |
評価ログ テーブルのスキーマを次に示します。
列名 |
タイプ |
説明 |
---|---|---|
|
String |
Databricks 要求 ID。 |
|
String |
検索評価から導き出されます。 |
|
構造体 |
評価を作成したユーザーに関する情報を含む構造体フィールド。 |
|
Timestamp |
要求のタイムスタンプ。 |
|
構造体 |
レビューアプリからのエージェントの応答に関するフィードバックのデータを含む構造体フィールド。 |
|
構造体 |
応答のために取得されたドキュメントに関するフィードバックのデータを含む構造体フィールド。 |
依存リソースの認証
エージェントデプロイ用のモデルサービングエンドポイントを作成するとき、 Databricks は、エンドポイントの作成者がエージェントが依存するすべてのリソースにアクセスするアクセス許可を持っていることを確認します。
LangChain フレーバー エージェントの場合、依存リソースはエージェントの作成およびログ記録中に自動的に推論されます。これらのリソースは、 resources.yaml
ファイルの記録済みモデル アーティファクトに記録されます。 デプロイ中に、 databricks.agents.deploy
は、これらの推測されたリソース依存関係にアクセスして通信するために必要な M2M OAuth トークンを自動的に作成します。
PyFuncフレーバーのエージェントの場合、デプロイされたエージェントのロギング中に、resources
パラメーターでリソースの依存関係を手動で指定する必要があります。PyFuncまたはLangChainエージェントのリソースの指定を参照してください。デプロイ中に、databricks.agents.deploy
は resources
パラメーターで指定されたリソースにアクセスできる M2M OAuth トークンを作成し、デプロイされたエージェントにデプロイします。
自動認証パススルー
次の表に、自動認証パススルーをサポートする機能を示します。 自動認証パススルーでは、デプロイ作成者の資格情報を使用して、サポートされている機能に対して自動的に認証します。
特徴量 |
最小 |
---|---|
ベクトル検索インデックス |
|
モデルサービングエンドポイント |
|
SQLウェアハウス |
|
Unity Catalog 機能 |
|
手動認証
自動認証パススルーをサポートしていない依存リソースがある場合、またはデプロイメント作成者の認証情報以外の認証情報を使用する場合は、 シークレットベースの環境変数を使用して認証情報を手動で提供できます。 たとえば、エージェントで 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
のリクエストに対するエージェントの応答が正確で、取得ツールによってフェッチされたコンテキストに基づいていることを示しています。