Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

排查知识辅助功能方面的问题

详细了解生成式知识助理 (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 字段后，生成器会返回 knowledge_search_debug_info 对象，作为 SearchKnowledgeResponse 的一部分，并返回生成的回答。此信息可提供有关知识搜索的性能和行为的宝贵数据分析。

PGKA V2 的问题排查

启用 enable_response_debug_info field 后，KnowledgeAssistDebugInfo 对象会包含几个专用于 PGKA V2 的新字段。如需访问此对象，需要将 baseline_model_version 和 enable_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：搜索未从您的 Datastore 返回任何文档。
ANSWER_GENERATION_GEN_AI_DISABLED：您的项目已停用生成式 AI 功能。
ANSWER_GENERATION_OUT_OF_QUOTA：回答生成因超出使用配额而被屏蔽。
ANSWER_GENERATION_ERROR：回答生成期间发生内部错误。
ANSWER_GENERATION_NOT_ENOUGH_INFO：检索到的文档缺少生成回答所需的信息。
ANSWER_GENERATION_RAI_FAILED：生成的回答被 Responsible 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：上下文引用的内容条目数量超出预期（应只有一个）。
- 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：从 Datastore 检索到的搜索结果生成简洁的自然语言回答所花费的时间（ReAct 轮次）。
- grounding：接地验证过程所花费的时间。此关键步骤会在返回生成的回答之前检查该回答是否在事实上获得来源文档的支持。
- query_generation：分析正在进行的对话并主动生成相关搜索查询所花费的时间。
- generated_query_rai：在主动生成的查询用于搜索之前对其执行 Responsible AI (RAI) 安全检查所花费的时间。
- query_categorization：使用 Agent Search 对生成的查询进行分类所花费的时间（如果配置了此功能）。

问题排查信息响应示例

以下是 search_knowledge_debug_info 对象在 JSON 响应中的可能外观的完整示例。

{
  "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：Responsible 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 搜索状态

生成查询后，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。
multiple_queries_generated：true 值表示模型生成了多个查询。此字段适用于 PGKA V2。
query_contained_search_context：true 值表示生成的查询包含搜索上下文。此字段适用于 PGKA V2。
appended_search_context_count：表示在搜索中成功使用的上下文项（例如“产品”“操作系统”）的数量。此字段适用于 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：上下文引用的内容条目数量超出预期（应只有一个）。
- 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 的问题排查响应示例

以下是两个场景的完整示例。

示例 1：包含行为标志的成功建议

此场景说明了模型成功生成多个查询并使用搜索上下文丰富了主查询的响应。以下是字段说明：

multiple_queries_generated：表示模型生成了多个相关主题。
query_contained_search_context：确认主查询已使用结构化数据丰富。
appended_search_context_count：用于优化搜索的键值对（例如应用名称、操作系统）的确切数量。

{
  "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 中的结构化输出。

排查知识辅助功能方面的问题 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

配置对话配置文件以进行问题排查

生成式知识助理 (GKA)

PGKA V2 的问题排查

问题排查详细信息

搜索失败或回答无用

活跃行为

来自注入的上下文的问题排查信息

延迟时间

问题排查信息响应示例

主动生成式知识助理 (PGKA)

问题排查详细信息

未能生成查询

未能对查询进行分类

Datastore 搜索状态

活跃配置

来自注入的上下文的信息

PGKA V1 的问题排查响应示例

PGKA V2 的问题排查响应示例

示例 1：包含行为标志的成功建议

示例 2：包含失败原因的跳过建议

排查知识辅助功能方面的问题