Risolvere i problemi relativi alle funzionalità di assistenza della conoscenza

Accedi a informazioni dettagliate su errori, comportamento di utilizzo delle funzionalità e latenza sia per l'assistenza knowledge base generativa (GKA) sia per 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 sia per PGKA, devi attivare il campo enable_response_debug_info nel profilo di conversazione. Se questo campo è disattivato, la ricerca della conoscenza 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 influisce sull'API e sulle integrazioni esistenti.

Assistenza knowledge base generativa (GKA)

Per ottenere informazioni dettagliate per la risoluzione dei problemi relativi alle query GKA, devi attivare questa funzionalità nel profilo di 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
      }
    }
  }
}

Con 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 utili sul rendimento e sul comportamento della ricerca della conoscenza.

Dettagli relativi alla risoluzione dei problemi

L'oggetto search_knowledge_debug_info contiene diverse informazioni chiave che ti aiutano a risolvere i problemi e a comprendere il processo di ricerca per GKA.

Ricerca non riuscita o risposta non utile

Il campo datastore_response_reason fornisce uno stato di alto livello 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 per cui 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 perché è stata superata la quota di utilizzo.
• SEARCH_EMPTY_RESULTS: la ricerca non ha restituito documenti dal datastore.
• ANSWER_GENERATION_GEN_AI_DISABLED: le funzionalità di AI generativa sono disattivate per il progetto.
• ANSWER_GENERATION_OUT_OF_QUOTA: la generazione delle risposte è stata bloccata perché è stata superata la quota di utilizzo.
• ANSWER_GENERATION_ERROR: si è verificato un errore interno durante la generazione delle risposte.
• 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 di 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 e pertanto è stata eliminata.

Comportamenti attivi

L'oggetto search_knowledge_behavior indica quali comportamenti specifici erano attivi durante la richiesta GKA.

• answer_generation_rewriter_on: un valore true indica che il sistema ha riscritto la query dell'utente per renderla più efficace per la ricerca nel datastore. Un valore false indica che il generatore non ha riscritto la query.
• end_user_metadata_included: un valore true indica che end_user_metadata è stato trasmesso nella chiamata all'agente del datastore. Un valore false indica che end_user_metadata non è stato trasmesso all'agente del datastore.

Informazioni per la risoluzione dei problemi dal contesto importato

Il campo ingested_context_reference_debug_info fornisce informazioni per la risoluzione dei problemi relativi al contesto importato per facilitare la ricerca.

• project_not_allowlisted: un valore true indica che il progetto non è nella lista consentita per utilizzare la funzionalità di riferimento del contesto importato. Un valore false indica che il progetto è nella lista consentita.
• context_reference_retrieved: indica se il riferimento del contesto è stato recuperato correttamente dal database.
• ingested_parameters_debug_info: un elenco di parametri importati dal riferimento del contesto e il relativo stato. Per ogni parametro, viene visualizzato un nome del parametro e uno dei seguenti stati di importazione.
  • INGESTION_STATUS_SUCCEEDED: il parametro è stato importato 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 del contesto aveva un numero imprevisto di voci di contenuti (deve averne una sola).
  • INGESTION_STATUS_INVALID_FORMAT: i contenuti del contesto non erano nel formato previsto (ad es. JSON).
  • INGESTION_STATUS_LANGUAGE_MISMATCH: la lingua del riferimento del contesto non corrispondeva alla lingua della conversazione.

Latenza

