Résoudre les problèmes liés aux fonctionnalités d'assistance pour les connaissances

Accédez à des informations détaillées sur les échecs, le comportement d'utilisation des fonctionnalités et la latence pour l'assistance à la connaissance générative (GKA) et l'assistance à la connaissance générative proactive (PGKA). Activez enable_response_debug_info pour afficher ces informations de dépannage dans l'objet knowledge_assist_debug_info.

Configurer un profil de conversation pour le dépannage

Pour accéder aux informations de dépannage pour GKA et PGKA, vous devez activer le champ enable_response_debug_info dans le profil de conversation. Si ce champ est désactivé, la recherche de connaissances renvoie une erreur NotFound lorsqu'une requête ne donne aucun résultat, et l'assistance base de connaissances renvoie un message vide. Activez enable_response_debug_info pour fournir une réponse OK avec des informations sur l'absence de résultats. Cette modification affecte l'API et les intégrations existantes.

Assistance à la connaissance générative (GKA)

Pour obtenir des informations de dépannage détaillées sur vos requêtes GKA, vous devez activer cette fonctionnalité dans votre profil de conversation. Lorsque vous créez ou mettez à jour un profil de conversation, définissez le champ enable_response_debug_info sur true dans human_agent_assistant_config, comme suit.

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

Lorsque le champ enable_response_debug_info est activé, le générateur renvoie l'objet knowledge_search_debug_info dans le cadre de SearchKnowledgeResponse, ainsi que les réponses générées. Ces informations fournissent des insights précieux sur les performances et le comportement de la recherche de connaissances.

Instructions de dépannage détaillées

L'objet search_knowledge_debug_info contient plusieurs informations clés pour vous aider à résoudre les problèmes et à comprendre le processus de recherche pour GKA.

Échec de la recherche ou réponse non utile

Le champ datastore_response_reason vous donne un état de haut niveau sur la diffusion des données ou la qualité des réponses. Il vous aide à identifier rapidement pourquoi une recherche a pu échouer ou pourquoi la qualité des réponses a pu être dégradée.

Les valeurs possibles sont les suivantes :

  • NONE: la requête a été traitée sans problème spécifique à signaler.
  • SEARCH_OUT_OF_QUOTA: l'opération de recherche a été bloquée, car le quota d'utilisation a été dépassé.
  • SEARCH_EMPTY_RESULTS: la recherche n'a renvoyé aucun document de votre datastore.
  • ANSWER_GENERATION_GEN_AI_DISABLED: les fonctionnalités d'IA générative sont désactivées pour votre projet.
  • ANSWER_GENERATION_OUT_OF_QUOTA: la génération de réponses a été bloquée, car le quota d'utilisation a été dépassé.
  • ANSWER_GENERATION_ERROR: une erreur interne s'est produite lors de la génération de la réponse.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: les documents récupérés ne contenaient pas suffisamment d'informations pour générer une réponse.
  • ANSWER_GENERATION_RAI_FAILED: la réponse générée a été bloquée par les filtres d'IA responsable (RAI).
  • ANSWER_GENERATION_NOT_GROUNDED: l'étape de vérification de l'ancrage a déterminé que la réponse générée n'était pas factuellement étayée par les documents sources et a donc été supprimée.

Comportements actifs

L'objet search_knowledge_behavior vous indique les comportements spécifiques qui étaient actifs lors de la requête GKA.

  • answer_generation_rewriter_on: une valeur true indique que le système a réécrit la requête de l'utilisateur pour qu'elle soit plus efficace pour la recherche dans le datastore. Une valeur false indique que le générateur n'a pas réécrit votre requête.
  • end_user_metadata_included : une valeur true indique que end_user_metadata a été transmis lors de l'appel à l'agent de data store. Une valeur false indique que end_user_metadata n'a pas été transmis à l'agent de data store.

Informations de dépannage à partir du contexte ingéré

Le champ ingested_context_reference_debug_info fournit des informations de dépannage liées au contexte qui a été ingéré pour faciliter la recherche.

  • project_not_allowlisted: une valeur true signifie que le projet ne figure pas sur la liste d'autorisation pour utiliser la fonctionnalité de référence de contexte ingéré. Une valeur false signifie que le projet figure sur la liste d'autorisation.
  • context_reference_retrieved: indique si la référence de contexte a été récupérée de la base de données.
  • ingested_parameters_debug_info: liste des paramètres ingérés à partir de la référence de contexte et de leur état. Pour chaque paramètre, vous voyez un nom de paramètre et l'un des états d'ingestion suivants.
    • INGESTION_STATUS_SUCCEEDED : le paramètre a été ingéré.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE : le paramètre n'était pas disponible pour l'ingestion.
    • INGESTION_STATUS_PARSE_FAILED : le système n'a pas pu analyser le contenu du paramètre.
    • INGESTION_STATUS_INVALID_ENTRY : la référence de contexte comportait un nombre inattendu d'entrées de contenu (elle ne doit en comporter qu'une seule).
    • INGESTION_STATUS_INVALID_FORMAT : le contenu du contexte n'était pas au format attendu (par exemple, JSON).
    • INGESTION_STATUS_LANGUAGE_MISMATCH : la langue de la référence de contexte ne correspond pas à celle de la conversation.

