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

デプロイされた AI エージェントのデバッグ

このページでは、Mosaic AI Agent Framework の agents.deploy() API を使用して AI エージェントをデプロイする際の一般的な問題をデバッグする方法について説明します。

Agent Framework はモデルサービングエンドポイントにデプロイされるため、このページのエージェントのデバッグ手順に加えて、 モデルサービングのデバッグガイド を確認する必要があります。

ベストプラクティスを使用したエージェントの作成​

エージェントを作成するときは、次のベストプラクティスを使用してください。

  • 推奨されるエージェント作成インターフェイスと MLflow トレースを使用してデバッグを改善する:MLflow トレースの自動ログ記録を有効にするなど、 コードで AI エージェントを作成する のベスト プラクティスに従って、エージェントのデバッグを容易にします。
  • ツールを明確に文書化する : ツールとパラメーターの説明を明確にすることで、エージェントがツールを理解し、適切に使用できるようになります。「明確なドキュメントによるツール呼び出しの改善」を参照してください。
  • LLM 呼び出しにタイムアウトとトークン制限を追加する : コード内の LLM 呼び出しにタイムアウトとトークン制限を追加して、実行時間の長いステップによる遅延を回避します。
    • エージェントが OpenAI クライアント を使用して Databricks LLM サービス エンドポイントにクエリを実行する場合は、必要に応じてエンドポイント呼び出しの提供にカスタム タイムアウトを設定します。

デプロイされたエージェントに対する低速または失敗した要求のデバッグ​

エージェントの作成中に MLflow トレースの自動ログ 記録を有効にした場合、トレースは推論テーブルに自動的に記録されます。これらのトレースは、低速または障害が発生しているエージェントコンポーネントを特定するのに役立ちます。

問題のあるリクエストを特定する​

問題のあるリクエストを見つけるには、次の手順に従います。

  1. ワークスペースで、[ サービス] タブに移動し、デプロイ名を選択します。

  2. [ 推論テーブル ] セクションで、推論テーブルの完全修飾名を見つけます。たとえば、 my-catalog.my-schema.my-table.

  3. Databricks ノートブックで次のコマンドを実行します。

    Python
    %sql
    SELECT * FROM my-catalog.my-schema.my-table

  4. 「レスポンス 」列で詳細なトレース情報を確認します。

  5. request_time、databricks_request_id、またはstatus_codeでフィルタリングして、結果を絞り込みます。

    Python
    %sql
    SELECT * FROM my-catalog.my-schema.my-table
    WHERE status_code != 200

問題の根本原因を分析する​

失敗した要求や遅い要求を特定したら、 mlflow.models.validate_serving_input失敗した入力要求に対してエージェントを呼び出す API。次に、結果のトレースを表示し、失敗した応答に対して根本原因分析を実行します。

開発ループを高速化するために、エージェントコードを直接更新し、失敗した入力の例に対してエージェントを呼び出すことで反復処理できます。

認証エラーのデバッグ​

デプロイされたエージェントがベクトル検索インデックスや LLM エンドポイントなどのリソースにアクセスしたときに認証エラーが発生した場合は、自動認証パススルーに必要なリソースと共にログに記録されたことを確認します。「自動認証パススルー」を参照してください。

ログに記録されたリソースを検査するには、ノートブックで次のコマンドを実行します。

Python
%pip install -U mlflow[databricks]
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

不足しているリソースや正しくないリソースを再度追加するには、エージェントをログに記録して再度デプロイする必要があります。

リソースに手動認証を使用している場合は、環境変数が正しく設定されていることを確認します。手動設定は、自動認証設定よりも優先されます。手動認証を参照してください。

に最終更新