Logging von Unterhaltungen – Übersicht

Mit dem Logging von Unterhaltungen können Sie die Unterhaltungen eines konversationelle Analyse API-Daten-Agenten in einer BigQuery-Tabelle in Ihrem Projekt aufzeichnen. So können Sie die Qualität der Antworten überprüfen, die Akzeptanz verfolgen und die Kosten im Blick behalten. Für jede Runde werden im Protokoll die Frage des Nutzers, die Antwort des KI-Agenten, die Latenz, die Nutzung von Modell-Tokens und die Kennungen erfasst, die Sie benötigen, um die Runden nach KI-Agent, Unterhaltung und Nutzer zu gruppieren. Zeilen werden mit dem Schema BigQuery Agent Analytics über die BigQuery Storage Write API (gRPC) geschrieben. Sie können das Logging für einen KI-Datenagenten aktivieren, dessen Datenquellen auf BigQuery-Tabellen verweisen, indem Sie die Felder bigqueryAgentAnalyticsEnabled und bigqueryAgentAnalyticsTable festlegen. Eine Anleitung finden Sie unter Unterhaltungsprotokollierung aktivieren.

Was wird protokolliert?

Für jede protokollierte Runde werden mehrere Ereigniszeilen (events) in die Zieltabelle geschrieben, die die folgenden Informationen enthalten:

  • Die Frage des Nutzers.

  • Die Antwort des KI-Agenten: Text, Statistiken, Annahmen, vorgeschlagene Folgefragen, Zitationsquellen und die Namen aller Datenergebnisse oder Diagramme.

  • Latenz pro Runde.

  • Modelltokennutzung, Modellversion und der Grund für das Beenden (warum das Modell keine Tokens mehr generiert hat) für jeden Modellaufruf.

  • Die Daten-Agent-ID und die Konversations-ID (für Chat mit einer Konversationsreferenz), damit Sie mehrere Agenten in einer Tabelle analysieren können.

  • Eine Nutzer-ID. Weitere Informationen zu Nutzer-IDs finden Sie unter Nutzeridentität.

  • Status- und Fehlerdetails.

Was wird nicht protokolliert?

Folgendes wird beim Logging von Unterhaltungen nicht aufgezeichnet:

  • Die SQL-Abfragen, die der Agent ausführt: Das Protokoll enthält die endgültige Antwort und die Namen der referenzierten Datenergebnisse und Diagramme, aber nicht die Abfragen, die sie erzeugt haben. Eine Ausnahme ist, wenn ein Nutzer den Agenten explizit auffordert, SQL anzuzeigen oder zu erklären. In diesem Fall kann das SQL im Antworttext erscheinen.

  • Die Toolaufrufe des KI-Agenten: Bei jedem Modellaufruf wird eine LLM_RESPONSE-Zeile geschrieben, einschließlich Aufrufen, bei denen das Modell ein Tool ausführt. Bevor die Zeile geschrieben wird, wird die Ausgabe des Modells entfernt, einschließlich des Namens und der Argumente aller aufgerufenen Tools. Nur die Tokennutzung, die Modellversion und der Grund für die Beendigung werden beibehalten.

  • Nutzerfeedback: Feedback mit „Mag ich“ oder „Mag ich nicht“ wird nicht protokolliert.

Einige Unterhaltungen werden überhaupt nicht protokolliert, z. B. zustandslose API-Aufrufe ohne Daten-Agent. Weitere Informationen zu nicht unterstützten Konversationsflächen finden Sie unter Einschränkungen.

So funktioniert das Logging von Unterhaltungen