Latence

{# disableFinding("data store")}

  • L'objet service_latency décompose le temps passé dans différents services internes, ce qui vous permet d'identifier les goulots d'étranglement des performances.

  • internal_service_latencies: liste contenant des informations sur la latence pour chaque étape interne du processus. Chaque entrée inclut un nom (step), le temps nécessaire en millisecondes (latency_ms), ainsi que l'heure de début (start_time) et de fin (complete_time). Les noms possibles pour une étape de processus interne sont les suivants :

    • total_data_store_agent: mesure le temps total nécessaire au traitement de l'ensemble de la requête GKA, de la réception de la requête au renvoi d'une réponse finale. Il agit comme un minuteur global pour toutes les étapes de recherche de l'agent de data store.
    • query_rewrite: temps passé à réécrire la requête initiale de l'utilisateur pour qu'elle soit plus efficace pour la recherche dans vos documents de connaissances.
    • search_query: temps nécessaire à l'agent de data store pour exécuter la recherche dans le ou les data store configurés, à l'aide de la requête (éventuellement réécrite).
    • summarization: temps passé à générer une réponse concise en langage naturel à partir des résultats de recherche récupérés dans le datastore (tour ReAct).
    • grounding: temps passé sur le processus de vérification de l'ancrage. Cette étape cruciale vérifie si la réponse générée est factuellement étayée par les documents sources avant d'être renvoyée.
    • query_generation: temps passé à analyser la conversation en cours et à générer de manière proactive une requête de recherche pertinente.
    • generated_query_rai: temps nécessaire pour effectuer une vérification de sécurité de l'IA responsable (RAI) sur la requête générée de manière proactive avant qu'elle ne soit utilisée pour une recherche.
    • query_categorization: temps passé à catégoriser la requête générée à l'aide d'Agent Search, si cette fonctionnalité est configurée.

Exemple de réponse contenant des informations de dépannage

Voici un exemple complet de l'objet search_knowledge_debug_info dans une réponse 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
            }
        }
      ]
    }
  }
}

Assistance à la connaissance générative proactive (PGKA)

Le dépannage fournit des insights approfondis sur les processus de génération, de catégorisation et de récupération des requêtes. L'objet knowledge_assist_debug_info fait partie de knowledge_assist_answer dans les résultats de vos suggestions.

Lorsque vous créez ou mettez à jour un profil de conversation, définissez le champ enable_response_debug_info sur true pour la fonctionnalité KNOWLEDGE_ASSIST, comme suit.

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

Instructions de dépannage détaillées

L'objet knowledge_assist_debug_info contient les champs suivants pour vous aider à comprendre le cycle de vie de bout en bout d'une suggestion proactive.

Échec de la génération d'une requête

Le champ query_generation_failure_reason explique pourquoi une conversation n'a peut-être pas généré de requête de recherche proactive.

  • QUERY_GENERATION_FAILED: une erreur interne s'est produite lors de la génération de la requête.
  • QUERY_GENERATION_NO_QUERY_GENERATED: le générateur a décidé de ne pas générer de requête. Cela se produit généralement lorsque le sujet de la conversation n'a pas changé ou qu'une requête similaire a été suggérée récemment.
  • QUERY_GENERATION_RAI_FAILED: les filtres d'IA responsable (RAI) ont bloqué une requête potentielle pour des raisons de sécurité.
  • NOT_IN_ALLOWLIST: les règles de filtrage au niveau du profil de conversation ou de l'agent ont bloqué la génération de la requête.
  • QUERY_GENERATION_QUERY_REDACTED: le générateur a bloqué la requête générée, car elle contenait des informations sensibles qui ont été masquées.
  • QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: la génération de la requête a échoué, car la langue de l'agent ne correspond pas à celle du client.
  • QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: la génération de la requête a échoué, car la langue du message traduit ne correspond pas à celle du profil de conversation.
  • QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: le générateur attendait un message traduit pour la génération de la requête, mais n'en a pas trouvé.

