Acesse informações detalhadas sobre falhas, comportamento de uso de recursos e latência para a Assistência de conhecimento generativo (GKA) e a Assistência de conhecimento generativo proativa (PGKA). Ative enable_response_debug_info para ver esses detalhes de solução de problemas no objeto knowledge_assist_debug_info.
Configurar um perfil de conversa para solução de problemas
Para acessar informações de solução de problemas do GKA e do PGKA, ative o campo enable_response_debug_info no perfil de conversa. Se esse campo estiver desativado, a pesquisa de conhecimento vai mostrar um erro NotFound quando uma consulta não gerar resultados, e o Assistente de conhecimento vai mostrar uma mensagem vazia. Ative enable_response_debug_info para fornecer uma resposta OK com detalhes sobre a falta de resultados. Essa modificação afeta a API e as integrações atuais.
Assistência de conhecimento generativo (GKA)
Para receber informações detalhadas sobre a solução de problemas das suas consultas da GKA, ative essa opção no seu perfil de conversa. Ao criar ou atualizar um perfil de conversa, defina o campo enable_response_debug_info como true em human_agent_assistant_config, da seguinte maneira.
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
}
}
}
}
Com o campo enable_response_debug_info ativado, o gerador retorna o objeto knowledge_search_debug_info como parte do SearchKnowledgeResponse junto com as respostas geradas. Essas informações oferecem insights valiosos sobre a performance e o comportamento da pesquisa de conhecimento.
Solução de problemas do PGKA V2
Com o enable_response_debug_info field ativado, o objeto KnowledgeAssistDebugInfo inclui vários novos campos específicos para o PGKA V2. Para acessar isso, baseline_model_version e enable_response_debug_info precisam ser definidos como 2.0.
Confira abaixo um exemplo de configuração para acessar informações de solução de problemas no 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",
}
]
}
}
Detalhes da solução de problemas
O objeto search_knowledge_debug_info contém várias informações importantes para ajudar você a resolver problemas e entender o processo de pesquisa do GKA.
Falha na pesquisa ou resposta irrelevante
O campo datastore_response_reason oferece um status de alto nível sobre a veiculação de dados ou a qualidade da resposta. Ele ajuda você a identificar rapidamente por que uma pesquisa pode ter falhado ou por que a qualidade da resposta pode ter sido reduzida.
Os possíveis valores incluem:
NONE: a solicitação foi processada sem problemas específicos a serem informados.SEARCH_OUT_OF_QUOTA: a operação de pesquisa foi bloqueada por exceder a cota de uso.SEARCH_EMPTY_RESULTS: a pesquisa não retornou documentos do seu Datastore.ANSWER_GENERATION_GEN_AI_DISABLED: os recursos de IA generativa estão desativados para seu projeto.ANSWER_GENERATION_OUT_OF_QUOTA: a geração de respostas foi bloqueada devido ao excesso de cota de uso.ANSWER_GENERATION_ERROR: Ocorreu um erro interno durante a geração da resposta.ANSWER_GENERATION_NOT_ENOUGH_INFO: os documentos recuperados não tinham informações suficientes para gerar uma resposta.ANSWER_GENERATION_RAI_FAILED: a resposta gerada foi bloqueada pelos filtros de IA responsável (RAI).ANSWER_GENERATION_NOT_GROUNDED: a etapa de verificação de embasamento determinou que a resposta gerada não era comprovada pelos documentos de origem e, portanto, foi descartada.
Comportamentos ativos
O objeto search_knowledge_behavior informa quais comportamentos específicos estavam ativos durante a solicitação da GKA.
answer_generation_rewriter_on: um valortrueindica que o sistema reescreveu a consulta do usuário para ser mais eficaz na pesquisa do Datastore. Um valorfalseindica que o gerador não reescreveu sua consulta.end_user_metadata_included: um valortrueindica queend_user_metadatafoi transmitido na chamada ao agente do repositório de dados. Um valorfalseindica queend_user_metadatanão foi transmitido ao agente do repositório de dados.
Informações de solução de problemas do contexto ingerido
O campo ingested_context_reference_debug_info fornece informações de solução de problemas relacionadas ao contexto ingerido para ajudar na pesquisa.
project_not_allowlisted: um valortruesignifica que o projeto não está na lista de permissões para usar o recurso de referência de contexto ingerido. Um valorfalsesignifica que o projeto está na lista de permissões.context_reference_retrieved: indica se a referência de contexto foi recuperada do banco de dados.ingested_parameters_debug_info: uma lista de parâmetros ingeridos da referência de contexto e o status deles. Para cada parâmetro, você vê um nome e um dos seguintes status de ingestão.INGESTION_STATUS_SUCCEEDED: o parâmetro foi ingerido.INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: o parâmetro não estava disponível para ingestão.INGESTION_STATUS_PARSE_FAILED: o sistema não conseguiu analisar o conteúdo do parâmetro.INGESTION_STATUS_INVALID_ENTRY: a referência de contexto tinha um número inesperado de entradas de conteúdo (deveria ter apenas uma).INGESTION_STATUS_INVALID_FORMAT: o conteúdo do contexto não estava no formato esperado (por exemplo, JSON).INGESTION_STATUS_LANGUAGE_MISMATCH: o idioma da referência de contexto não corresponde ao da conversa.
Latência
O objeto
service_latencydetalha o tempo gasto em vários serviços internos, ajudando você a identificar gargalos de performance.internal_service_latencies: uma lista com detalhes de latência para cada etapa interna do processo. Cada entrada inclui um nome (step), a quantidade de tempo que leva em milissegundos (latency_ms) e o horário de início (start_time) e término (complete_time). Possíveis nomes para uma etapa de processo interno:total_data_store_agent: mede o tempo total gasto para processar toda a solicitação da GKA, desde o recebimento da consulta até o retorno de uma resposta final. Ele funciona como um timer geral para todas as etapas de pesquisa do datastore para agentes.query_rewrite: o tempo gasto para reescrever a consulta inicial do usuário e torná-la mais eficaz na pesquisa dos documentos de conhecimento.search_query: o tempo gasto pelo agente de repositório de dados para executar a pesquisa nos repositórios configurados usando a consulta (potencialmente reescrita).summarization: o tempo gasto para gerar uma resposta concisa em linguagem natural com base nos resultados da pesquisa recuperados do Datastore (rodada do ReAct).grounding: o tempo gasto no processo de verificação de embasamento. Essa etapa crucial verifica se a resposta gerada é comprovada pelos documentos da fonte antes de ser retornada.query_generation: o tempo gasto analisando a conversa em andamento e gerando proativamente uma consulta de pesquisa relevante.generated_query_rai: o tempo necessário para realizar uma verificação de segurança de IA responsável (RAI, na sigla em inglês) na consulta gerada de forma proativa antes de ela ser usada em uma pesquisa.query_categorization: o tempo gasto para categorizar a consulta gerada usando a Pesquisa do agente, se esse recurso estiver configurado.
Exemplo de resposta com informações de solução de problemas
Confira a seguir um exemplo abrangente de como o objeto search_knowledge_debug_info pode aparecer em uma resposta 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
}
}
]
}
}
}
Assistência de conhecimento generativo proativa (PGKA)
A solução de problemas oferece insights detalhados sobre os processos de geração, categorização e recuperação de respostas da consulta. O objeto knowledge_assist_debug_info faz parte do knowledge_assist_answer nos resultados da sugestão.
Ao criar ou atualizar um perfil de conversa, defina o campo enable_response_debug_info como true para o recurso KNOWLEDGE_ASSIST, da seguinte maneira.
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
}
}
}
}
Detalhes da solução de problemas
O objeto knowledge_assist_debug_info contém os seguintes campos para ajudar você a entender o ciclo de vida completo de uma sugestão proativa.
Não foi possível gerar uma consulta
O campo query_generation_failure_reason explica por que uma conversa não gerou uma consulta de pesquisa proativa.
QUERY_GENERATION_FAILED: ocorreu um erro interno durante a geração da consulta.QUERY_GENERATION_NO_QUERY_GENERATED: o gerador decidiu não criar uma consulta. Isso geralmente acontece quando o assunto da conversa não mudou ou uma consulta semelhante foi sugerida recentemente.QUERY_GENERATION_RAI_FAILED: os filtros de IA responsável (RAI) bloquearam uma possível consulta por motivos de segurança.NOT_IN_ALLOWLIST: as regras de filtragem no nível do perfil de conversa ou do agente bloquearam a geração de consultas.QUERY_GENERATION_QUERY_REDACTED: o gerador bloqueou a consulta gerada porque ela continha informações sensíveis que foram encobertas.QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: a geração de consultas falhou porque o idioma do agente não corresponde ao do cliente.QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: a geração de consultas falhou porque o idioma da mensagem traduzida não corresponde ao idioma do perfil de conversa.QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: o gerador esperava uma mensagem traduzida para a geração de consultas, mas não encontrou nenhuma.QUERY_GENERATION_EMPTY_CONVERSATION: a conversa não tem mensagens. Isso só está disponível para o PGKA V2.QUERY_GENERATION_EMPTY_LAST_MESSAGE: a última mensagem estava vazia ou tinha apenas espaços em branco. Isso só está disponível para o PGKA V2.QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET: a configuração do evento de acionamento (por exemplo,AGENT_MESSAGE) não correspondeu à função do remetente da última mensagem. Isso só está disponível para o PGKA V2.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: o sistema não conseguiu analisar a saída JSON estruturada do modelo. Isso só está disponível para o PGKA V2.
Falha ao categorizar uma consulta
O campo query_categorization_failure_reason explica por que a categorização de consultas pode ter falhado.
QUERY_CATEGORIZATION_INVALID_CONFIG: a configuração da Pesquisa do agente fornecida para categorização é inválida. Por exemplo, o mecanismo de pesquisa está vazio.QUERY_CATEGORIZATION_RESULT_NOT_FOUND: o resultado da Pesquisa do agente não incluiu um resultado de categorização.QUERY_CATEGORIZATION_FAILED: a chamada para a Pesquisa do agente para categorização falhou.
Status da pesquisa do Datastore
O campo datastore_response_reason fornece o status da pesquisa no seu Datastore depois que uma consulta é gerada.
NONE: Datastore processou a solicitação sem problemas específicos a serem informados.SEARCH_OUT_OF_QUOTA: o Agent Assist bloqueou a operação de pesquisa por exceder a cota de uso.SEARCH_EMPTY_RESULTS: a pesquisa não retornou documentos do seu Datastore.ANSWER_GENERATION_GEN_AI_DISABLED: os recursos de IA generativa estão desativados para seu projeto.ANSWER_GENERATION_OUT_OF_QUOTA: O Agent Assist bloqueou a geração de respostas por exceder a cota de uso.ANSWER_GENERATION_ERROR: Ocorreu um erro interno durante a geração da resposta.ANSWER_GENERATION_NOT_ENOUGH_INFO: os documentos recuperados não tinham informações suficientes para gerar uma resposta.ANSWER_GENERATION_RAI_FAILED: os filtros de RAI bloquearam a resposta gerada.ANSWER_GENERATION_NOT_GROUNDED: a etapa de verificação de embasamento determinou que os documentos de origem não apoiavam de fato a resposta gerada, então ela foi descartada.
Configurações ativas
O objeto knowledge_assist_behavior informa quais configurações específicas estavam ativas para a solicitação.
answer_generation_rewriter_on:truese o gerador reescreveu a consulta para melhorar os resultados da pesquisa efalsese não fez isso.end_user_metadata_included:truese o gerador tiver transmitidoend_user_metadataao Datastore efalsese não tiver.return_query_only:truese o perfil estiver configurado para retornar apenas a consulta de pesquisa gerada efalsese o perfil retornar a resposta completa.use_pubsub_delivery:truese o gerador estiver configurado para entregar resultados com o Pub/Sub efalsese não estiver.disable_sync_delivery:truese a entrega síncrona da resposta estiver desativada efalsese estiver ativada.previous_queries_included:truese o gerador considerou consultas sugeridas anteriormente durante o processo de geração de consultas efalsese não considerou.use_translated_message:truese uma mensagem traduzida foi usada para gerar a consulta efalsese não foi.use_custom_safety_filter_level:truese um nível de filtro de segurança personalizado foi aplicado.falsese o gerador usou apenas os níveis padrão do filtro de segurança.multiple_queries_generated: um valortrueindica que o modelo gerou mais de uma consulta. Esse recurso está disponível para o PGKA V2.query_contained_search_context: um valortrueindica que a consulta gerada incluiu um contexto de pesquisa. Esse recurso está disponível para o PGKA V2.appended_search_context_count: indica o número de itens de contexto (por exemplo, "produto", "SO") usados com sucesso na pesquisa. Esse recurso está disponível para o PGKA V2.
Informações do contexto ingerido
O campo ingested_context_reference_debug_info fornece informações de depuração relacionadas ao contexto ingerido para ajudar na pesquisa.
project_not_allowlisted: um valortruesignifica que o projeto não está na lista de permissões para usar o recurso de referência de contexto ingerido. Um valorfalsesignifica que o projeto está na lista de permissões.context_reference_retrieved: indica se a referência de contexto foi recuperada do banco de dados.ingested_parameters_debug_info: uma lista de parâmetros ingeridos da referência de contexto e o status deles. Para cada parâmetro, você vê um nome e um dos seguintes status de ingestão possíveis.INGESTION_STATUS_SUCCEEDED: o parâmetro foi ingerido.INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: o parâmetro não estava disponível para ingestão.INGESTION_STATUS_PARSE_FAILED: o sistema não conseguiu analisar o conteúdo do parâmetro.INGESTION_STATUS_INVALID_ENTRY: a referência de contexto tinha um número inesperado de entradas de conteúdo (deveria ter apenas uma).INGESTION_STATUS_INVALID_FORMAT: o conteúdo do contexto não estava no formato esperado.INGESTION_STATUS_LANGUAGE_MISMATCH: o idioma da referência de contexto não corresponde ao da conversa.
Exemplo de resposta para solução de problemas do PGKA V1
Confira a seguir um exemplo abrangente de como o objeto knowledge_assist_debug_info pode aparecer em uma resposta.
{
"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
}
}
]
}
}
}
Exemplo de resposta para solução de problemas do PGKA V2
Confira a seguir exemplos abrangentes para dois cenários.
Exemplo 1: sugestão bem-sucedida com flags de comportamento
Este cenário ilustra uma resposta em que o modelo gerou várias consultas e enriqueceu a consulta principal com o contexto de pesquisa. Confira a explicação dos campos:
multiple_queries_generated: indica que o modelo produziu mais de um tema relevante.query_contained_search_context: confirma se a consulta principal foi enriquecida com dados estruturados.appended_search_context_count: o número exato de pares de chave-valor (por exemplo, nome do aplicativo, SO) usados para refinar a pesquisa.
{
"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" }
]
}
}
]
}
}
]
}
Exemplo 2: sugestão ignorada com motivo de falha
Nesse cenário, o sistema determinou que uma sugestão não deveria ser acionada porque a condição do evento não foi atendida (por exemplo, o acionador foi definido como AGENT_MESSAGE, mas a última mensagem foi de END_USER). Em vez de um erro, o sistema retorna um status de sucesso com o motivo específico.
{
"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
}
}
]
}
Outros motivos comuns de falha incluem:
QUERY_GENERATION_EMPTY_CONVERSATION: não foram encontradas mensagens na conversa.QUERY_GENERATION_EMPTY_LAST_MESSAGE: a última mensagem estava vazia ou continha apenas espaços em branco.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: o sistema não conseguiu analisar a saída estruturada do LLM.