Wenn ein Nutzer mit einem KI-Datenagenten chattet, für den das Logging von Unterhaltungen aktiviert ist, verarbeitet die konversationelle Analyse jede Runde in den folgenden Phasen:

  1. Konfigurieren: Ein Agenten-Inhaber aktiviert das Unterhaltungs-Logging und gibt mit der konversationellen Analyse API ein vorhandenes Ziel-Dataset und einen Tabellennamen im Projekt des Agenten an.

  2. Fragen: Ein Nutzer sendet eine Frage an den KI-Agenten. Wenn Sie die konversationelle Analyse API über Ihre eigene Anwendung aufrufen, sind Sie dafür verantwortlich, Ihre Nutzer zu informieren. Nutzer, die mit dem KI-Agenten in BigQuery Studio chatten, sehen einen Hinweis, dass ihre Unterhaltungen protokolliert werden.

  3. Datenschutzprüfung: Bevor der KI-Agent mit der Bearbeitung der Anfrage beginnt, werden im Rahmen einer Datenschutzprüfung die Metadaten der Wissensquellentabellen des KI-Agenten (seine BigQuery-Datenquellen) mit den Anmeldedaten des Nutzers gelesen, der den Chat gestartet hat. Bei dieser Prüfung wird bestätigt, dass keine der Tabellen Sicherheit auf Zeilenebene (Zeilenzugriffsrichtlinien), Sicherheit auf Spaltenebene (Richtlinien-Tags) oder dynamische Datenmaskierung verwendet. Wenn bei der Prüfung eine Richtlinie gefunden wird oder nicht bestätigt werden kann, dass keine Richtlinien vorhanden sind, wird die Runde nicht protokolliert und der KI-Agent beantwortet die Frage des Nutzers trotzdem.

  4. Antworten: Der KI-Agent antwortet dem Nutzer wie gewohnt.

  5. Schreiben: Der Dienst-Agent der konversationellen Analyse API des Projekts (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com) schreibt die Logzeilen über die Storage Write API (gRPC) in die Zieltabelle. Beim ersten protokollierten Turn erstellt der Dienst-Agent die Tabelle, falls sie noch nicht vorhanden ist.

  6. Abfrage: Zeilen werden in der Regel innerhalb weniger Sekunden nach Abschluss der Antwort angezeigt. Die Lieferdauer wird nicht garantiert.

Logging-Fehler führen nie zu einem Fehler bei einer Runde. Die Datenschutzprüfung und das Schreiben von Logs können jedoch zu Latenz führen. Eine fehlende Berechtigung für das Log-Dataset, ein nicht vorhandenes Dataset oder ein ausgeschöpftes Kontingent führen nicht dazu, dass die Chatanfrage oder der API-Aufruf fehlschlägt. Die konversationelle Analyse meldet keine Logging-Fehler in der Chat-Oberfläche, in der API-Antwort oder in Cloud Logging.

Datenschutz, Data Governance und Sicherheit

Wenn Sie das Logging von Unterhaltungen für einen Agenten aktivieren, sollten Sie sich ansehen, wie sich Hinweise für Endnutzer, Datenzugriff, Verschlüsselung, Netzwerksteuerung und Audit-Logging auf Ihre Logs auswirken.

Hinweise für Endnutzer und protokollierte Inhalte

Die folgenden Hinweise und Regeln legen fest, was bei der Unterhaltungsaufzeichnung aufgezeichnet wird und wer die aufgezeichneten Daten einsehen kann:

  • Hinweis für Endnutzer in BigQuery Studio: Wenn das Logging von Unterhaltungen für einen KI-Agenten aktiviert ist, sehen Nutzer, die mit dem KI-Agenten in BigQuery Studio chatten, den folgenden Hinweis, wenn das Logging von Unterhaltungen aktiviert ist, einschließlich auf dem Bildschirm für neue Unterhaltungen, bevor der Nutzer einen ersten Prompt sendet:

    Alle Prompts und Antworten werden in BigQuery protokolliert und sind für Nutzer mit Dataset-Berechtigungen zugänglich.

  • Ihre Verantwortlichkeiten bei der Verwendung der API: Wenn Sie das Logging von Unterhaltungen (Trace-Logging) für einen KI-Datenagenten aktivieren und diesen Agenten Endnutzern über Ihre eigene Anwendung oder Integration zur Verfügung stellen, kann Google diesen Nutzern keinen Hinweis anzeigen. Sie sind für alle Mitteilungen, Offenlegungen oder Einwilligungen verantwortlich, die gemäß anwendbarem Recht und Ihren Vereinbarungen mit Ihren Endnutzern für die protokollierten Unterhaltungen gelten. Weitere Informationen finden Sie unter Sicherheit, Datenschutz, Risiko und Compliance für die konversationelle Analyse API.

  • Inhalt des Logs und wer es sehen kann: In der Zieltabelle werden Frage-und-Antwort-Inhalte gemäß den folgenden Datenschutzregeln gespeichert:

    • Vollständige Fragen und Antworten: Antworten können Werte enthalten, die von Ihren Wissensquellen zurückgegeben werden. Jeder, der die Protokolltabelle lesen kann, kann Daten sehen, die der Agent an einen Nutzer zurückgegeben hat, einschließlich Daten, die er in den Quelltabellen nicht lesen kann. Gewähren Sie nur Personen, die diese Inhalte sehen sollen, Lesezugriff auf das Log-Dataset.

    • Nutzer-IDs und Schreibspeicherort: Die Spalte user_id identifiziert den Aufrufer, der die Frage gestellt hat (siehe Nutzeridentität). Zeilen werden nur in das Ziel geschrieben, das Sie im Projekt des KI-Agenten konfigurieren.

    • Tabellen mit Sicherheit auf Zeilenebene, Sicherheit auf Spaltenebene oder Datenmaskierung: Wenn die Wissensquellen eines Agenten Sicherheit auf Zeilenebene (Zeilenzugriffsrichtlinien), Sicherheit auf Spaltenebene (Richtlinien-Tags) oder dynamische Datenmaskierung verwenden, werden seine Runden nicht protokolliert. Bei der Datenschutzprüfung werden Tabellen in bigquery-public-data übersprungen und nur die Tabellen und Ansichten berücksichtigt, die Sie als Wissensquellen auswählen, nicht die Tabellen hinter einer Ansicht:

      • Eine Ansicht einer Tabelle, die diese Richtlinien verwendet, kann die Prüfung bestehen, sodass ihre Turns protokolliert werden können. Bevor Sie das Logging aktivieren, müssen Sie sicherstellen, dass die Tabellen hinter Ansichten keine Zeilenzugriffsrichtlinien, Richtlinien-Tags oder Datenmaskierung verwenden.

      • Wenn Sie eine dieser Richtlinien später einer Quelltabelle hinzufügen, bleiben bereits protokollierte Zeilen in der Protokolltabelle. Wenn Ihre Aufbewahrungs- oder Governance-Richtlinie das Beibehalten dieser Zeilen verbietet, löschen Sie sie.