Échec de la catégorisation d'une requête

Le champ query_categorization_failure_reason explique pourquoi la catégorisation de la requête a pu échouer.

  • QUERY_CATEGORIZATION_INVALID_CONFIG: la configuration d'Agent Search fournie pour la catégorisation n'est pas valide (par exemple, le moteur de recherche est vide).
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: le résultat d'Agent Search n'incluait pas de résultat de catégorisation.
  • QUERY_CATEGORIZATION_FAILED: l'appel à Agent Search pour la catégorisation a échoué.

État de la recherche dans le datastore

Le champ datastore_response_reason fournit l'état de la recherche dans votre datastore après la génération d'une requête.

  • NONE: le datastore a traité la requête sans problème spécifique à signaler.
  • SEARCH_OUT_OF_QUOTA: Agent Assist a bloqué l'opération de recherche, car le quota d'utilisation a été dépassé.
  • SEARCH_EMPTY_RESULTS: la recherche n'a renvoyé aucun document de votre datastore.
  • ANSWER_GENERATION_GEN_AI_DISABLED: les fonctionnalités d'IA générative sont désactivées pour votre projet.
  • ANSWER_GENERATION_OUT_OF_QUOTA: Agent Assist a bloqué la génération de réponses, car le quota d'utilisation a été dépassé.
  • ANSWER_GENERATION_ERROR: une erreur interne s'est produite lors de la génération de la réponse.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: les documents récupérés ne contenaient pas suffisamment d'informations pour générer une réponse.
  • ANSWER_GENERATION_RAI_FAILED: les filtres RAI ont bloqué la réponse générée.
  • ANSWER_GENERATION_NOT_GROUNDED: l'étape de vérification de l'ancrage a déterminé que les documents sources n'étayaient pas factuellement la réponse générée, qui a donc été supprimée.

Configurations actives

L'objet knowledge_assist_behavior vous indique les configurations spécifiques qui étaient actives pour la requête.

  • answer_generation_rewriter_on: true si le générateur a réécrit la requête pour obtenir de meilleurs résultats de recherche, et false dans le cas contraire.
  • end_user_metadata_included : true si le générateur a transmis end_user_metadata au datastore, et false dans le cas contraire.
  • return_query_only: true si votre profil est configuré pour ne renvoyer que la requête de recherche générée, et false si votre profil renvoie la réponse complète.
  • use_pubsub_delivery: true si votre générateur est configuré pour fournir des résultats avec Pub/Sub, et false dans le cas contraire.
  • disable_sync_delivery: true si la diffusion synchrone de la réponse est désactivée, et false si elle est activée.
  • previous_queries_included: true si le générateur a pris en compte les requêtes suggérées précédemment lors du processus de génération de la requête, et false dans le cas contraire.
  • use_translated_message: true si un message traduit a été utilisé pour la génération de la requête, et false dans le cas contraire.
  • use_custom_safety_filter_level: true si un niveau de filtre de sécurité personnalisé a été appliqué. false si le générateur n'a utilisé que les niveaux de filtre de sécurité par défaut.

Informations à partir du contexte ingéré

Le champ ingested_context_reference_debug_info fournit des informations de débogage liées au contexte qui a été ingéré pour faciliter la recherche.

  • project_not_allowlisted: une valeur true signifie que le projet ne figure pas sur la liste d'autorisation pour utiliser la fonctionnalité de référence de contexte ingéré. Une valeur false signifie que le projet figure sur la liste d'autorisation.
  • context_reference_retrieved: indique si la référence de contexte a été récupérée de la base de données.
  • ingested_parameters_debug_info: liste des paramètres ingérés à partir de la référence de contexte et de leur état. Pour chaque paramètre, vous voyez un nom de paramètre et l'un des états d'ingestion possibles suivants.
    • INGESTION_STATUS_SUCCEEDED : le paramètre a été ingéré.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE : le paramètre n'était pas disponible pour l'ingestion.
    • INGESTION_STATUS_PARSE_FAILED : le système n'a pas pu analyser le contenu du paramètre.
    • INGESTION_STATUS_INVALID_ENTRY : la référence de contexte comportait un nombre inattendu d'entrées de contenu (elle ne doit en comporter qu'une seule).
    • INGESTION_STATUS_INVALID_FORMAT : le contenu du contexte n'était pas au format attendu.
    • INGESTION_STATUS_LANGUAGE_MISMATCH : la langue de la référence de contexte ne correspond pas à celle de la conversation.

Exemple de réponse de dépannage

Voici un exemple complet de l'objet knowledge_assist_debug_info dans une réponse. 

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