Resolver problemas com os recursos de assistência de conhecimento

Acesse informações detalhadas sobre falhas, comportamento de uso de recursos e latência da assistência de conhecimento generativo (GKA, na sigla em inglês) e da assistência de conhecimento generativo proativa (PGKA, na sigla em inglês). Ative enable_response_debug_info para conferir 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 da GKA e da 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 a assistência 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 de solução de problemas das consultas da GKA, ative o recurso no 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, conforme mostrado abaixo.

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 da SearchKnowledgeResponse junto com as respostas geradas. Essas informações oferecem insights valiosos sobre a performance e o comportamento da pesquisa de conhecimento.

Detalhes da solução de problemas

O objeto search_knowledge_debug_info contém várias informações importantes para ajudar você a solucionar problemas e entender o processo de pesquisa da GKA.

Falha na pesquisa ou resposta inútil

O campo datastore_response_reason mostra 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 estar degradada.

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 devido ao excesso de 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 de respostas.
  • 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, na sigla em inglês).
  • ANSWER_GENERATION_NOT_GROUNDED: a etapa de verificação de embasamento determinou que a resposta gerada não tinha suporte factual dos 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 valor true indica que o sistema reescreveu a consulta do usuário para ser mais eficaz na pesquisa do Datastore. Um valor false indica que o gerador não reescreveu a consulta.
  • end_user_metadata_included: um valor true indica que end_user_metadata foi transmitido na chamada ao agente do repositório de dados. Um valor false indica que end_user_metadata nã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 valor true significa que o projeto não está na lista de permissões para usar o recurso de referência de contexto ingerido. Um valor false significa 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ê verá 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 correspondia ao idioma da conversa.

Latência

{# disableFinding("repositório de dados")}

  • O objeto service_latency detalha o tempo gasto em vários serviços internos, ajudando você a identificar gargalos de performance.

  • internal_service_latencies: uma lista que contém detalhes de latência para cada etapa interna do processo. Cada entrada inclui um nome (step), a quantidade de tempo em milissegundos (latency_ms) e a hora de início (start_time) e de término (complete_time). Os possíveis nomes para uma etapa de processo interno são:

    • 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 agente do repositório de dados.
    • query_rewrite: o tempo gasto para reescrever a consulta inicial do usuário para ser mais eficaz na pesquisa de documentos de conhecimento.
    • search_query: o tempo gasto pelo agente do repositório de dados para executar a pesquisa no repositório de dados configurado ou nos repositórios, usando a consulta (possivelmente reescrita).
    • summarization: o tempo gasto para gerar uma resposta concisa em linguagem natural com base nos resultados da pesquisa recuperados do Datastore (turno ReAct).
    • grounding: o tempo gasto no processo de verificação de embasamento. Essa etapa crucial verifica se a resposta gerada tem suporte factual dos documentos de origem antes de ser retornada.
    • query_generation: o tempo gasto para analisar a conversa em andamento e gerar proativamente uma consulta de pesquisa relevante.
    • generated_query_rai: o tempo gasto para realizar uma verificação de segurança de IA responsável (RAI) na consulta gerada proativamente antes de ela ser usada para 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 de informações de solução de problemas

Confira abaixo 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 consultas. O objeto knowledge_assist_debug_info faz parte da knowledge_assist_answer nos resultados de sugestão.

Ao criar ou atualizar um perfil de conversa, defina o campo enable_response_debug_info como true para o recurso KNOWLEDGE_ASSIST, conforme mostrado abaixo.

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.

Falha ao gerar uma consulta

O campo query_generation_failure_reason explica por que uma conversa pode não ter gerado uma consulta de pesquisa proativa.

  • QUERY_GENERATION_FAILED: ocorreu um erro interno durante a geração de consultas.
  • QUERY_GENERATION_NO_QUERY_GENERATED: o gerador decidiu não gerar uma consulta. Isso geralmente acontece quando o tópico 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 perfil de conversa ou no nível 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 editadas.
  • QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: a geração de consultas falhou porque o idioma do agente não corresponde ao idioma 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 uma.

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 Datastore depois que uma consulta é gerada.

  • NONE: o 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 devido ao excesso de 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 devido ao excesso de cota de uso.
  • ANSWER_GENERATION_ERROR: ocorreu um erro interno durante a geração de respostas.
  • 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 tinham suporte factual para a resposta gerada. Portanto, a resposta 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: true se o gerador reescreveu a consulta para melhores resultados de pesquisa e false se não.
  • end_user_metadata_included: true se o gerador transmitiu end_user_metadata ao Datastore e false se não.
  • return_query_only: true se o perfil estiver configurado para retornar apenas a consulta de pesquisa gerada e false se o perfil retornar a resposta completa.
  • use_pubsub_delivery: true se o gerador estiver configurado para entregar resultados com o Pub/Sub e false se não.
  • disable_sync_delivery: true se a entrega síncrona da resposta estiver desativada e false se a entrega síncrona da resposta estiver ativada.
  • previous_queries_included: true se o gerador considerou consultas sugeridas anteriormente durante o processo de geração de consultas e false se não.
  • use_translated_message: true se uma mensagem traduzida foi usada para a geração de consultas e false se não.
  • use_custom_safety_filter_level: true se um nível de filtro de segurança personalizado foi aplicado. false se o gerador usou apenas os níveis de filtro de segurança padrão.

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 valor true significa que o projeto não está na lista de permissões para usar o recurso de referência de contexto ingerido. Um valor false significa 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ê verá 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 correspondia ao idioma da conversa.

Exemplo de resposta de solução de problemas

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