Fehlerbehebung bei Funktionen zur Wissensunterstützung

Sie können auf detaillierte Informationen zu Fehlern, zur Nutzung von Funktionen und zur Latenz sowohl für die generative Wissensunterstützung (Generative Knowledge Assist, GKA) als auch für die proaktive generative Wissensunterstützung (Proactive Generative Knowledge Assist, PGKA) zugreifen. Aktivieren Sie enable_response_debug_info, um diese Details zur Fehlerbehebung im knowledge_assist_debug_info-Objekt aufzurufen.

Unterhaltungsprofil zur Fehlerbehebung konfigurieren

Wenn Sie auf Informationen zur Fehlerbehebung für GKA und PGKA zugreifen möchten, müssen Sie das Feld enable_response_debug_info im Unterhaltungsprofil aktivieren. Wenn dieses Feld deaktiviert ist, erhalten Sie bei der Wissenssuche einen NotFound-Fehler, wenn eine Anfrage keine Ergebnisse liefert, und bei Knowledge Assist eine leere Meldung. Aktivieren Sie enable_response_debug_info, um eine OK-Antwort mit Details zum Fehlen von Ergebnissen zu erhalten. Diese Änderung betrifft die API und bestehende Integrationen.

Generative Knowledge Assist (GKA)

Wenn Sie detaillierte Informationen zur Fehlerbehebung für Ihre GKA-Anfragen erhalten möchten, müssen Sie diese in Ihrem Unterhaltungsprofil aktivieren. Legen Sie beim Erstellen oder Aktualisieren eines Unterhaltungsprofils das Feld enable_response_debug_info in human_agent_assistant_config auf true fest, wie unten dargestellt.

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

Wenn das Feld enable_response_debug_info aktiviert ist, gibt der Generator das knowledge_search_debug_info-Objekt als Teil von SearchKnowledgeResponse zusammen mit den generierten Antworten zurück. Diese Informationen liefern wertvolle Einblicke in die Leistung und das Verhalten der Wissenssuche.

Details zur Fehlerbehebung

Das search_knowledge_debug_info-Objekt enthält mehrere wichtige Informationen, die Ihnen bei der Fehlerbehebung und beim Verständnis des Suchvorgangs für GKA helfen.

Fehler bei der Suche oder nicht hilfreiche Antwort

Das Feld datastore_response_reason enthält einen allgemeinen Status zur Datenbereitstellung oder Antwortqualität. So können Sie schnell herausfinden, warum eine Suche fehlgeschlagen ist oder warum die Qualität der Antwort möglicherweise beeinträchtigt ist.

Mögliche Werte:

  • NONE: Die Anfrage wurde ohne besondere Probleme verarbeitet.
  • SEARCH_OUT_OF_QUOTA: Der Suchvorgang wurde aufgrund einer Überschreitung des Nutzungskontingents blockiert.
  • SEARCH_EMPTY_RESULTS: Bei der Suche wurden keine Dokumente aus Ihrem Datastore zurückgegeben.
  • ANSWER_GENERATION_GEN_AI_DISABLED: Generative KI-Funktionen sind für Ihr Projekt deaktiviert.
  • ANSWER_GENERATION_OUT_OF_QUOTA: Die Antwortgenerierung wurde aufgrund einer Überschreitung des Nutzungskontingents blockiert.
  • ANSWER_GENERATION_ERROR: Beim Generieren der Antwort ist ein interner Fehler aufgetreten.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: Die abgerufenen Dokumente enthielten nicht genügend Informationen, um eine Antwort zu generieren.
  • ANSWER_GENERATION_RAI_FAILED: Die generierte Antwort wurde durch Filter für verantwortungsbewusste Anwendung von KI (Responsible AI, RAI) blockiert.
  • ANSWER_GENERATION_NOT_GROUNDED: Im Fundierungsüberprüfungsschritt wurde festgestellt, dass die generierte Antwort nicht durch die Quelldokumente belegt wird. Sie wurde daher verworfen.

Aktive Verhaltensweisen

