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

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 preziosi sul rendimento e sul comportamento della ricerca nella knowledge base.

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 di alto livello sulla pubblicazione dei dati o sulla qualità delle risposte. 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 della fondatezza 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 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 inserito

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

  • project_not_allowlisted: un valore true indica che il progetto non è incluso nella lista consentita per l'utilizzo della funzionalità di riferimento al contesto inserito. Un valore false significa che il progetto è nella lista consentita.
  • context_reference_retrieved: indica se il riferimento al contesto è stato recuperato correttamente dal database.
  • ingested_parameters_debug_info: un elenco dei parametri inseriti dal riferimento di contesto e il relativo stato. Per ogni parametro, viene visualizzato 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 corrispondeva a quella 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 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 dell'agente del datastore.
    • 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 nel datastore o 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 alla procedura di verifica della fondatezza. Questo passaggio cruciale verifica 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 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 proattiva basata sulla conoscenza generativa (PGKA)

La risoluzione dei problemi fornisce informazioni approfondite sui processi di generazione, categorizzazione 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 filtraggio 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 della conversazione.
  • QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: il generatore si aspettava un messaggio tradotto per la generazione di 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 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: Assistente basato sull'IA 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: 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 superato end_user_metadata a Datastore e false in caso contrario.
  • return_query_only: true se il tuo profilo è configurato per restituire solo la query di ricerca generata e false se il tuo profilo restituisce la risposta completa.
  • use_pubsub_delivery: true se il generatore è configurato per fornire risultati con Pub/Sub e false in caso contrario.
  • disable_sync_delivery: true se la pubblicazione sincrona della risposta è disattivata e false se la pubblicazione sincrona della risposta è attivata.
  • previous_queries_included: true se il generatore ha preso in considerazione le query suggerite in precedenza durante il processo di generazione delle 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 personalizzato. false se il generatore ha utilizzato solo i livelli predefiniti dei filtri di sicurezza.

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 valore true indica che il progetto non è incluso nella lista consentita per l'utilizzo della funzionalità di riferimento al contesto inserito. Un valore false significa che il progetto è nella lista consentita.
  • context_reference_retrieved: indica se il riferimento al contesto è stato recuperato correttamente dal database.
  • ingested_parameters_debug_info: un elenco dei 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: I contenuti del contesto non erano nel formato previsto.
    • INGESTION_STATUS_LANGUAGE_MISMATCH: La lingua del riferimento al contesto non corrispondeva a quella 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
          }
        }
      ]
    }
  }
}