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

生成ナレッジ アシスト（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("data store")}

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

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

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

データストアの検索ステータス

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
          }
        }
      ]
    }
  }
}