Accedi a informazioni dettagliate su errori, comportamento di utilizzo delle funzionalità e latenza per l'assistenza knowledge base generativa (GKA) e l'assistenza knowledge base generativa proattiva (PGKA). Attiva enable_response_debug_info per visualizzare questi dettagli per la risoluzione dei problemi all'interno dell'oggetto knowledge_assist_debug_info.
Configurare un profilo di conversazione per la risoluzione dei problemi
Per accedere alle informazioni per la risoluzione dei problemi sia per GKA che per PGKA, devi attivare il campo enable_response_debug_info nel profilo della conversazione. Se questo campo è disattivato, la ricerca nella knowledge base restituisce un errore NotFound quando una query non produce risultati e l'assistenza knowledge base restituisce un messaggio vuoto. Attiva enable_response_debug_info per fornire una risposta OK con i dettagli sulla mancanza di risultati. Questa modifica interessa l'API e le integrazioni esistenti.
Assistenza knowledge base generativa (GKA)
Per ottenere informazioni dettagliate sulla risoluzione dei problemi relativi alle query GKA, devi attivare questa opzione nel tuo profilo conversazione. Quando crei o aggiorni un profilo di conversazione, imposta il campo enable_response_debug_info su true all'interno di human_agent_assistant_config, come segue.
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
}
}
}
}
Se il campo enable_response_debug_info è attivato, il generatore restituisce l'oggetto knowledge_search_debug_info come parte di SearchKnowledgeResponse insieme alle risposte generate. Queste informazioni forniscono approfondimenti preziosi sul rendimento e sul comportamento della ricerca nella knowledge base.
Risoluzione dei problemi per PGKA V2
Con enable_response_debug_info field attivato, l'oggetto KnowledgeAssistDebugInfo include diversi nuovi campi specifici per PGKA V2. Per accedere a questa funzionalità, baseline_model_version e enable_response_debug_info devono essere impostati su 2.0.
Di seguito è riportato l'esempio di configurazione per accedere alle informazioni per la risoluzione dei problemi in 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",
}
]
}
}
Dettagli relativi alla risoluzione dei problemi
L'oggetto search_knowledge_debug_info contiene diverse informazioni chiave per aiutarti a risolvere i problemi e comprendere la procedura di ricerca per GKA.
Ricerca non riuscita o risposta non utile
Il campo datastore_response_reason fornisce uno stato generale sulla pubblicazione dei dati o sulla qualità della risposta. Ti aiuta a identificare rapidamente il motivo per cui una ricerca potrebbe non essere riuscita o perché la qualità della risposta potrebbe essere peggiorata.
I valori possibili sono:
NONE: la richiesta è stata elaborata senza problemi specifici da segnalare.SEARCH_OUT_OF_QUOTA: l'operazione di ricerca è stata bloccata a causa del superamento della quota di utilizzo.SEARCH_EMPTY_RESULTS: la ricerca non ha restituito documenti dal tuo Datastore.ANSWER_GENERATION_GEN_AI_DISABLED: le funzionalità di AI generativa sono disattivate per il tuo progetto.ANSWER_GENERATION_OUT_OF_QUOTA: la generazione di risposte è stata bloccata a causa del superamento della quota di utilizzo.ANSWER_GENERATION_ERROR: si è verificato un errore interno durante la generazione della risposta.ANSWER_GENERATION_NOT_ENOUGH_INFO: I documenti recuperati non contenevano informazioni sufficienti per generare una risposta.ANSWER_GENERATION_RAI_FAILED: la risposta generata è stata bloccata dai filtri AI responsabile (RAI).ANSWER_GENERATION_NOT_GROUNDED: il passaggio di verifica del grounding ha stabilito che la risposta generata non era supportata dai documenti di origine ed è stata quindi scartata.
Comportamenti attivi
L'oggetto search_knowledge_behavior indica quali comportamenti specifici erano attivi durante la richiesta GKA.
answer_generation_rewriter_on: un valoretrueindica che il sistema ha riscritto la query dell'utente per renderla più efficace per la ricerca nel datastore. Un valorefalseindica che il generatore non ha riscritto la query.end_user_metadata_included: un valoretrueindica cheend_user_metadataè stato trasmesso nella chiamata all'agente del datastore. Un valorefalseindica cheend_user_metadatanon è stato trasmesso all'agente del datastore.
Informazioni per la risoluzione dei problemi dal contesto inserito
Il campo ingested_context_reference_debug_info fornisce informazioni per la risoluzione dei problemi relative al contesto inserito per facilitare la ricerca.
project_not_allowlisted: un valoretrueindica che il progetto non è presente nella lista consentita per l'utilizzo della funzionalità di riferimento al contesto inserito. Un valorefalseindica che il progetto è presente nella lista consentita.context_reference_retrieved: indica se il riferimento al contesto è stato recuperato correttamente dal database.ingested_parameters_debug_info: un elenco di parametri inseriti dal riferimento di contesto e il relativo stato. Per ogni parametro, vengono visualizzati un nome e uno dei seguenti stati di importazione.INGESTION_STATUS_SUCCEEDED: Il parametro è stato inserito correttamente.INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: Il parametro non era disponibile per l'importazione.INGESTION_STATUS_PARSE_FAILED: il sistema non è riuscito ad analizzare i contenuti del parametro.INGESTION_STATUS_INVALID_ENTRY: il riferimento al contesto aveva un numero imprevisto di voci di contenuti (deve averne solo una).INGESTION_STATUS_INVALID_FORMAT: I contenuti del contesto non erano nel formato previsto (ad es. JSON).INGESTION_STATUS_LANGUAGE_MISMATCH: La lingua del riferimento al contesto non corrisponde a quella della conversazione.
Latenza
L'oggetto
service_latencysuddivide il tempo trascorso in vari servizi interni, aiutandoti a individuare i colli di bottiglia delle prestazioni.internal_service_latencies: un elenco contenente i dettagli della latenza per ogni passaggio interno della procedura. Ogni voce include un nome (step), la quantità di tempo necessaria in millisecondi (latency_ms) e l'ora di inizio (start_time) e di fine (complete_time). I possibili nomi per un passaggio della procedura interna sono i seguenti:total_data_store_agent: misura il tempo totale impiegato per elaborare l'intera richiesta GKA, dalla ricezione della query alla restituzione di una risposta finale. Funge da timer generale per tutti i passaggi di ricerca del datastore per gli agenti.query_rewrite: il tempo impiegato per riscrivere la query iniziale dell'utente in modo che sia più efficace per la ricerca nei documenti della knowledge base.search_query: il tempo impiegato dall'agente del datastore per eseguire la ricerca nei datastore configurati, utilizzando la query (potenzialmente riscritta).summarization: il tempo impiegato per generare una risposta concisa in linguaggio naturale dai risultati di ricerca recuperati da Datastore (turno ReAct).grounding: il tempo dedicato al processo di verifica della fondatezza. Questo passaggio cruciale controlla se la risposta generata è supportata dai documenti di origine prima di essere restituita.query_generation: il tempo dedicato all'analisi della conversazione in corso e alla generazione proattiva di una query di ricerca pertinente.generated_query_rai: il tempo impiegato per eseguire un controllo di sicurezza dell'AI responsabile (RAI) sulla query generata in modo proattivo prima che venga utilizzata per una ricerca.query_categorization: il tempo dedicato alla classificazione della query generata utilizzando Agent Search, se questa funzionalità è configurata.
Esempio di risposta con informazioni per la risoluzione dei problemi
Di seguito è riportato un esempio completo di come potrebbe apparire l'oggetto search_knowledge_debug_info in una risposta 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
}
}
]
}
}
}
Assistenza proattiva basata sulla conoscenza generativa (PGKA)
La risoluzione dei problemi fornisce informazioni dettagliate sui processi di generazione, classificazione e recupero delle risposte. L'oggetto knowledge_assist_debug_info fa parte di knowledge_assist_answer nei risultati dei suggerimenti.
Quando crei o aggiorni un profilo conversazione, imposta il campo enable_response_debug_info su true per la funzionalità KNOWLEDGE_ASSIST, come segue.
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
}
}
}
}
Dettagli relativi alla risoluzione dei problemi
L'oggetto knowledge_assist_debug_info contiene i seguenti campi per aiutarti a comprendere il ciclo di vita end-to-end di un suggerimento proattivo.
Impossibile generare una query
Il campo query_generation_failure_reason spiega perché una conversazione potrebbe non aver generato una query di ricerca proattiva.
QUERY_GENERATION_FAILED: si è verificato un errore interno durante la generazione della query.QUERY_GENERATION_NO_QUERY_GENERATED: il generatore ha deciso di non generare una query. Di solito questo accade quando l'argomento della conversazione non è cambiato o è stata suggerita di recente una query simile.QUERY_GENERATION_RAI_FAILED: i filtri di AI responsabile (RAI) hanno bloccato una potenziale query per motivi di sicurezza.NOT_IN_ALLOWLIST: le regole di filtro a livello di profilo conversazione o agente hanno bloccato la generazione di query.QUERY_GENERATION_QUERY_REDACTED: il generatore ha bloccato la query generata perché conteneva informazioni sensibili che sono state oscurate.QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: la generazione della query non è riuscita perché la lingua dell'agente non corrisponde a quella del cliente.QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: la generazione della query non è riuscita perché la lingua del messaggio tradotto non corrisponde a quella del profilo conversazione.QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: il generatore si aspettava un messaggio tradotto per la generazione della query, ma non ne ha trovato uno.QUERY_GENERATION_EMPTY_CONVERSATION: La conversazione non ha messaggi. Questa funzionalità è disponibile solo per PGKA V2.QUERY_GENERATION_EMPTY_LAST_MESSAGE: L'ultimo messaggio era vuoto o conteneva spazi vuoti. Questa funzionalità è disponibile solo per PGKA V2.QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET: la configurazione dell'evento trigger (ad es.AGENT_MESSAGE) non corrisponde al ruolo dell'ultimo mittente del messaggio. Questa funzionalità è disponibile solo per PGKA V2.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: il sistema non è riuscito ad analizzare l'output JSON strutturato del modello. Questa funzionalità è disponibile solo per PGKA V2.
Impossibile classificare una query
Il campo query_categorization_failure_reason spiega perché la classificazione delle query potrebbe non essere riuscita.
QUERY_CATEGORIZATION_INVALID_CONFIG: la configurazione della ricerca dell'agente fornita per la classificazione non è valida, ad esempio il motore di ricerca è vuoto.QUERY_CATEGORIZATION_RESULT_NOT_FOUND: il risultato della ricerca dell'agente non includeva un risultato di classificazione.QUERY_CATEGORIZATION_FAILED: la chiamata alla ricerca dell'agente per la classificazione non è riuscita.
Stato della ricerca Datastore
Il campo datastore_response_reason fornisce lo stato della ricerca nel datastore dopo la generazione di una query.
NONE: Datastore ha elaborato la richiesta senza problemi specifici da segnalare.SEARCH_OUT_OF_QUOTA: Agent Assist ha bloccato l'operazione di ricerca perché è stata superata la quota di utilizzo.SEARCH_EMPTY_RESULTS: la ricerca non ha restituito documenti dal tuo Datastore.ANSWER_GENERATION_GEN_AI_DISABLED: le funzionalità di AI generativa sono disattivate per il tuo progetto.ANSWER_GENERATION_OUT_OF_QUOTA: Agent Assist ha bloccato la generazione di risposte a causa del superamento della quota di utilizzo.ANSWER_GENERATION_ERROR: si è verificato un errore interno durante la generazione della risposta.ANSWER_GENERATION_NOT_ENOUGH_INFO: I documenti recuperati non contenevano informazioni sufficienti per generare una risposta.ANSWER_GENERATION_RAI_FAILED: i filtri RAI hanno bloccato la risposta generata.ANSWER_GENERATION_NOT_GROUNDED: il passaggio di verifica del grounding ha stabilito che i documenti di origine non supportano fattualmente la risposta generata, pertanto la risposta è stata scartata.
Configurazioni attive
L'oggetto knowledge_assist_behavior indica quali configurazioni specifiche erano attive per la richiesta.
answer_generation_rewriter_on:truese il generatore ha riscritto la query per ottenere risultati di ricerca migliori efalsein caso contrario.end_user_metadata_included:truese il generatore ha superatoend_user_metadataa Datastore efalsein caso contrario.return_query_only:truese il tuo profilo è configurato per restituire solo la query di ricerca generata efalsese il tuo profilo restituisce la risposta completa.use_pubsub_delivery:truese il generatore è configurato per fornire risultati con Pub/Sub efalsein caso contrario.disable_sync_delivery:truese la pubblicazione sincrona della risposta è disattivata efalsese la pubblicazione sincrona della risposta è attivata.previous_queries_included:truese il generatore ha preso in considerazione le query suggerite in precedenza durante il processo di generazione delle query efalsein caso contrario.use_translated_message:truese è stato utilizzato un messaggio tradotto per la generazione della query efalsein caso contrario.use_custom_safety_filter_level:truese è stato applicato un livello di filtro personalizzato.falsese il generatore ha utilizzato solo i livelli predefiniti dei filtri di sicurezza.multiple_queries_generated: un valoretrueindica che il modello ha prodotto più di una query. Questa funzionalità è disponibile per PGKA V2.query_contained_search_context: un valoretrueindica che la query generata includeva un contesto di ricerca. Questa funzionalità è disponibile per PGKA V2.appended_search_context_count: indica il numero di elementi di contesto (ad es. "prodotto", "sistema operativo") utilizzati correttamente nella ricerca. Questa funzionalità è disponibile per PGKA V2.
Informazioni dal contesto acquisito
Il campo ingested_context_reference_debug_info fornisce informazioni di debug relative al contesto inserito per facilitare la ricerca.
project_not_allowlisted: un valoretrueindica che il progetto non è presente nella lista consentita per l'utilizzo della funzionalità di riferimento al contesto inserito. Un valorefalseindica che il progetto è presente nella lista consentita.context_reference_retrieved: indica se il riferimento al contesto è stato recuperato correttamente dal database.ingested_parameters_debug_info: un elenco di parametri inseriti dal riferimento di contesto e il relativo stato. Per ogni parametro, viene visualizzato un nome e uno dei seguenti stati di importazione possibili.INGESTION_STATUS_SUCCEEDED: Il parametro è stato inserito correttamente.INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: Il parametro non era disponibile per l'importazione.INGESTION_STATUS_PARSE_FAILED: il sistema non è riuscito ad analizzare i contenuti del parametro.INGESTION_STATUS_INVALID_ENTRY: il riferimento al contesto aveva un numero imprevisto di voci di contenuti (deve averne solo una).INGESTION_STATUS_INVALID_FORMAT: Il contenuto del contesto non era nel formato previsto.INGESTION_STATUS_LANGUAGE_MISMATCH: La lingua del riferimento al contesto non corrisponde a quella della conversazione.
Esempio di risposta per la risoluzione dei problemi per PGKA V1
Di seguito è riportato un esempio completo di come potrebbe apparire l'oggetto knowledge_assist_debug_info in una risposta.
{
"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
}
}
]
}
}
}
Esempio di risposta per la risoluzione dei problemi per PGKA V2
Di seguito sono riportati esempi esaustivi per due scenari.
Esempio 1: suggerimento riuscito con flag di comportamento
Questo scenario illustra una risposta in cui il modello ha generato correttamente più query e ha arricchito la query principale con il contesto di ricerca. Di seguito sono riportate le spiegazioni dei campi:
multiple_queries_generated: indica che il modello ha prodotto più di un argomento pertinente.query_contained_search_context: conferma che la query principale è stata arricchita con dati strutturati.appended_search_context_count: il numero esatto di coppie chiave-valore (ad es. nome dell'applicazione, sistema operativo) utilizzate per perfezionare la ricerca.
{
"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" }
]
}
}
]
}
}
]
}
Esempio 2: suggerimento ignorato con motivo dell'errore
In questo scenario, il sistema ha stabilito che un suggerimento non deve essere attivato perché la condizione dell'evento non è stata soddisfatta (ad esempio, il trigger è stato impostato su AGENT_MESSAGE, ma l'ultimo messaggio è stato inviato da END_USER). Invece di un errore, il sistema restituisce uno stato di successo con il motivo specifico.
{
"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
}
}
]
}
Altri motivi comuni di mancato completamento della verifica sono:
QUERY_GENERATION_EMPTY_CONVERSATION: Non sono stati trovati messaggi nella conversazione.QUERY_GENERATION_EMPTY_LAST_MESSAGE: l'ultimo messaggio era vuoto o conteneva solo spazi vuoti.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: il sistema non è riuscito ad analizzare l'output strutturato del LLM.