メインコンテンツまでスキップ

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

このページでは、 Agent Framework Python API の 関数を使用して AI エージェント を Mosaic AI Model Servingdeploy() にデプロイする方法を示します。

Mosaic AI Model Serving にエージェントをデプロイすると、次のような利点があります。

  • モデルサービングは、オートスケール、ロギング、バージョン管理、アクセス制御を管理し、高品質なエージェントの開発に集中することができます。
  • 対象分野の専門家は、レビューアプリを使用して、デプロイされたエージェントと対話し、モニタリングと評価に組み込むことができるフィードバックを提供できます。
  • ライブトラフィックで評価を実行することで、エージェントを監視できます。ユーザートラフィックにはグラウンドトゥルースは含まれませんが、LLM ジャッジ (および作成したカスタムメトリクス) は教師なし評価を実行します。

必要条件​

  • MLflow 2.13.1 以降 (databricks.agentsから deploy() API を使用してエージェントをデプロイする場合

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

  • Databricks ノートブックの外部からエージェントをデプロイするには databricks-agents SDK バージョン 0.12.0 以降が必要です。

  • エンドポイント作成者 (エージェントをデプロイするユーザー) は、デプロイ時に推論テーブルを格納するために選択された Unity Catalog スキーマに対する CREATE VOLUME アクセス許可を持っている必要があります。これにより、関連する評価テーブルとログ記録テーブルをスキーマに作成できます。推論テーブルの有効化と無効化を参照してください。

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

deploy() 操作

説明

Create CPU モデルサービング エンドポイント

エージェントをモデルサービング エンドポイント経由で提供することにより、ユーザー向けアプリケーションからエージェントにアクセスできるようにします。

プロビジョニング short-lived サービスプリンシパル credentials

Databricks は、 モデルのログ記録時に定義された Databricks マネージド リソースにアクセスするための最小限のアクセス許可を持つ、有効期間の短い資格情報を自動的に提供します。

Databricks は、資格情報を発行する前に、エンドポイント所有者に必要なアクセス許可を持っていることを確認して、特権の昇格や不正アクセスを防ぎます。AIエージェントの認証を参照してください。

エージェントが Databricks で管理されていないリソースに依存している場合は、シークレットを含む環境変数を deploy()に渡すことができます。「モデルサービングエンドポイントからリソースへのアクセスを設定する」を参照してください。

レビューアプリを有効にする

利害関係者がエージェントと対話し、フィードバックを提供できるようにします。「レビュー アプリを使用して、生成AI アプリ (MLflow 2) の人間によるレビューを行う」を参照してください。

推論テーブルを有効にする

エージェントを監視およびデバッグするには、要求の入力と応答をログに記録します。

REST API 要求のログ記録とアプリのフィードバックの確認

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

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

本番運用 モニタリング for Gen AI (beta) を有効にする

本番運用 モニタリング ベータ版への登録が必要です。基本監視は、デプロイされたエージェントトレースに対して自動的に有効になります。

MLflow 3 (beta) でリアルタイム トレースとモニタリングを有効にする

本番運用 モニタリング ベータ版への登録と MLflow 3.0 以降の使用が必要です。

Databricks は、デプロイされたエージェントからのトレースを推論テーブルにログ記録して長期保存するだけでなく、デプロイされたエージェントからのトレースを MLflow エクスペリメントにログに記録し、リアルタイムの可視性を確保します。これにより、モニタリングとデバッグのレイテンシーが短縮されます。

  • agents.deploy()を使用して新しいエンドポイントを作成すると、モニタリングとトレースは、現在アクティブなMLflowエクスペリメントからの読み取りと書き込みで構成されます。

  • 特定のエンドポイントのエクスペリメントを設定するには、agents.deploy()を呼び出してエンドポイントを作成する前に mlflow.set_experiment() を呼び出します。

  • エンドポイントで提供されているすべてのエージェント ( agents.deploy()への後続の呼び出しによってエンドポイントに追加されたエージェントを含む) からのトレースは、このエクスペリメントに書き込まれます。

  • モニタリング コンピュート quality メトリクス on traces in this エクスペリメント.

  • デフォルトでは、基本的な監視のみが構成されます。 LLMジャッジなどを追加するには、本番運用 モニタリングを参照してください。

注記

デプロイが完了するまでに最大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エージェントは、タスクを完了するために他のリソースに対して認証を必要とすることがよくあります。 たとえば、エージェントは、非構造化データをクエリするためにベクトル検索インデックスにアクセスする必要がある場合があります。

すべての認証方法とその使用タイミングに関する包括的な情報については、「 AI エージェントの認証」を参照してください。

デプロイされたエージェントの監視​

エージェントが Databricks モデルサービングにデプロイされた後、 AI Gateway 推論テーブルを使用してデプロイされたエージェントをモニタリングできます。 推論テーブルには、レビューアプリからのリクエスト、レスポンス、エージェントトレース、エージェントフィードバックの詳細なログが含まれています。 この情報により、問題のデバッグ、パフォーマンスの監視、オフライン評価用のゴールデンデータセットの作成が可能になります。

important

MLflow 3 が開発環境にインストールされている場合、 agents.deploy()を呼び出したときにエンドポイントは、 MLflow Traces をリアルタイムで、呼び出し時にアクティブ化されたエクスペリメントMLflowに記録agents.deploy()。デプロイメント前に mlflow.set_experiment() を呼び出して、アクティブなエクスペリメントを変更できます。

詳細については、 MLflow のドキュメント を参照してください。

「トレースを使用したアプリのデバッグと監視」を参照してください。

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

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

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

「Databricks エージェント Python API」を参照してください。

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

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

追加のリソース​

に最終更新