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 (ACG) et l'assistance proactive à la connaissance générative (APCG). 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 détails sur l'absence de résultats. Cette modification affecte l'API et les intégrations existantes.

Assistance base de connaissances générative (ABKG)

Pour obtenir des informations détaillées sur le dépannage de vos requêtes GKA, vous devez l'activer 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 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 qui vous aident à résoudre les problèmes et à comprendre le processus de recherche pour GKA.

Échec de la recherche ou réponse inutile

Le champ datastore_response_reason fournit un état général de la diffusion des données ou de la qualité de la réponse. Il vous aide à identifier rapidement pourquoi une recherche a pu échouer ou pourquoi la qualité de la réponse a pu être dégradée.

Les valeurs possibles sont les suivantes :

  • NONE : la requête a été traitée sans problème particulier.
  • SEARCH_OUT_OF_QUOTA : l'opération de recherche a été bloquée en raison du dépassement du quota d'utilisation.
  • 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 en raison du dépassement du quota d'utilisation.
  • 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.
  • 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 du data store. Une valeur false indique que end_user_metadata n'a pas été transmis à l'agent du 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 ingéré pour faciliter la recherche.

  • project_not_allowlisted : une valeur true signifie que le projet n'est 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 avec succès depuis 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 verrez un nom de paramètre et l'un des états d'ingestion suivants.
    • INGESTION_STATUS_SUCCEEDED : le paramètre a bien é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 réussi à 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 devrait 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 du contexte ne correspond pas à celle de la conversation.

Latence

{# disableFinding("data store")}

  • L'objet service_latency détaille le temps passé dans différents services internes, ce qui vous aide à 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), une durée en millisecondes (latency_ms) ainsi qu'une heure de début (start_time) et de fin (complete_time). Voici quelques exemples de noms pour une étape de processus interne :

    • 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 à la réponse finale. Il sert de minuteur global pour toutes les étapes de recherche de l'agent dans le 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 (potentiellement 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 depuis le datastore (tour ReAct).
    • grounding : temps passé sur le processus de validation de l'ancrage. Cette étape cruciale permet de vérifier 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 un contrôle de sécurité de l'IA responsable 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 de Vertex AI Search, si cette fonctionnalité est configurée.

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

Voici un exemple complet de ce à quoi l'objet search_knowledge_debug_info peut ressembler 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 proactive basée sur les connaissances génératives (APBCG)

Le dépannage fournit des informations détaillées sur les processus de génération de requêtes, de catégorisation et de récupération de réponses. 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 complet 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 thème 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 de l'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 requêtes.
  • 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 requêtes, 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 Vertex AI 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 de Vertex AI Search n'incluait pas de résultat de catégorisation.
  • QUERY_CATEGORIZATION_FAILED : l'appel à Vertex AI Search pour la catégorisation a échoué.

État de la recherche Datastore

Le champ datastore_response_reason indique 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 aucun problème spécifique à signaler.
  • SEARCH_OUT_OF_QUOTA : l'assistance de l'agent a bloqué l'opération de recherche en raison du dépassement du quota d'utilisation.
  • 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 la réponse, 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 d'IA responsable ont bloqué la réponse générée.
  • ANSWER_GENERATION_NOT_GROUNDED : l'étape de validation de l'ancrage a déterminé que les documents sources ne soutenaient pas factuellement la réponse générée, qui a donc été supprimée.

Configurations actives

L'objet knowledge_assist_behavior 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 améliorer les 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 tenu compte des requêtes suggérées précédemment lors du processus de génération de requêtes et false dans le cas contraire.
  • use_translated_message : true si un message traduit a été utilisé pour générer 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 issues du contexte ingéré

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

  • project_not_allowlisted : une valeur true signifie que le projet n'est pas autorisé à 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 avec succès depuis 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 verrez un nom de paramètre et l'un des états d'ingestion possibles suivants.
    • INGESTION_STATUS_SUCCEEDED : le paramètre a bien é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 réussi à 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 devrait 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 du 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
          }
        }
      ]
    }
  }
}