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

生成ナレッジ アシスト(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 オブジェクトを返します。この情報は、ナレッジ検索のパフォーマンスと動作に関する貴重な分析情報を提供します。

PGKA V2 のトラブルシューティング

enable_response_debug_info field が有効になっている場合、KnowledgeAssistDebugInfo オブジェクトには PGKA V2 固有の新しいフィールドがいくつか含まれます。これにアクセスするには、baseline_model_versionenable_response_debug_info を 2.0 に設定する必要があります。 PGKA V2 でトラブルシューティング情報にアクセスするための設定例を次に示します。

  "name": "projects/PROJECT_ID/locations/LOCATION/conversationProfiles/PROFILE_ID",
  "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/agents/AGENT_ID"
            }
          },
          "conversation_model_config": {
            "baseline_model_version": "2.0"
          },
          "disable_query_search_context": true,
          "enable_response_debug_info": true,
            "suggestion_trigger_event": "END_OF_UTTERANCE",
        }
      ]
    }
  }

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

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

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

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

値は次のとおりです。

  • NONE: リクエストは、報告する特定の問題なく処理されました。
  • SEARCH_OUT_OF_QUOTA: 使用量割り当てを超えたため、検索オペレーションがブロックされました。
  • SEARCH_EMPTY_RESULTS: 検索でデータストアからドキュメントが返されませんでした。
  • 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 の場合、システムはデータストアの検索をより効果的に行うためにユーザーのクエリを書き換えたことを示します。値が 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: コンテキスト参照の言語が会話の言語と一致しませんでした。

レイテンシ

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

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

    • total_data_store_agent: クエリの受信から最終的な回答の返信まで、GKA リクエスト全体の処理にかかった合計時間を測定します。エージェントのデータストア検索ステップ全体の包括的なタイマーとして機能します。
    • query_rewrite: ナレッジ ドキュメントの検索をより効果的に行うために、ユーザーの最初のクエリを書き換えるのに費やされた時間。
    • search_query: データストア エージェントが、構成されたデータストアに対して、(書き換えられた可能性のある)クエリを使用して検索を実行するのにかかった時間。
    • summarization: データストアから取得した検索結果から、簡潔な自然言語の回答を生成するのに費やされた時間(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_GENERATION_EMPTY_CONVERSATION: 会話にメッセージがありません。これは PGKA V2 でのみ使用できます。
  • QUERY_GENERATION_EMPTY_LAST_MESSAGE: 最後のメッセージが空または空白でした。これは PGKA V2 でのみ使用できます。
  • QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET: トリガー イベントの構成(AGENT_MESSAGE など)が、最後のメッセージ送信者のロールと一致しませんでした。これは PGKA V2 でのみ使用できます。
  • QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: システムはモデルからの構造化 JSON 出力を解析できませんでした。これは PGKA V2 でのみ使用できます。

クエリを分類できませんでした

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

  • QUERY_CATEGORIZATION_INVALID_CONFIG: 分類用に提供された Agent Search の構成が無効です(検索エンジンが空など)。
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: Agent Search の結果に分類結果が含まれていませんでした。
  • QUERY_CATEGORIZATION_FAILED: 分類のための Agent Search の呼び出しに失敗しました。

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

datastore_response_reason フィールドには、クエリの生成後のデータストアに対する検索のステータスが表示されます。

  • NONE: データストアは、報告する特定の問題なくリクエストを処理しました。
  • SEARCH_OUT_OF_QUOTA: 使用量割り当てを超えたため、Agent Assist が検索オペレーションをブロックしました。
  • SEARCH_EMPTY_RESULTS: 検索でデータストアからドキュメントが返されませんでした。
  • 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 をデータストアに渡した場合は 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
  • multiple_queries_generated: 値が true の場合、モデルは複数のクエリを生成しました。これは PGKA V2 で使用できます。
  • query_contained_search_context: 値が true の場合、生成されたクエリに検索コンテキストが含まれていました。これは PGKA V2 で使用できます。
  • appended_search_context_count: 検索で正常に使用されたコンテキスト アイテム(「商品」、「OS」など)の数を示します。これは PGKA V2 で使用できます。

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

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: コンテキスト参照の言語が会話の言語と一致しませんでした。

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

以下に、レスポンスでの 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
          }
        }
      ]
    }
  }
}

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

以下に、2 つのシナリオの包括的な例を示します。

例 1: 動作フラグを使用した提案の成功

このシナリオでは、モデルが複数のクエリを正常に生成し、検索コンテキストでプライマリ クエリを拡充したレスポンスを示します。フィールドの説明は次のとおりです。

  • multiple_queries_generated: モデルが複数の関連トピックを生成したことを示します。
  • query_contained_search_context: プライマリ クエリが構造化データで拡充されたことを確認します。
  • appended_search_context_count: 検索の絞り込みに使用された Key-Value ペア(アプリケーション名、OS など)の正確な数。
{
  "message": {
    "name": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "content": "My DesignApp is crashing on Mac. Also, how do I resolve the storage limit error?",
    "participant_role": "END_USER"
  },
  "human_agent_suggestion_results": [
    {
      "suggest_knowledge_assist_response": {
        "knowledge_assist_answer": {
          "suggested_query": {
            "query_text": "Troubleshoot application crashing",
            "search_contexts": [
              { "key": "application name", "value": "DesignApp" },
              { "key": "operating system", "value": "Mac" }
            ]
          },
          "suggested_query_answer": {
            "answer_text": "To troubleshoot the crash on Mac, ensure..."
          },
          "answer_record": "projects/PROJECT_ID/locations/LOCATION/answerRecords/ANSWER_RECORD_ID",
          "knowledge_assist_debug_info": {
            "knowledge_assist_behavior": {
              "multiple_queries_generated": true,
              "query_contained_search_context": true,
              "appended_search_context_count": 2
            }
          }
        },
        "latest_message": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
        "context_size": 20,
        "additional_suggested_query_results": [
          {
            "suggested_query": {
              "query_text": "Resolve storage limit exceeded error",
              "search_contexts": [
                { "key": "storage plan", "value": "1TB" }
              ]
            }
          }
        ]
      }
    }
  ]
}

例 2: 失敗理由による提案のスキップ

このシナリオでは、イベント条件が満たされなかったため(トリガーが AGENT_MESSAGE に設定されているが、最後のメッセージが END_USER からだった場合など)、提案をトリガーしないとシステムが判断しました。エラーではなく、システムは特定の理由とともに成功ステータスを返します。

{
  "message": {
    "name": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "content": "I am having trouble with my account.",
    "participant_role": "END_USER"
  },
  "human_agent_suggestion_results": [
    {
      "suggest_knowledge_assist_response": {
        "knowledge_assist_answer": {
          "knowledge_assist_debug_info": {
            "query_generation_failure_reason": "QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET"
          }
        },
        "latest_message": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
        "context_size": 20
      }
    }
  ]
}

その他の一般的な失敗理由は次のとおりです。

  • QUERY_GENERATION_EMPTY_CONVERSATION: 会話にメッセージが見つかりませんでした。
  • QUERY_GENERATION_EMPTY_LAST_MESSAGE: 最後のメッセージが空または空白のみでした。
  • QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: システムは LLM からの構造化出力を解析できませんでした。