Accede a información detallada sobre las fallas, el comportamiento de uso de las funciones y la latencia de Knowledge Assist generativo (GKA) y Knowledge Assist generativo proactivo (PGKA). Habilita enable_response_debug_info para ver estos detalles de solución de problemas dentro del objeto knowledge_assist_debug_info.
Configura un perfil de conversación para la solución de problemas
Para acceder a la información de solución de problemas de GKA y PGKA, debes activar el campo enable_response_debug_info en el perfil de conversación. Si este campo está desactivado, la búsqueda de conocimiento te mostrará un error NotFound cuando una consulta no arroje resultados, y el asistente de conocimiento te mostrará un mensaje vacío. Activa enable_response_debug_info para proporcionar una respuesta OK con detalles sobre la falta de resultados. Esta modificación afecta la API y las integraciones existentes.
Asistente de conocimiento generativo (GKA)
Para obtener información detallada sobre la solución de problemas de tus consultas de GKA, debes habilitarla en tu perfil de conversación. Cuando crees o actualices un perfil de conversación, configura el campo enable_response_debug_info como true dentro de human_agent_assistant_config, de la siguiente manera.
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
}
}
}
}
Con el campo enable_response_debug_info habilitado, el generador muestra el objeto knowledge_search_debug_info como parte de SearchKnowledgeResponse junto con las respuestas generadas. Esta información proporciona estadísticas valiosas sobre el rendimiento y el comportamiento de la búsqueda de conocimiento.
Solución de problemas para PGKA V2
Con el enable_response_debug_info field habilitado, el objeto KnowledgeAssistDebugInfo incluye varios campos nuevos específicos para PGKA V2. Para acceder a ellos, baseline_model_version y enable_response_debug_info deben configurarse en 2.0.
A continuación, se muestra el ejemplo de configuración para acceder a la información de solución de problemas en 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",
}
]
}
}
Detalles de la solución de problemas
El objeto search_knowledge_debug_info contiene varios datos clave para ayudarte a solucionar problemas y comprender el proceso de búsqueda de GKA.
Falla de búsqueda o respuesta poco útil
El campo datastore_response_reason te proporciona un estado de alto nivel sobre la calidad de la respuesta o la publicación de datos. Te ayuda a identificar rápidamente por qué podría haber fallado una búsqueda o por qué podría haberse degradado la calidad de la respuesta.
Estos son algunos de los valores posibles:
NONE: La solicitud se procesó sin problemas específicos para informar.SEARCH_OUT_OF_QUOTA: La operación de búsqueda se bloqueó debido a que se excedió la cuota de uso.SEARCH_EMPTY_RESULTS: La búsqueda no mostró documentos de tu Datastore.ANSWER_GENERATION_GEN_AI_DISABLED: Las funciones de IA generativa están inhabilitadas para tu proyecto.ANSWER_GENERATION_OUT_OF_QUOTA: La generación de respuestas se bloqueó debido a que se excedió la cuota de uso.ANSWER_GENERATION_ERROR: Se produjo un error interno durante la generación de respuestas.ANSWER_GENERATION_NOT_ENOUGH_INFO: Los documentos recuperados no tenían suficiente información para generar una respuesta.ANSWER_GENERATION_RAI_FAILED: Los filtros de IA responsable (RAI) bloquearon la respuesta generada.ANSWER_GENERATION_NOT_GROUNDED: El paso de verificación de fundamentación determinó que los documentos fuente no respaldaban fácticamente la respuesta generada y, por lo tanto, se descartó.
Comportamientos activos
El objeto search_knowledge_behavior te indica qué comportamientos específicos estuvieron activos durante la solicitud de GKA.
answer_generation_rewriter_on: Un valortrueindica que el sistema reescribió la consulta del usuario para que sea más eficaz para buscar en Datastore. Un valorfalseindica que el generador no reescribió tu consulta.end_user_metadata_included: Un valortrueindica queend_user_metadatase pasó en la llamada al agente del almacén de datos. Un valorfalseindica queend_user_metadatano se pasó al agente del almacén de datos.
Información de solución de problemas del contexto transferido
El campo ingested_context_reference_debug_info proporciona información de solución de problemas relacionada con el contexto que se transfirió para ayudar a la búsqueda.
project_not_allowlisted: Un valortruesignifica que el proyecto no está en la lista de entidades permitidas para usar la función de referencia de contexto transferido. Un valorfalsesignifica que el proyecto está en la lista de entidades permitidas.context_reference_retrieved: Indica si la referencia de contexto se recuperó correctamente de la base de datos.ingested_parameters_debug_info: Una lista de parámetros transferidos de la referencia de contexto y su estado. Para cada parámetro, verás un nombre de parámetro y uno de los siguientes estados de transferencia.INGESTION_STATUS_SUCCEEDED: El parámetro se transfirió correctamente.INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: El parámetro no estaba disponible para la transferencia.INGESTION_STATUS_PARSE_FAILED: El sistema no pudo analizar el contenido del parámetro.INGESTION_STATUS_INVALID_ENTRY: La referencia de contexto tenía una cantidad inesperada de entradas de contenido (solo debería tener una).INGESTION_STATUS_INVALID_FORMAT: El contenido del contexto no tenía el formato esperado (p.ej., JSON).INGESTION_STATUS_LANGUAGE_MISMATCH: El idioma de la referencia de contexto no coincidía con el idioma de la conversación.
Latencia
El objeto
service_latencydesglosa el tiempo que se dedica a varios servicios internos, lo que te ayuda a identificar los cuellos de botella de rendimiento.internal_service_latencies: Una lista que contiene detalles de latencia para cada paso interno del proceso. Cada entrada incluye un nombre (step), la cantidad de tiempo que tarda en milisegundos (latency_ms) y la hora de inicio (start_time) y finalización (complete_time). Los nombres posibles para un paso del proceso interno son los siguientes:total_data_store_agent: Mide el tiempo total que se tarda en procesar toda la solicitud de GKA, desde que se recibe la consulta hasta que se muestra una respuesta final. Actúa como un cronómetro general para todos los pasos de búsqueda de Datastore para agentes.query_rewrite: El tiempo que se dedica a reescribir la consulta inicial del usuario para que sea más eficaz para buscar en tus documentos de conocimiento.search_query: El tiempo que tarda el agente del almacén de datos en ejecutar la búsqueda en tus almacenes de datos configurados, con la consulta (posiblemente reescrita).summarization: El tiempo que se dedica a generar una respuesta concisa en lenguaje natural a partir de los resultados de la búsqueda recuperados de Datastore (turno de ReAct).grounding: El tiempo que se dedica al proceso de verificación de fundamentación. Este paso fundamental verifica si los documentos fuente respaldan fácticamente la respuesta generada antes de que se muestre.query_generation: El tiempo que se dedica a analizar la conversación en curso y generar de forma proactiva una consulta de búsqueda pertinente.generated_query_rai: El tiempo que se tarda en realizar una verificación de seguridad de IA responsable (RAI) en la consulta generada de forma proactiva antes de que se use para una búsqueda.query_categorization: El tiempo que se dedica a categorizar la consulta generada con Agent Search, si esta función está configurada.
Ejemplo de respuesta de información de solución de problemas
A continuación, se muestra un ejemplo completo de cómo podría verse el objeto search_knowledge_debug_info en una respuesta 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
}
}
]
}
}
}
Asistente de conocimiento generativo proactivo (PGKA)
La solución de problemas proporciona estadísticas detalladas sobre los procesos de generación de consultas, categorización y recuperación de respuestas. El objeto knowledge_assist_debug_info forma parte de knowledge_assist_answer en los resultados de sugerencias.
Cuando crees o actualices un perfil de conversación, configura el campo enable_response_debug_info como true para la función KNOWLEDGE_ASSIST, de la siguiente manera.
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
}
}
}
}
Detalles de la solución de problemas
El objeto knowledge_assist_debug_info contiene los siguientes campos para ayudarte a comprender el ciclo de vida integral de una sugerencia proactiva.
No se pudo generar una consulta
El campo query_generation_failure_reason explica por qué es posible que una conversación no haya generado una consulta de búsqueda proactiva.
QUERY_GENERATION_FAILED: Se produjo un error interno durante la generación de consultas.QUERY_GENERATION_NO_QUERY_GENERATED: El generador decidió no generar una consulta. Esto suele ocurrir cuando el tema de la conversación no cambió o se sugirió recientemente una consulta similar.QUERY_GENERATION_RAI_FAILED: Los filtros de IA responsable (RAI) bloquearon una posible consulta por motivos de seguridad.NOT_IN_ALLOWLIST: Las reglas de filtrado en el perfil de conversación o a nivel del agente bloquearon la generación de consultas.QUERY_GENERATION_QUERY_REDACTED: El generador bloqueó la consulta generada porque contenía información sensible que se ocultó.QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: No se pudo generar la consulta porque el idioma del agente no coincide con el del cliente.QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: No se pudo generar la consulta porque el idioma del mensaje traducido no coincide con el del perfil de conversación.QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: El generador esperaba un mensaje traducido para la generación de consultas, pero no encontró ninguno.QUERY_GENERATION_EMPTY_CONVERSATION: La conversación no tiene mensajes. Esta función solo está disponible para PGKA V2.QUERY_GENERATION_EMPTY_LAST_MESSAGE: El último mensaje estaba vacío o contenía espacios en blanco. Esta función solo está disponible para PGKA V2.QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET: La configuración del evento de activación (p.ej.,AGENT_MESSAGE) no coincidía con el rol del último remitente del mensaje. Esta función solo está disponible para PGKA V2.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: El sistema no pudo analizar el resultado JSON estructurado del modelo. Esta función solo está disponible para PGKA V2.
No se pudo categorizar una consulta
El campo query_categorization_failure_reason explica por qué es posible que haya fallado la categorización de consultas.
QUERY_CATEGORIZATION_INVALID_CONFIG: La configuración de Agent Search proporcionada para la categorización no es válida, por ejemplo, el motor de búsqueda está vacío.QUERY_CATEGORIZATION_RESULT_NOT_FOUND: El resultado de Agent Search no incluyó un resultado de categorización.QUERY_CATEGORIZATION_FAILED: Falló la llamada a Agent Search para la categorización.
Estado de la búsqueda de Datastore
El campo datastore_response_reason proporciona el estado de la búsqueda en tu Datastore después de que se genera una consulta.
NONE: Datastore procesó la solicitud sin problemas específicos para informar.SEARCH_OUT_OF_QUOTA: Agent Assist bloqueó la operación de búsqueda debido a que se excedió la cuota de uso.SEARCH_EMPTY_RESULTS: La búsqueda no mostró documentos de tu Datastore.ANSWER_GENERATION_GEN_AI_DISABLED: Las funciones de IA generativa están inhabilitadas para tu proyecto.ANSWER_GENERATION_OUT_OF_QUOTA: Agent Assist bloqueó la generación de respuestas debido a que se excedió la cuota de uso.ANSWER_GENERATION_ERROR: Se produjo un error interno durante la generación de respuestas.ANSWER_GENERATION_NOT_ENOUGH_INFO: Los documentos recuperados no tenían suficiente información para generar una respuesta.ANSWER_GENERATION_RAI_FAILED: Los filtros de RAI bloquearon la respuesta generada.ANSWER_GENERATION_NOT_GROUNDED: El paso de verificación de fundamentación determinó que los documentos fuente no respaldaban fácticamente la respuesta generada, por lo que se descartó la respuesta.
Configuraciones activas
El objeto knowledge_assist_behavior te indica qué configuraciones específicas estuvieron activas para la solicitud.
answer_generation_rewriter_on:truesi el generador reescribió la consulta para obtener mejores resultados de búsqueda yfalsesi no lo hizo.end_user_metadata_included:truesi el generador pasóend_user_metadataa Datastore yfalsesi no lo hizo.return_query_only:truesi tu perfil está configurado para mostrar solo la consulta de búsqueda generada yfalsesi tu perfil muestra la respuesta completa.use_pubsub_delivery:truesi tu generador está configurado para entregar resultados con Pub/Sub yfalsesi no lo está.disable_sync_delivery:truesi la entrega síncrona de la respuesta está inhabilitada yfalsesi está habilitada.previous_queries_included:truesi el generador consideró las consultas sugeridas anteriormente durante el proceso de generación de consultas yfalsesi no lo hizo.use_translated_message:truesi se usó un mensaje traducido para la generación de consultas yfalsesi no lo hizo.use_custom_safety_filter_level:truesi se aplicó un nivel de filtro de seguridad personalizado.falsesi el generador usó solo los niveles de filtro de seguridad predeterminados.multiple_queries_generated: Un valortrueindica que el modelo produjo más de una consulta. Esta función está disponible para PGKA V2.query_contained_search_context: Un valortrueindica que la consulta generada incluía un contexto de búsqueda. Esta función está disponible para PGKA V2.appended_search_context_count: Indica la cantidad de elementos de contexto (p.ej., "producto", "SO") que se usaron correctamente en la búsqueda. Esta función está disponible para PGKA V2.
Información del contexto transferido
El campo ingested_context_reference_debug_info proporciona información de depuración relacionada con el contexto que se transfirió para ayudar a la búsqueda.
project_not_allowlisted: Un valortruesignifica que el proyecto no está en la lista de entidades permitidas para usar la función de referencia de contexto transferido. Un valorfalsesignifica que el proyecto está en la lista de entidades permitidas.context_reference_retrieved: Indica si la referencia de contexto se recuperó correctamente de la base de datos.ingested_parameters_debug_info: Una lista de parámetros transferidos de la referencia de contexto y su estado. Para cada parámetro, verás un nombre de parámetro y uno de los siguientes estados de transferencia posibles.INGESTION_STATUS_SUCCEEDED: El parámetro se transfirió correctamente.INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: El parámetro no estaba disponible para la transferencia.INGESTION_STATUS_PARSE_FAILED: El sistema no pudo analizar el contenido del parámetro.INGESTION_STATUS_INVALID_ENTRY: La referencia de contexto tenía una cantidad inesperada de entradas de contenido (solo debería tener una).INGESTION_STATUS_INVALID_FORMAT: El contenido del contexto no tenía el formato esperado.INGESTION_STATUS_LANGUAGE_MISMATCH: El idioma de la referencia de contexto no coincidía con el idioma de la conversación.
Ejemplo de respuesta de solución de problemas para PGKA V1
A continuación, se muestra un ejemplo completo de cómo podría verse el objeto knowledge_assist_debug_info en una respuesta.
{
"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
}
}
]
}
}
}
Ejemplo de respuesta de solución de problemas para PGKA V2
A continuación, se muestran ejemplos completos para dos situaciones.
Ejemplo 1: Sugerencia exitosa con indicadores de comportamiento
En esta situación, se ilustra una respuesta en la que el modelo generó correctamente varias consultas y enriqueció la consulta principal con el contexto de búsqueda. A continuación, se explican los campos:
multiple_queries_generated: Indica que el modelo produjo más de un tema pertinente.query_contained_search_context: Confirma que la consulta principal se enriqueció con datos estructurados.appended_search_context_count: La cantidad exacta de pares clave-valor (p.ej., nombre de la aplicación, SO) que se usaron para refinar la búsqueda.
{
"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" }
]
}
}
]
}
}
]
}
Ejemplo 2: Sugerencia omitida con motivo de falla
En esta situación, el sistema determinó que no se debe activar una sugerencia porque no se cumplió la condición del evento (p.ej., el activador se configuró como AGENT_MESSAGE, pero el último mensaje era de END_USER). En lugar de un error, el sistema muestra un estado exitoso con el 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
}
}
]
}
Entre otros motivos comunes de falla, se incluyen los siguientes:
QUERY_GENERATION_EMPTY_CONVERSATION: No se encontraron mensajes en la conversación.QUERY_GENERATION_EMPTY_LAST_MESSAGE: El último mensaje estaba vacío o solo contenía espacios en blanco.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: El sistema no pudo analizar el resultado estructurado del LLM.