Zugriffssteuerung, Verschlüsselung und Netzwerksicherheit

Mit den folgenden Einstellungen können Sie die Aufbewahrung, den Zugriff, die Verschlüsselung und die Perimetersicherheit für Ihre Unterhaltungslogs verwalten:

  • Aufbewahrung und Zugriffssteuerung für das Log-Dataset: Konfigurieren Sie die Aufbewahrung, Dataset-Rollen, Tabellenrichtlinien und Audit-Logs für Ihre Zieltabelle:

    • Aufbewahrung: Google löscht keine Logzeilen. Legen Sie für das Log-Dataset oder die Log-Tabelle einen Partitionsablauf fest, der Ihrer Richtlinie entspricht (z. B. 90 Tage).

    • Geringste Berechtigung: Halten Sie das Log-Dataset von Ihren anderen Datasets getrennt, damit der Schreibzugriff des freigegebenen Dienst-Agents der konversationellen Analyse API nicht auf Ihre anderen Tabellen zugreifen kann. Gewähren Sie Analysten roles/bigquery.dataViewer für das Log-Dataset oder gewähren Sie ihnen nur Zugriff auf autorisierte Ansichten oder autorisierte Datasets.

    • Steuerelemente auf Spalten- und Zeilenebene für die Protokolltabelle: Sie können Richtlinien-Tags, Datenmaskierung oder Zeilenzugriffsrichtlinien auf die Protokolltabelle selbst anwenden, z. B. auf content oder user_id. Diese Einstellungen für Protokolltabellen haben keine Auswirkungen auf die Datenschutzprüfung für Wissensquellen.

    • Audit-Logging: Änderungen an der Konfiguration des Daten-Agents und Vorgänge in der Protokolltabelle werden in Audit-Logs aufgezeichnet. Weitere Informationen finden Sie unter Geprüfte Vorgänge.

  • CMEK, VPC Service Controls und Datenstandort: Die folgenden Verschlüsselungs-, Perimeter- und Standortkontrollen gelten für das Gesprächs-Logging:

    • CMEK: Wenn das Log-Dataset vom Kunden verwaltete Cloud KMS-Schlüssel (CMEK) verwendet, weisen Sie dem BigQuery-Verschlüsselungsdienstkonto (bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com) die Rolle roles/cloudkms.cryptoKeyEncrypterDecrypter für den Schlüssel zu. Ein CMEK für einen KI-Datenagenten verschlüsselt die Agentenressource, nicht die Protokolltabelle (siehe Kundenverwaltete Verschlüsselungsschlüssel).

    • VPC Service Controls: Wenn Sie einen Dienstperimeter verwenden, fügen Sie sowohl geminidataanalytics.googleapis.com als auch bigquery.googleapis.com in den Perimeter ein, der das Projekt des Agents enthält. Der Dienst-Agent schreibt aus der von Google verwalteten Infrastruktur in die Logtabelle. Wenn der Perimeter also bigquery.googleapis.com einschränkt, fügen Sie eine Regel für eingehenden Traffic wie die folgende hinzu. Ersetzen Sie PROJECT_NUMBER durch die Projektnummer des Agenten:

      - ingressFrom:
          identities:
          - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com
          sources:
          - accessLevel: "*"
        ingressTo:
          operations:
          - serviceName: bigquery.googleapis.com
            methodSelectors:
            - permission: bigquery.tables.get
            - permission: bigquery.tables.create
            - permission: bigquery.tables.update
            - permission: bigquery.tables.updateData
          resources:
          - projects/PROJECT_NUMBER
      

      Weitere Informationen finden Sie unter Perimetersicherheit mit VPC Service Controls konfigurieren.

    • Datenstandort: Logzeilen und die automatisch erstellte Tabelle werden am Speicherort des Log-Datasets gespeichert, für das Organisationsrichtlinien für den Ressourcenstandort (gcp.resourceLocations) gelten.

