ナレッジ アシスト機能のトラブルシューティング

生成ナレッジ アシスト（GKA）とプロアクティブ生成ナレッジ アシスト（PGKA）の両方について、障害、機能の使用状況、レイテンシに関する詳細情報にアクセスできます。enable_response_debug_info を有効にすると、knowledge_assist_debug_info オブジェクト内でこれらのトラブルシューティングの詳細を表示できます。

トラブルシューティング用に会話プロファイルを構成する

GKA と PGKA の両方のトラブルシューティング情報にアクセスするには、会話プロファイルの enable_response_debug_info フィールドをオンにする必要があります。このフィールドがオフの場合、クエリで結果が返されないと、ナレッジ検索で NotFound エラーが返され、ナレッジ アシストで空のメッセージが返されます。enable_response_debug_info をオンにすると、結果がないことに関する詳細を含む OK レスポンスが返されます。この変更は、API と既存の統合に影響します。

生成ナレッジ アシスト（GKA）

GKA クエリのトラブルシューティングの詳細情報を取得するには、会話プロファイルで有効にする必要があります。会話プロファイルを作成または更新するときに、次のように human_agent_assistant_config 内の enable_response_debug_info フィールドを true に設定します。

parent:"projects/PROJECT_ID/locations/LOCATION-ID"
conversation_profile {
  display_name: "DISPLAY-NAME"
  human_agent_assistant_config {
    human_agent_suggestion_config {
      feature_configs {
        suggestion_feature {
          type: KNOWLEDGE_SEARCH
        }
        query_config {
          dialogflow_query_source {
            human_agent_side_config {
              agent: "projects/PROJECT_ID/locations/LOCATION-NAME/agents/AGENT-ID"
            }
          }
        }
        enable_response_debug_info: true
      }
    }
  }
}

enable_response_debug_info フィールドが有効になっている場合、ジェネレータは生成された回答とともに SearchKnowledgeResponse の一部として knowledge_search_debug_info オブジェクトを返します。この情報は、ナレッジ検索のパフォーマンスと動作に関する貴重な分析情報を提供します。

トラブルシューティングの詳細

search_knowledge_debug_info オブジェクトには、GKA の検索プロセスのトラブルシューティングと理解に役立つ重要な情報がいくつか含まれています。

検索の失敗または役に立たない回答

datastore_response_reason フィールドには、データ配信または回答の品質に関する概要ステータスが表示されます。検索が失敗した理由や回答の品質が低下した理由をすばやく特定するのに役立ちます。

値は次のとおりです。

  • NONE: リクエストは、報告すべき特定の問題なく処理されました。
  • SEARCH_OUT_OF_QUOTA: 使用割り当てを超過したため、検索オペレーションがブロックされました。
  • SEARCH_EMPTY_RESULTS: 検索で Datastore からドキュメントが返されませんでした。
  • ANSWER_GENERATION_GEN_AI_DISABLED: プロジェクトで生成 AI 機能が無効になっています。
  • ANSWER_GENERATION_OUT_OF_QUOTA: 使用量の割り当てを超えたため、回答の生成がブロックされました。
  • ANSWER_GENERATION_ERROR: 回答の生成中に内部エラーが発生しました。
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: 取得したドキュメントに、回答を生成するのに十分な情報がありませんでした。
  • ANSWER_GENERATION_RAI_FAILED: 生成された回答が責任ある AI（RAI）フィルタによってブロックされました。
  • ANSWER_GENERATION_NOT_GROUNDED: グラウンディング検証ステップで、生成された回答がソース ドキュメントによって事実として裏付けられていないと判断されたため、破棄されました。

アクティブな動作

search_knowledge_behavior オブジェクトは、GKA リクエスト中に有効だった特定の動作を示します。

  • answer_generation_rewriter_on: true 値は、Datastore の検索をより効果的に行うために、システムがユーザーのクエリを書き換えたことを示します。false の値は、ジェネレータがクエリを書き換えなかったことを示します。
  • end_user_metadata_included: true 値は、データストア エージェントへの呼び出しで end_user_metadata が渡されたことを示します。false の値は、end_user_metadata がデータストア エージェントに渡されなかったことを示します。

取り込まれたコンテキストからのトラブルシューティング情報