{# disableFinding("datastore")}

• L'oggetto service_latency suddivide 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 del processo. Ogni voce include un nome (step), la quantità di tempo in millisecondi (latency_ms) e l'ora di inizio (start_time) e di fine (complete_time). I nomi possibili per un passaggio del processo interno 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. Funziona come un timer generale per tutti i passaggi di ricerca dell'agente del datastore.
  • query_rewrite: il tempo trascorso a riscrivere la query iniziale dell'utente per renderla più efficace per la ricerca nei documenti della conoscenza.
  • search_query: il tempo impiegato dall'agente del datastore per eseguire la ricerca nel datastore o nei datastore configurati, utilizzando la query (potenzialmente riscritta).
  • summarization: il tempo trascorso a generare una risposta concisa in linguaggio naturale dai risultati di ricerca recuperati dal datastore (turno ReAct).
  • grounding: il tempo trascorso nella procedura di verifica del grounding. Questo passaggio cruciale verifica se la risposta generata è supportata dai documenti di origine prima di essere restituita.
  • query_generation: il tempo trascorso ad analizzare la conversazione in corso e a generare in modo proattivo una query di ricerca pertinente.
  • generated_query_rai: il tempo impiegato per eseguire un controllo di sicurezza di AI responsabile (RAI) sulla query generata in modo proattivo prima che venga utilizzata per una ricerca.
  • query_categorization: il tempo trascorso a classificare la query generata utilizzando Vertex AI 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 knowledge base generativa proattiva (PGKA)

La risoluzione dei problemi fornisce informazioni approfondite sui processi di generazione, classificazione e recupero delle risposte delle query. L'oggetto knowledge_assist_debug_info fa parte di knowledge_assist_answer all'interno dei risultati dei suggerimenti.

Quando crei o aggiorni un profilo di 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. In genere, 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 di conversazione o di agente hanno bloccato la generazione della 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 alla lingua del cliente.
• QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: la generazione della query non è riuscita perché la lingua del messaggio tradotto non corrisponde alla lingua del profilo di 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.

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 di Vertex AI Search fornita per la classificazione non è valida, ad esempio il motore di ricerca è vuoto.
• QUERY_CATEGORIZATION_RESULT_NOT_FOUND: il risultato di Vertex AI Search non includeva un risultato di classificazione.
• QUERY_CATEGORIZATION_FAILED: la chiamata a Vertex AI Search per la classificazione non è riuscita.

Stato della ricerca nel datastore

Il campo datastore_response_reason fornisce lo stato della ricerca nel datastore dopo la generazione di una query.

• NONE: il 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 datastore.
• ANSWER_GENERATION_GEN_AI_DISABLED: le funzionalità di AI generativa sono disattivate per il progetto.
• ANSWER_GENERATION_OUT_OF_QUOTA: Agent Assist ha bloccato la generazione delle risposte perché è stata superata la quota di utilizzo.
• ANSWER_GENERATION_ERROR: si è verificato un errore interno durante la generazione delle risposte.
• 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 supportavano la risposta generata, pertanto la risposta è stata eliminata.

Configurazioni attive

L'oggetto knowledge_assist_behavior indica quali configurazioni specifiche erano attive per la richiesta.

• answer_generation_rewriter_on: true se il generatore ha riscritto la query per ottenere risultati di ricerca migliori e false in caso contrario.
• end_user_metadata_included: true se il generatore ha passato end_user_metadata al datastore e false in caso contrario.
• return_query_only: true se il profilo è configurato per restituire solo la query di ricerca generata e false se il profilo restituisce la risposta completa.
• use_pubsub_delivery: true se il generatore è configurato per pubblicare i risultati con Pub/Sub e false in caso contrario.
• disable_sync_delivery: true se la pubblicazione sincrona della risposta è disattivata e false se è attivata.
• previous_queries_included: true se il generatore ha considerato le query suggerite in precedenza durante il processo di generazione della query e false in caso contrario.
• use_translated_message: true se è stato utilizzato un messaggio tradotto per la generazione della query e false in caso contrario.
• use_custom_safety_filter_level: true se è stato applicato un livello di filtro di sicurezza personalizzato. false se il generatore ha utilizzato solo i livelli di filtro di sicurezza predefiniti.

Informazioni dal contesto importato

Il campo ingested_context_reference_debug_info fornisce informazioni di debug relative al contesto importato per facilitare la ricerca.

• project_not_allowlisted: un valore true indica che il progetto non è nella lista consentita per utilizzare la funzionalità di riferimento del contesto importato. Un valore false indica che il progetto è nella lista consentita.
• context_reference_retrieved: indica se il riferimento del contesto è stato recuperato correttamente dal database.
• ingested_parameters_debug_info: un elenco di parametri importati dal riferimento del contesto e il relativo stato. Per ogni parametro, viene visualizzato un nome del parametro e uno dei seguenti stati di importazione possibili.
  • INGESTION_STATUS_SUCCEEDED: il parametro è stato importato 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 del contesto aveva un numero imprevisto di voci di contenuti (deve averne una sola).
  • INGESTION_STATUS_INVALID_FORMAT: i contenuti del contesto non erano nel formato previsto.
  • INGESTION_STATUS_LANGUAGE_MISMATCH: la lingua del riferimento del contesto non corrispondeva alla lingua della conversazione.

Esempio di risposta per la risoluzione dei problemi

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