Attribution von Kundenservicemitarbeitern und Anrufern

Der Dienst-Agent der konversationellen Analyse API, nicht der chattende Nutzer, erstellt und aktualisiert die Protokolltabelle und fügt ihr Zeilen hinzu. Für diese Vorgänge benötigt der Dienst-Agent die Rolle BigQuery-Datenbearbeiter (roles/bigquery.dataEditor) für das Log-Dataset.

In Audit-Logeinträgen, die von Cloud-Audit-Logs aufgezeichnet werden, wird im Feld authenticationInfo.principalEmail (oder authenticationInfo.principalSubject für föderierte Identitäten) das Hauptkonto angegeben, das den jeweiligen Vorgang ausgeführt hat:

  • Tabellenerstellung, Schemaaktualisierungen und Zeilenanhänge protokollieren: der Dienst-Agent service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com.

  • Anfragen zur Konfiguration von Daten-Agents (CreateDataAgent, CreateDataAgentSync, UpdateDataAgent und UpdateDataAgentSync): Der Nutzer, das Dienstkonto oder die föderierte Identität, die die API aufruft. Wenn delegierte Dienstkonto-Anmeldedaten gelten, enthalten diese Einträge auch authenticationInfo.serviceAccountDelegationInfo.

Geprüfte Vorgänge

In Cloud-Audit-Logs werden Konfigurationsänderungen für das Unterhaltungs-Logging und Logtabellenvorgänge für die folgenden Dienste aufgezeichnet:

  • API für konversationelle Analyse: Die folgenden Methoden generieren Audit-Logs unter geminidataanalytics.googleapis.com:

    • CreateDataAgent, CreateDataAgentSync, UpdateDataAgent und UpdateDataAgentSync generieren Audit-Logs für Administratoraktivitäten, in denen die Felder bigqueryAgentAnalyticsEnabled und bigqueryAgentAnalyticsTable eines Agents aufgezeichnet werden, einschließlich des Zielprojekts, des Datasets und der Tabelle.

    • SetAgentOpsObservability generiert Audit-Logs zur Administratoraktivität, in denen die Felder dataSourceType, telemetryEnabled, bqaaEnabled und updateMask der Anfrage aufgezeichnet werden.

    • RetrieveAgentOpsObservability generiert Audit-Logs zum Datenzugriff, wenn der entsprechende Audit-Logtyp ADMIN_READ oder DATA_READ für geminidataanalytics.googleapis.com aktiviert ist.

  • BigQuery: Die Vorgänge des Dienst-Agents für die Logtabelle und die Abfragen, die Sie für die Tabelle ausführen, generieren die folgenden Audit-Logs:

    • Beim Erstellen von Logtabellen und Aktualisieren von Schemas werden Audit-Logs zu Administratoraktivitäten unter bigquery.googleapis.com generiert.

    • Durch das Anhängen von Zeilen über die Storage Write API (gRPC) werden Audit-Logs für den Datenzugriff für die Methode google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows generiert, einschließlich TableDataChange-Metadaten (WRITE_API_APPEND_ROWS). Diese Einträge verwenden den Dienstnamen bigquery.googleapis.com, nicht bigquerystorage.googleapis.com. Nur Audit-Logs für abgelehnte Richtlinien verwenden bigquerystorage.googleapis.com.

    • Abfragen der Logtabelle generieren Audit-Logs zum Datenzugriff unter bigquery.googleapis.com, z. B. Einträge vom Typ JobInsertion, JobChange und TableDataRead.

Weitere Informationen finden Sie unter Audit-Logging für die konversationelle Analyse API und Übersicht zu BigQuery-Audit-Logs.

Beschränkungen