Das search_knowledge_behavior-Objekt gibt an, welche spezifischen Verhaltensweisen während der GKA-Anfrage aktiv waren.

  • answer_generation_rewriter_on: Ein true-Wert gibt an, dass das System die Anfrage des Nutzers umgeschrieben hat, um die Suche in Datastore effektiver zu gestalten. Der Wert false gibt an, dass die Anfrage nicht umgeschrieben wurde.
  • end_user_metadata_included: Ein true-Wert gibt an, dass end_user_metadata im Aufruf an den Datenspeicher-Agenten übergeben wurde. Der Wert false gibt an, dass end_user_metadata nicht an den Datenspeicher-Agent übergeben wurde.

Informationen zur Fehlerbehebung aus dem aufgenommenen Kontext

Das Feld ingested_context_reference_debug_info enthält Informationen zur Fehlerbehebung im Zusammenhang mit Kontext, der zur Unterstützung der Suche aufgenommen wurde.

  • project_not_allowlisted: Ein true-Wert bedeutet, dass das Projekt nicht auf der Zulassungsliste für die Verwendung der Funktion zum Erfassen von Kontextreferenzen steht. Der Wert false bedeutet, dass das Projekt auf der Zulassungsliste steht.
  • context_reference_retrieved: Gibt an, ob der Kontextverweis erfolgreich aus der Datenbank abgerufen wurde.
  • ingested_parameters_debug_info: Eine Liste der Parameter, die aus der Kontextreferenz aufgenommen wurden, und ihr Status. Für jeden Parameter sehen Sie einen Parameternamen und einen der folgenden Aufnahmestatus.
    • INGESTION_STATUS_SUCCEEDED: Der Parameter wurde erfolgreich aufgenommen.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: Der Parameter war für die Aufnahme nicht verfügbar.
    • INGESTION_STATUS_PARSE_FAILED: Der Inhalt des Parameters konnte vom System nicht geparst werden.
    • INGESTION_STATUS_INVALID_ENTRY: Die Kontextreferenz hatte eine unerwartete Anzahl von Inhaltseinträgen (sie sollte nur einen haben).
    • INGESTION_STATUS_INVALID_FORMAT: Der Kontextinhalt hatte nicht das erwartete Format (z.B. JSON).
    • INGESTION_STATUS_LANGUAGE_MISMATCH: Die Sprache der Kontextreferenz stimmte nicht mit der Sprache des Gesprächs überein.

Latenz