ingested_context_reference_debug_info フィールドには、検索を支援するために取り込まれたコンテキストに関連するトラブルシューティング情報が提供されます。

  • project_not_allowlisted: true 値は、取り込まれたコンテキスト参照機能を使用するための許可リストにプロジェクトが含まれていないことを意味します。値 false は、プロジェクトが許可リストに登録されていることを意味します。
  • context_reference_retrieved: コンテキスト参照がデータベースから正常に取得されたかどうかを示します。
  • ingested_parameters_debug_info: コンテキスト参照から取り込まれたパラメータとそのステータスのリスト。各パラメータには、パラメータ名と次のいずれかの取り込みステータスが表示されます。
    • INGESTION_STATUS_SUCCEEDED: パラメータが正常に取り込まれました。
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: パラメータは取り込みに使用できませんでした。
    • INGESTION_STATUS_PARSE_FAILED: システムがパラメータのコンテンツを解析できませんでした。
    • INGESTION_STATUS_INVALID_ENTRY: コンテキスト参照に予期しない数のコンテンツ エントリが含まれていました（1 つのみである必要があります）。
    • INGESTION_STATUS_INVALID_FORMAT: コンテキスト コンテンツが想定された形式（JSON など）ではありませんでした。
    • INGESTION_STATUS_LANGUAGE_MISMATCH: コンテキスト参照の言語が会話の言語と一致していません。

レイテンシ