Für das Unterhaltungs-Logging gelten die folgenden Einschränkungen:

  • Der Bereich Vorschau im BigQuery Studio-Agent-Editor wird nicht protokolliert.

  • Zustandslose API-Aufrufe ohne KI-Datenagenten werden nicht protokolliert.

  • KI-Agenten, die einen Suchbereich anstelle bestimmter Tabellen verwenden oder keine BigQuery-Tabellen deklarieren, werden nicht protokolliert. Agenten, die nur BigQuery-Property-Graphen (ohne BigQuery-Tabellen) als Wissensquellen konfigurieren, werden nicht protokolliert.

  • Generierte SQL, Toolaufrufe und Tool- oder Anfrageereignisse des Agent Development Kit (ADK) (TOOL_STARTING, TOOL_COMPLETED, TOOL_ERROR und LLM_REQUEST) werden nicht protokolliert. Nur die Antwort und die Namen der Datenergebnisse und Diagramme werden protokolliert. Bei Turns, die direkt aus einer verifizierten Abfrage beantwortet werden, werden keine LLM_RESPONSE-Zeilen geschrieben. Fehlgeschlagene Turns mit verifizierten Abfragen werden nicht protokolliert.

  • Nutzerfeedback in Form von „Mag ich“ oder „Mag ich nicht“ wird nicht protokolliert.

  • Runden werden nicht protokolliert, wenn Wissensquellen Zugriffsrichtlinien auf Zeilenebene, Sicherheit auf Spaltenebene (Richtlinien-Tags) oder Datenmaskierung verwenden, einschließlich Datenrichtlinien, die direkt an Spalten angehängt sind. Runden werden auch dann nicht protokolliert, wenn die Datenschutzprüfung diese Richtlinien nicht verifizieren kann, z. B. wenn der chattende Nutzer keine Berechtigung zum Prüfen der Richtlinienmetadaten einer Tabelle hat oder die Prüfung ein Zeitlimit überschreitet. Bei der Prüfung werden die Ansichten der dahinter liegenden Tabellen nicht berücksichtigt.

  • Es werden nur BigQuery-Tabelle-Agents unterstützt. Looker-, Data Studio-, AlloyDB for PostgreSQL-, Spanner- und Cloud SQL-Datenquellen werden nicht unterstützt.

  • Das Ziel-Dataset muss bereits im selben Projekt wie der Agent vorhanden sein.

  • Schemaänderungen an vorhandenen Tabellen sind nur additiv. Ein in Konflikt stehender Spaltentyp oder -modus verhindert Schreibvorgänge in diese Tabelle.

  • Jede infrage kommende Runde wird ohne Stichprobeneinstellung protokolliert. Nehmen Sie stattdessen eine Stichprobe zum Zeitpunkt der Abfrage (siehe Beispielfragen und ‑antworten aller Agenten zur Überprüfung).

  • Die Spalte agent enthält den Agententyp und nicht den Anzeigenamen des Agenten. Verwenden Sie die Daten-Agent-ID in attributes.

  • API-Aufrufer, die ein Dienstkonto für viele Endnutzer verwenden, sehen die E-Mail-Adresse dieses Dienstkontos in jeder Zeile.

  • Textwerte,die länger als 512.000 Zeichen (500 * 1,024) sind, werden mit dem Suffix ...[TRUNCATED] abgeschnitten. Der entfernte Teil kann nicht wiederhergestellt werden.

  • Schreibvorgänge werden nach dem Best-Effort-Prinzip mit einer begrenzten Anzahl von Wiederholungsversuchen ausgeführt. Runden, die nicht geschrieben werden können, werden nicht protokolliert. Wiederholungsversuche können gelegentlich zu doppelten Zeilen führen (verwenden Sie event_id, um Duplikate zu entfernen).

  • Ein Agent übernimmt die Einstellung für die Beobachtbarkeit auf Projektebene nicht.

Preise

Für die Protokollierung von Unterhaltungen fallen keine separaten Gebühren an. Für Ihr Projekt fallen die BigQuery-Standardpreise für die Datenaufnahme über die BigQuery Storage Write API (gRPC), den Speicher und Analyseabfragen an. Die Aufnahme über die BigQuery Storage Write API (gRPC) umfasst 2 TiB kostenlose Nutzung pro Monat für jedes Rechnungskonto, die auf die Nutzung der Storage Write API (gRPC) aufgeteilt wird. Filtern Sie Abfragen nach timestamp, um die gescannten Byte zu reduzieren. Bei der Datenschutzprüfung vor der Ausführung werden Tabellenmetadaten gelesen und Probelaufabfragen kostenlos ausgeführt.

Nächste Schritte