{# disableFinding("data store")}

  • Das service_latency-Objekt unterteilt die in verschiedenen internen Diensten verbrachte Zeit und hilft Ihnen so, Leistungsengpässe zu ermitteln.

  • internal_service_latencies: Eine Liste mit Latenzdetails für jeden internen Schritt des Prozesses. Jeder Eintrag enthält einen Namen (step), die Dauer in Millisekunden (latency_ms) sowie die Start- (start_time) und Endzeit (complete_time). Mögliche Namen für einen internen Prozessschritt sind:

    • total_data_store_agent: Misst die Gesamtzeit, die für die Verarbeitung der gesamten GKA-Anfrage benötigt wird, vom Empfang der Anfrage bis zur Rückgabe einer endgültigen Antwort. Er dient als übergeordneter Zeitgeber für alle Suchschritte des Datenspeicher-Agents.
    • query_rewrite: Die Zeit, die für das Umschreiben der ursprünglichen Anfrage des Nutzers aufgewendet wurde, um die Suche in Ihren Wissensdokumenten effektiver zu gestalten.
    • search_query: Die Zeit, die der Datenspeicher-Agent benötigt hat, um die Suche anhand der konfigurierten Datenspeicher mit der (möglicherweise umgeschriebenen) Anfrage auszuführen.
    • summarization: Die Zeit, die für die Generierung einer prägnanten Antwort in natürlicher Sprache aus den Suchergebnissen benötigt wurde, die aus Datastore abgerufen wurden (ReAct-Schritt).
    • grounding: Die Zeit, die für die Überprüfung der Fundierung aufgewendet wurde. In diesem wichtigen Schritt wird geprüft, ob die generierte Antwort faktisch durch die Quelldokumente belegt wird, bevor sie zurückgegeben wird.
    • query_generation: Die Zeit, die für die Analyse der laufenden Unterhaltung und die proaktive Generierung einer relevanten Suchanfrage aufgewendet wurde.
    • generated_query_rai: Die Zeit, die benötigt wird, um eine Sicherheitsprüfung für die verantwortungsbewusste Anwendung von KI (Responsible AI, RAI) für die proaktiv generierte Anfrage durchzuführen, bevor sie für eine Suche verwendet wird.
    • query_categorization: Die Zeit, die für die Kategorisierung der generierten Anfrage mit Vertex AI Search aufgewendet wurde, sofern diese Funktion konfiguriert ist.

Beispiel für eine Antwort mit Informationen zur Fehlerbehebung

Das folgende Beispiel zeigt, wie das search_knowledge_debug_info-Objekt in einer JSON-Antwort aussehen könnte. 

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

Proaktive generative Wissensunterstützung (PGKA)

Die Fehlerbehebung bietet detaillierte Einblicke in die Prozesse zur Generierung von Anfragen, zur Kategorisierung und zum Abrufen von Antworten. Das knowledge_assist_debug_info-Objekt ist Teil von knowledge_assist_answer in den Ergebnissen Ihres Vorschlags.

Wenn Sie ein Unterhaltungsprofil erstellen oder aktualisieren, legen Sie das Feld enable_response_debug_info für die Funktion KNOWLEDGE_ASSIST auf true fest.

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

Details zur Fehlerbehebung

Das Objekt knowledge_assist_debug_info enthält die folgenden Felder, mit denen Sie den End-to-End-Lebenszyklus eines proaktiven Vorschlags nachvollziehen können.

Abfrage konnte nicht generiert werden

Im Feld query_generation_failure_reason wird erläutert, warum für eine Unterhaltung möglicherweise keine proaktive Suchanfrage generiert wurde.

  • QUERY_GENERATION_FAILED: Beim Generieren der Abfrage ist ein interner Fehler aufgetreten.
  • QUERY_GENERATION_NO_QUERY_GENERATED: Der Generator hat sich entschieden, keine Abfrage zu generieren. Das passiert in der Regel, wenn sich das Konversationsthema nicht geändert hat oder vor Kurzem eine ähnliche Anfrage vorgeschlagen wurde.
  • QUERY_GENERATION_RAI_FAILED: RAI-Filter (Verantwortungsbewusste Anwendung von KI) haben eine potenzielle Anfrage aus Sicherheitsgründen blockiert.
  • NOT_IN_ALLOWLIST: Die Abfragegenerierung wurde durch Filterregeln auf Unterhaltungsprofil- oder Agentenebene blockiert.
  • QUERY_GENERATION_QUERY_REDACTED: Der Generator hat die generierte Anfrage blockiert, da sie vertrauliche Informationen enthielt, die entfernt wurden.
  • QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: Die Abfragegenerierung ist fehlgeschlagen, weil die Sprache des Kundenservicemitarbeiters nicht mit der Sprache des Kunden übereinstimmt.
  • QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: Die Abfrage konnte nicht generiert werden, weil die Sprache der übersetzten Nachricht nicht mit der Sprache des Konversationsprofils übereinstimmt.
  • QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: Der Generator hat eine übersetzte Nachricht für die Abfragegenerierung erwartet, aber keine gefunden.

Abfrage konnte nicht kategorisiert werden

Im Feld query_categorization_failure_reason wird erläutert, warum die Kategorisierung der Anfrage möglicherweise fehlgeschlagen ist.

  • QUERY_CATEGORIZATION_INVALID_CONFIG: Die für die Kategorisierung bereitgestellte Vertex AI Search-Konfiguration ist ungültig, z. B. ist die Suchmaschine leer.
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: Das Ergebnis von Vertex AI Search enthielt kein Kategorisierungsergebnis.
  • QUERY_CATEGORIZATION_FAILED: Der Aufruf von Vertex AI Search zur Kategorisierung ist fehlgeschlagen.

Datastore-Suchstatus

Das Feld datastore_response_reason enthält den Status der Suche in Ihrem Datastore, nachdem eine Anfrage generiert wurde.

  • NONE: Datastore hat die Anfrage ohne besondere Probleme verarbeitet.
  • SEARCH_OUT_OF_QUOTA: Agent Assist hat den Suchvorgang blockiert, da das Nutzungskontingent überschritten wurde.
  • SEARCH_EMPTY_RESULTS: Bei der Suche wurden keine Dokumente aus Ihrem Datastore zurückgegeben.
  • ANSWER_GENERATION_GEN_AI_DISABLED: Generative KI-Funktionen sind für Ihr Projekt deaktiviert.
  • ANSWER_GENERATION_OUT_OF_QUOTA: Agent Assist hat die Antwortgenerierung blockiert, da das Nutzungskontingent überschritten wurde.
  • ANSWER_GENERATION_ERROR: Beim Generieren der Antwort ist ein interner Fehler aufgetreten.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: Die abgerufenen Dokumente enthielten nicht genügend Informationen, um eine Antwort zu generieren.
  • ANSWER_GENERATION_RAI_FAILED: Die generierte Antwort wurde von RAI-Filtern blockiert.
  • ANSWER_GENERATION_NOT_GROUNDED: Beim Fundierungsabgleich wurde festgestellt, dass die Quelldokumente die generierte Antwort nicht faktisch unterstützen. Die Antwort wurde daher verworfen.

Aktive Konfigurationen

Das knowledge_assist_behavior-Objekt gibt an, welche spezifischen Konfigurationen für die Anfrage aktiv waren.

  • answer_generation_rewriter_on: true, wenn die Anfrage vom Generator für bessere Suchergebnisse umformuliert wurde, und false, wenn nicht.
  • end_user_metadata_included: true, wenn der Generator end_user_metadata an Datastore übergeben hat, und false, wenn nicht.
  • return_query_only: true, wenn in Ihrem Profil nur die generierte Suchanfrage zurückgegeben wird, und false, wenn in Ihrem Profil die vollständige Antwort zurückgegeben wird.
  • use_pubsub_delivery: true, wenn Ihr Generator so konfiguriert ist, dass Ergebnisse mit Pub/Sub bereitgestellt werden, und false, wenn dies nicht der Fall ist.
  • disable_sync_delivery: true, wenn die synchrone Zustellung der Antwort deaktiviert ist, und false, wenn die synchrone Zustellung der Antwort aktiviert ist.
  • previous_queries_included: true, wenn der Generator zuvor vorgeschlagene Anfragen während der Anfragegenerierung berücksichtigt hat, und false, wenn nicht.
  • use_translated_message: true, wenn eine übersetzte Nachricht für die Abfragegenerierung verwendet wurde, und false, wenn nicht.
  • use_custom_safety_filter_level: true, wenn eine benutzerdefinierte Sicherheitsfilterstufe angewendet wurde. false, wenn für den Generator nur die Standardstufen des Sicherheitsfilters verwendet wurden.

Informationen aus aufgenommenem Kontext

Das Feld ingested_context_reference_debug_info enthält Debugging-Informationen zum Kontext, der zur Unterstützung der Suche aufgenommen wurde.

  • project_not_allowlisted: Ein true-Wert bedeutet, dass das Projekt nicht auf der Zulassungsliste für die Verwendung der Funktion zum Erfassen von Kontextreferenzen steht. Der Wert false bedeutet, dass das Projekt auf der Zulassungsliste steht.
  • context_reference_retrieved: Gibt an, ob der Kontextverweis erfolgreich aus der Datenbank abgerufen wurde.
  • ingested_parameters_debug_info: Eine Liste der Parameter, die aus der Kontextreferenz aufgenommen wurden, und ihr Status. Für jeden Parameter sehen Sie einen Parameternamen und einen der folgenden möglichen Aufnahmestatus.
    • INGESTION_STATUS_SUCCEEDED: Der Parameter wurde erfolgreich aufgenommen.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: Der Parameter war für die Aufnahme nicht verfügbar.
    • INGESTION_STATUS_PARSE_FAILED: Der Inhalt des Parameters konnte vom System nicht geparst werden.
    • INGESTION_STATUS_INVALID_ENTRY: Die Kontextreferenz hatte eine unerwartete Anzahl von Inhaltseinträgen (sie sollte nur einen haben).
    • INGESTION_STATUS_INVALID_FORMAT: Der Kontextinhalt hatte nicht das erwartete Format.
    • INGESTION_STATUS_LANGUAGE_MISMATCH: Die Sprache der Kontextreferenz stimmte nicht mit der Sprache des Gesprächs überein.

Beispiel für eine Antwort zur Fehlerbehebung

Im Folgenden finden Sie ein umfassendes Beispiel dafür, wie das knowledge_assist_debug_info-Objekt in einer Antwort aussehen kann. 

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