{# disableFinding("データストア")}

  • service_latency オブジェクトは、さまざまな内部サービスで費やされた時間を分類し、パフォーマンスのボトルネックを特定するのに役立ちます。

  • internal_service_latencies: プロセスの内部ステップごとのレイテンシの詳細を含むリスト。各エントリには、名前（step）、所要時間（ミリ秒単位）（latency_ms）、開始時間（start_time）、終了時間（complete_time）が含まれます。内部プロセス ステップの名前は次のとおりです。

    • total_data_store_agent: クエリの受信から最終的な回答の返信まで、GKA リクエスト全体の処理にかかった合計時間を測定します。すべてのデータストア エージェント検索ステップの包括的なタイマーとして機能します。
    • query_rewrite: ユーザーの最初のクエリをナレッジ ドキュメントの検索に効果的なものに書き換えるのに費やされた時間。
    • search_query: データストア エージェントが、構成された 1 つ以上のデータストアに対して、（書き換えられた可能性のある）クエリを使用して検索を実行するのにかかった時間。
    • summarization: Datastore から取得した検索結果から簡潔な自然言語の回答を生成するのに費やされた時間（ReAct ターン）。
    • grounding: グラウンディング検証プロセスに費やされた時間。この重要なステップでは、生成された回答が返される前に、その回答がソースドキュメントによって事実に基づいてサポートされているかどうかを確認します。
    • query_generation: 進行中の会話を分析し、関連性の高い検索クエリを事前に生成するのに費やされた時間。
    • generated_query_rai: 検索に使用される前に、事前に生成されたクエリに対して責任ある AI（RAI）の安全性チェックを実行するのにかかる時間。
    • query_categorization: この機能が構成されている場合、Agent Search を使用して生成されたクエリの分類に費やされた時間。

トラブルシューティング情報のレスポンスの例

以下に、JSON レスポンスでの search_knowledge_debug_info オブジェクトの例を示します。

{
  "search_knowledge_debug_info": {
    "datastore_response_reason": "ANSWER_GENERATION_NOT_ENOUGH_INFO",
    "search_knowledge_behavior": {
      "answer_generation_rewriter_on": true,
      "end_user_metadata_included": true
    },
    "ingested_context_reference_debug_info": {
      "project_not_allowlisted": false,
      "context_reference_retrieved": true,
      "ingested_parameters_debug_info": [
        {
          "parameter": "order_id",
          "ingestion_status": "INGESTION_STATUS_SUCCEEDED"
        },
        {
          "parameter": "user_profile",
          "ingestion_status": "INGESTION_STATUS_INVALID_FORMAT"
        },
        {
          "parameter": "product_sku",
          "ingestion_status": "INGESTION_STATUS_CONTEXT_NOT_AVAILABLE"
        }
      ]
    },
    "service_latency": {
      "internal_service_latencies": [
        {
          "step": "total_data_store_agent",
          "latency_ms": 4125.781,
          "start_time": {
            "seconds": 1750969252,
            "nanos": 550649603
          },
          "complete_time": {
            "seconds": 1750969256,
            "nanos": 676430603
          }
        },
        {
          "step": "query_rewrite",
          "latency_ms": 412.0,
          "start_time": {
            "seconds": 1750969252,
            "nanos": 780119421
          },
          "complete_time": {
            "seconds": 1750969253,
            "nanos": 192119421
          }
        },
        {
          "step": "search_query",
          "latency_ms": 950.0,
          "start_time": {
            "seconds": 1750969253,
            "nanos": 192119421
          },
          "complete_time": {
            "seconds": 1750969254,
            "nanos": 142119421
          }
        },
        {
          "step": "summarization",
          "latency_ms": 721.0,
          "start_time": {
            "seconds": 1750969254,
            "nanos": 142119421
          },
          "complete_time": {
            "seconds": 1750969254,
            "nanos": 863119421
          }
        },
        {
            "step": "grounding",
            "latency_ms": 155.0,
            "start_time": {
              "seconds": 1750969254,
              "nanos": 863119421
            },
            "complete_time": {
              "seconds": 1750969255,
              "nanos": 18119421
            }
        }
      ]
    }
  }
}

プロアクティブ生成ナレッジ アシスト（PGKA）

トラブルシューティングでは、クエリの生成、分類、回答の取得プロセスについて詳細な分析情報が提供されます。knowledge_assist_debug_info オブジェクトは、提案結果内の knowledge_assist_answer の一部です。

会話プロファイルを作成または更新するときに、次のように KNOWLEDGE_ASSIST 機能の enable_response_debug_info フィールドを true に設定します。

parent: "projects/PROJECT_ID/locations/LOCATION-ID"
conversation_profile {
  display_name: "DISPLAY-NAME"
  human_agent_assistant_config {
    human_agent_suggestion_config {
      feature_configs {
        suggestion_feature {
          type: KNOWLEDGE_ASSIST
        }
        query_config {
          dialogflow_query_source {
            agent: "projects/PROJECT_ID/locations/LOCATION-ID/agents/DATASTORE-AGENT-ID"
          }
        }
        enable_response_debug_info: true
      }
    }
  }
}

トラブルシューティングの詳細

knowledge_assist_debug_info オブジェクトには、プロアクティブな提案のエンドツーエンドのライフサイクルを理解するのに役立つ次のフィールドが含まれています。

クエリを生成できませんでした

query_generation_failure_reason フィールドは、会話でプロアクティブな検索クエリが生成されなかった理由を示します。

  • QUERY_GENERATION_FAILED: クエリの生成中に内部エラーが発生しました。
  • QUERY_GENERATION_NO_QUERY_GENERATED: ジェネレータがクエリを生成しないと判断しました。これは通常、会話のトピックが変更されていない場合や、最近類似するクエリが提案された場合に発生します。
  • QUERY_GENERATION_RAI_FAILED: 責任ある AI（RAI）フィルタが、安全上の理由から潜在的なクエリをブロックしました。
  • NOT_IN_ALLOWLIST: 会話プロファイルまたはエージェント レベルのフィルタリング ルールにより、クエリの生成がブロックされました。
  • QUERY_GENERATION_QUERY_REDACTED: 生成されたクエリに削除された機密情報が含まれていたため、ジェネレータによってブロックされました。
  • QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: エージェントの言語がお客様の言語と一致しないため、クエリの生成に失敗しました。
  • QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: 翻訳されたメッセージの言語が会話プロファイルの言語と一致しないため、クエリの生成に失敗しました。
  • QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: ジェネレータはクエリ生成用の翻訳済みメッセージを想定していましたが、見つかりませんでした。

クエリの分類に失敗しました

query_categorization_failure_reason フィールドは、クエリの分類が失敗した理由を示します。

  • QUERY_CATEGORIZATION_INVALID_CONFIG: 分類用に指定されたエージェント検索の構成が無効です（検索エンジンが空の場合など）。
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: エージェント検索の結果に分類結果が含まれていませんでした。
  • QUERY_CATEGORIZATION_FAILED: 分類のためのエージェント検索の呼び出しが失敗しました。

Datastore 検索のステータス

datastore_response_reason フィールドは、クエリの生成後に Datastore に対して実行された検索のステータスを提供します。

  • NONE: Datastore は、報告すべき特定の問題なくリクエストを処理しました。
  • SEARCH_OUT_OF_QUOTA: 使用割り当てを超えたため、Agent Assist が検索オペレーションをブロックしました。
  • SEARCH_EMPTY_RESULTS: 検索で Datastore からドキュメントが返されませんでした。
  • ANSWER_GENERATION_GEN_AI_DISABLED: プロジェクトで生成 AI 機能が無効になっています。
  • ANSWER_GENERATION_OUT_OF_QUOTA: 使用量割り当てを超過したため、Agent Assist が回答の生成をブロックしました。
  • ANSWER_GENERATION_ERROR: 回答の生成中に内部エラーが発生しました。
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: 取得したドキュメントに、回答を生成するのに十分な情報がありませんでした。
  • ANSWER_GENERATION_RAI_FAILED: RAI フィルタによって生成された回答がブロックされました。
  • ANSWER_GENERATION_NOT_GROUNDED: グラウンディング検証ステップで、生成された回答を事実に基づいて裏付けるソース ドキュメントがないと判断されたため、回答は破棄されました。

アクティブな構成

knowledge_assist_behavior オブジェクトは、リクエストに対してアクティブだった特定の構成を示します。

  • answer_generation_rewriter_on: 生成ツールが検索結果を改善するためにクエリを書き換えた場合は true、書き換えなかった場合は false。
  • end_user_metadata_included: ジェネレータが end_user_metadata を Datastore に渡した場合は true、渡さなかった場合は false。
  • return_query_only: プロファイルが生成された検索クエリのみを返すように構成されている場合は true、プロファイルが完全な回答を返す場合は false。
  • use_pubsub_delivery: 生成ツールが Pub/Sub で結果を配信するように構成されている場合は true、そうでない場合は false。
  • disable_sync_delivery: レスポンスの同期配信が無効になっている場合は true、同期レスポンス配信が有効になっている場合は false。
  • previous_queries_included: クエリ生成プロセスで以前に提案されたクエリが考慮された場合は true、考慮されなかった場合は false。
  • use_translated_message: 翻訳されたメッセージがクエリの生成に使用された場合は true、使用されなかった場合は false。
  • use_custom_safety_filter_level: カスタムの安全フィルタレベルが適用された場合は true。ジェネレータがデフォルトの安全フィルタ レベルのみを使用した場合は false。

取り込まれたコンテキストからの情報

ingested_context_reference_debug_info フィールドには、検索を支援するために取り込まれたコンテキストに関連するデバッグ情報が提供されます。

  • project_not_allowlisted: true 値は、取り込まれたコンテキスト参照機能を使用するための許可リストにプロジェクトが含まれていないことを意味します。値 false は、プロジェクトが許可リストに登録されていることを意味します。
  • context_reference_retrieved: コンテキスト参照がデータベースから正常に取得されたかどうかを示します。
  • ingested_parameters_debug_info: コンテキスト参照から取り込まれたパラメータとそのステータスのリスト。各パラメータには、パラメータ名と次のいずれかの取り込みステータスが表示されます。
    • INGESTION_STATUS_SUCCEEDED: パラメータが正常に取り込まれました。
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: パラメータは取り込みに使用できませんでした。
    • INGESTION_STATUS_PARSE_FAILED: システムがパラメータのコンテンツを解析できませんでした。
    • INGESTION_STATUS_INVALID_ENTRY: コンテキスト参照に予期しない数のコンテンツ エントリが含まれていました（1 つのみである必要があります）。
    • INGESTION_STATUS_INVALID_FORMAT: コンテキスト コンテンツが想定される形式ではありませんでした。
    • INGESTION_STATUS_LANGUAGE_MISMATCH: コンテキスト参照の言語が会話の言語と一致していません。

トラブルシューティングの回答の例

次の例は、レスポンスで knowledge_assist_debug_info オブジェクトがどのように表示されるかを示しています。

{
  "knowledge_assist_debug_info": {
    "query_generation_failure_reason": "QUERY_GENERATION_NO_QUERY_GENERATED",
    "query_categorization_failure_reason": "QUERY_CATEGORIZATION_FAILURE_REASON_UNSPECIFIED",
    "datastore_response_reason": "SEARCH_EMPTY_RESULTS",
    "knowledge_assist_behavior": {
      "answer_generation_rewriter_on": true,
      "end_user_metadata_included": false,
      "return_query_only": false,
      "use_pubsub_delivery": true,
      "disable_sync_delivery": true,
      "previous_queries_included": true,
      "use_translated_message": false,
      "use_custom_safety_filter_level": false
    },
    "ingested_context_reference_debug_info": {
      "project_not_allowlisted": false,
      "context_reference_retrieved": true,
      "ingested_parameters_debug_info": [
        {
          "parameter": "session_id",
          "ingestion_status": "INGESTION_STATUS_SUCCEEDED"
        }
      ]
    },
    "service_latency": {
      "internal_service_latencies": [
        {
          "step": "query_generation",
          "latency_ms": 680.5,
          "start_time": {
            "seconds": 1753123456,
            "nanos": 110220330
          },
          "complete_time": {
            "seconds": 1753123456,
            "nanos": 790720330
          }
        },
        {
          "step": "search_query",
          "latency_ms": 1050.1,
          "start_time": {
            "seconds": 1753123456,
            "nanos": 790720330
          },
          "complete_time": {
            "seconds": 1753123457,
            "nanos": 840820330
          }
        }
      ]
    }
  }
}