Häufig gestellte Fragen zur Conversational Analytics API

Kann die Conversational Analytics API meine Daten ändern oder löschen?

Die Conversational Analytics API ist aus Sicherheitsgründen so konzipiert, dass Ihre Daten nicht geändert oder gelöscht werden können.

Datensicherheit für verschiedene Datenquellen:

  • BigQuery: Die API blockiert DDL- (Datendefinitionssprache) und DML-Anweisungen (Datenbearbeitungssprache). Das System führt eigens einen Testlauf mit generiertem SQL-Code aus und lässt nur Abfragen vom Typ SELECT zu.
  • Looker: Die API interagiert mit Looker über Methoden wie run_inline_query, die auf Lesevorgänge wie Auswahl, Filter und Limits beschränkt sind. Diese Methoden unterstützen keine DDL- oder DML-Vorgänge und umfassen auch keine Lösch- oder Drop-Vorgänge.
  • Data Studio (für CSV-Dateien und Google-Tabellen): In Data Studio wird ein strukturiertes Format verwendet, um Daten für Visualisierungen und Berichte zu definieren und abzurufen. Alle mit dieser Methode ausgeführten Abfragen sind schreibgeschützt und erlauben keine Datenänderungen.
  • Datenbanken: Das System lässt nur Abfragen vom Typ SELECT zu. Damit Daten nicht geändert oder gelöscht werden können, muss das Dienstkonto oder der Nutzer, das bzw. der mit der Conversational Analytics API interagiert, schreibgeschützte Berechtigungen für Ihre Datenbank haben.

Die Conversational Analytics API ist für diese Datenquellen schreibgeschützt. Weitere Informationen zur Sicherheit der Conversational Analytics API finden Sie im Blogpost Chat with confidence: Unpacking security in Looker Conversational Analytics.

Wie gehe ich mit Authentifizierungs- und Berechtigungsfehlern um?

Nachfolgend sind häufige Authentifizierungs- und Berechtigungsfehler aufgeführt, die bei der Verwendung der Conversational Analytics API auftreten können:

  1. Fehler: PERMISSION_DENIED oder 403 Write access to project ... was denied

    • Wahrscheinliche Ursache: Diese Meldung deutet häufig auf Probleme mit Google Cloud -IAM-Rollen hin. Dem Nutzer- oder Dienstkonto, das versucht, die API zu verwenden, fehlen die erforderlichen Berechtigungen für das Google Cloud -Projekt.
    • Problembehebung:
      • Der Google Cloud Project Owner muss dafür sorgen, dass dem Nutzer- oder Dienstkonto die richtigen IAM-Rollen im Google Cloud -Projekt zugewiesen sind. Für bestimmte Vorgänge, z. B. zum Aktivieren der API und Testen ihrer Funktionen, sind möglicherweise Rollen wie Project Editor erforderlich.
      • Wenn beim Wechsel zwischen Regionen ein 403-Fehler wie Write access to project 'us-gcp-project-name' was denied auftritt, überprüfen Sie die IAM-Konfiguration Ihres Projekts.

  2. Fehler: 500 Internal Server Error, wenn ein Looker-Nutzer mit der Rolle User versucht, mit einem KI-Datenagenten zu chatten.

Warum werden beim Streamen von Antworten 503- oder 500-Fehler angezeigt?

Wenn Sie einen einfachen HTTP- oder REST-Client (z. B. die Python-Bibliothek requests) verwenden, um den Streaming-Endpunkt :chat aufzurufen, gibt die API möglicherweise eine allgemeine Fehlermeldung wie 503 Connection reset by peer oder 500 Internal error zurück.

Diese allgemeinen Fehler treten auf, weil die Streaming API einen HTTP-Header 200 OK sendet, sobald der Stream geöffnet wird. Wenn beim Streamen ein schwerwiegender Fehler auftritt (z. B. ein Zeitlimit für eine lang andauernde Abfrage oder eine plötzliche Berechtigungsverweigerung), beendet der KI-Datenagent den Stream und fügt den spezifischen Fehlercode in die HTTP/2-Trailer ein. Standardmäßige HTTP- oder REST-Clients können diese nachfolgenden Header nicht parsen und interpretieren die abrupte Beendigung stattdessen als Socket-Absturz.

Um Fehler zu beheben, die während eines Streams auftreten, empfehlen wir dringend, die offiziellen Google Cloud Clientbibliotheken (SDKs) wie das Python SDK zu verwenden. Diese gRPC-basierten SDKs parsen HTTP/2-Trailer und geben den spezifischen Fehlercode wie DEADLINE_EXCEEDED oder PERMISSION_DENIED anstelle eines allgemeinen Netzwerkfehlers zurück.

Welche Looker-Anforderungen gelten für die Verwendung der Conversational Analytics API?

Wenn Sie die Conversational Analytics API verwenden möchten, benötigen Sie je nach Datenquelle und auszuführenden Aktionen die entsprechenden Berechtigungen in Google Cloud IAM und Looker:

  1. Google Cloud IAM-Rollen:

    • Sie benötigen ausreichende IAM-Rollen für Ihr Google Cloud -Projekt, um mit der geminidataanalytics.googleapis.com API interagieren zu können. Falsch konfigurierte IAM-Rollen führen häufig zu PERMISSION_DENIED-Fehlern.
    • Die notwendigen Rollen sind teilweise auch von den Aktionen abhängig. Für bestimmte Vorgänge sind jedoch möglicherweise allgemeine Rollen wie Project Editor erforderlich.

  2. Looker-Berechtigungen und -Rollen:

    • Berechtigungen auf Modellebene: Wenn ein Looker-Nutzer die konversationelle Analyse und die Conversational Analytics API verwenden möchte, muss ihm eine Looker-Rolle mit der Berechtigung gemini_in_looker für die Modelle zugewiesen werden, mit denen er interagiert.

Weitere Informationen zu den Berechtigungen und Rollen für die Verwendung der Conversational Analytics API finden Sie auf der Dokumentationsseite IAM-Rollen und -Berechtigungen für die Conversational Analytics API zuweisen.

Außerdem muss Ihre Looker-Instanz bestimmte Anforderungen erfüllen:

Wenn Sie die Conversational Analytics API mit Data Studio Pro verwenden möchten, muss sich Ihr Pro-Abo außerhalb eines VPC-SC-Perimeters befinden.

Welche Datenbankanforderungen gelten für die Verwendung der Conversational Analytics API?

Wenn Sie die Conversational Analytics API mit Datenbanken wie AlloyDB for PostgreSQL, GoogleSQL for Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL verwenden möchten, müssen Sie die IAM-Authentifizierung ordnungsgemäß aktivieren und konfigurieren:

  1. Google Cloud **IAM-Rollen**:

    • Das Dienstkonto oder der Nutzer muss die erforderlichen IAM-Rollen haben, um eine Verbindung zur jeweiligen Datenbank herzustellen und sie abzufragen. In der Regel sind dafür Rollen mit Lesezugriff auf die Datenbank erforderlich.

  2. API-Aktivierung:

    • Achten Sie darauf, dass die Cloud AI Companion API in Ihrem Google Cloud Projekt aktiviert ist.

Weitere Informationen zum Aktivieren der IAM-Authentifizierung finden Sie in der Dokumentation für die einzelnen Datenbanken:

Wie migriere ich von der Data QnA API zur Conversational Analytics API?

Wenn Sie die ältere, experimentelle Version der Data QnA API (dataqna.googleapis.com) verwendet haben, finden Sie in der Migrationsanleitung Informationen zur Migration auf den neuen, offiziellen Endpunkt der Conversational Analytics API (geminidataanalytics.googleapis.com).

Was ist der Unterschied zwischen dem Namen und der ID eines KI-Datenagenten?

Die ID des KI-Datenagenten, also der Wert, den Sie für data_agent_id eingeben, ist die eindeutige Kennung des KI-Datenagenten. Der Name des KI-Datenagenten, data_agent.name, wird automatisch aus der data_agent_id als voll qualifizierter Name (FQN) abgeleitet. Dieser verwendet das Format projects/<project>/locations/<location>/dataAgents/<data_agent_id>

Beim Erstellen eines KI-Datenagenten wird daher jeder Wert, den Sie für data_agent.name eingegeben haben, ignoriert. Bei get-, update- oder delete-Vorgängen wird der vollständige data_agent.name als eindeutige Kennung des KI-Datenagenten behandelt.

Bei Verwendung der Conversational Analytics API zum Erstellen von KI-Datenagenten gilt Folgendes:

  • Wenn Sie data_agent_id nicht festlegen, wird automatisch eine eindeutige ID erstellt.
  • Wenn Sie data_agent_id beispielsweise auf TestID festlegen, wird jeder Wert, den Sie für data_agent.name eingegeben haben, mit projects/<project>/locations/<location>/dataAgents/TestID überschrieben.
  • Wenn Sie data_agent_id mit einem FQN definieren, tritt der Fehler „malformed name“ auf.

Welches ID-Format wird für „Agent erstellen“ oder „Unterhaltung erstellen“ akzeptiert?

Für KI-Datenagenten:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} ist die Ressourcen-ID. Sie darf maximal 63 Zeichen lang sein und muss dem Format unter https://google.aip.dev/122#resource-id-segments entsprechen.

Beispiel: projects/1234567890/locations/us-central1/dataAgents/my-agent

Es wird empfohlen, dieses Feld bei der Erstellung des KI-Agenten nicht festzulegen, da es automatisch abgeleitet und mit {parent}/dataAgents/{data_agent_id} überschrieben wird.

Für Unterhaltungen:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} ist die Ressourcen-ID. Sie darf maximal 63 Zeichen lang sein und muss dem Format unter https://google.aip.dev/122#resource-id-segments entsprechen.

Beispiel: projects/1234567890/locations/us-central1/conversations/my-conversation.

Wir empfehlen, dieses Feld bei der Erstellung von Unterhaltungen nicht festzulegen, da es bei der konversationellen Analyse automatisch erkannt und dann mit {parent}/conversations/{conversation_id} überschrieben wird.

Wie verwende ich die Aktualisierungsmaske?

Im Ablauf zum Aktualisieren eines KI-Datenagenten verwendet der Parameter updateMask einen FieldMask-Formatstring, der angibt, welche dataAgent-Felder in der dataAgent-Ressource aktualisiert werden sollen. Der Parameter updateMask ist ein Pflichtfeld und wird folgendermaßen validiert:

  • Wenn updateMask leer ist, wird eine BadRequestException ausgegeben und es werden keine Felder aktualisiert.
  • Wenn alle Felder im Parameter updateMask gültige dataAgent-Felder sind, werden nur diese Felder aktualisiert.
  • Wenn sowohl gültige als auch ungültige Felder vorhanden sind, werden die ungültigen Felder ignoriert und nur die gültigen aktualisiert.

Wie verwende ich getIAMPolicy und setIAMPolicy, um die IAM-Richtlinie für einen KI-Datenagenten festzulegen?

Mit den Methoden getIamPolicy und setIamPolicy können Sie Nutzern IAM-Rollen für einen bestimmten KI-Agenten zuweisen.

Die folgenden Codebeispiele zeigen, wie Sie die IAM-Richtlinie für einen KI-Datenagenten abrufen:

Die folgenden Codebeispiele zeigen, wie Sie einem KI-Datenagenten IAM zuweisen:

Welche Erinnerungsfähigkeiten hat der KI-Datenagent der Conversational Analytics API?

  • In einer einzelnen Sitzung: Die Conversational Analytics API unterstützt Multi-Turn-Unterhaltungen. Das bedeutet, dass sie in der Lage ist, sich auf frühere Teile der aktuellen Unterhaltung zu beziehen.
  • Über mehrere Sitzungen hinweg: Die Conversational Analytics API bietet Funktionen für den verwalteten Unterhaltungsverlauf, sodass Nutzer über mehrere Sitzungen hinweg chatten können. Außerdem werden zustandsorientierte KI-Agenten mit von Google verwalteten Multi-Turn-Unterhaltungen unterstützt.
  • Langfristig gemerkte Informationen: KI-Datenagenten der Conversational Analytics API unterstützen keine expliziten Langzeiterinnerungsfunktionen.

Erhalte ich von einem KI-Datenagenten der Conversational Analytics API immer dieselbe Antwort auf dieselbe Frage?

  • Antworten in natürlicher Sprache vom KI-Datenagenten sind nicht deterministisch. Die vom KI-Agenten gegebene Antwort in natürlicher Sprache kann also auch bei einer identisch formulierten Frage variieren.
  • Antworten auf Datenanfragen: Bei einer Frage, die auf bestimmte Daten abzielt, sollte die zugrunde liegende generierte Abfrage (SQL- oder Looker-Abfrage) deterministisch sein. Die abgerufenen Daten sollten daher identisch sein, sofern sich die zugrunde liegenden Daten nicht geändert haben.

Wie kann ich die Antwort-Accuracy eines KI-Datenagenten der Conversational Analytics API verbessern?

Eine Möglichkeit, die Antwort-Accuracy von KI-Datenagenten zu verbessern, besteht darin, dem KI-Datenagenten aussagekräftige Kontextinformationen zur Verfügung zu stellen. So fügen Sie Kontext hinzu:

  • Sie können auf der semantischen Ebene von Looker Kontext in den LookML-Definitionen angeben. Weitere Informationen und Beispiele finden Sie auf der Dokumentationsseite KI-Agentenverhalten mit erstelltem Kontext steuern.
  • In AlloyDB for PostgreSQL-, Cloud SQL for MySQL-, Cloud SQL for PostgreSQL- und Spanner-Datenquellen können Sie Kontext bereitstellen, indem Sie Tabellen-, Spalten- und Schemabeschreibungen sowie Einschränkungen als Anleitung für die Daten und deren Interpretation hinzufügen.

  • Wenn Sie einen KI-Datenagenten erstellen, können Sie Systemanweisungen, geprüfte Abfragen und erweiterten Kontext angeben:

    • Systemanweisungen sind benutzerdefinierte Anleitungen, die das Verhalten eines KI-Datenagenten steuern. Diese Anleitungen enthalten die geschäftsspezifische Logik, Antwortformatierungen oder Datendarstellungen.
    • Sie können geprüfte Abfragen (je nach Datenquelle auch als Golden Queries bezeichnet) bereitstellen. Das sind Beispielanfragen in natürlicher Sprache, die mit den entsprechenden korrekten SQL- bzw. Looker-Abfragen verknüpft werden.
    • Für AlloyDB-, Cloud SQL for MySQL-, Cloud SQL for PostgreSQL- und Spanner-Datenquellen können Sie erweiterten Kontext bereitstellen, um das Datenverständnis und die Genauigkeit Ihrer KI-Agenten zu optimieren.

    Weitere Informationen finden Sie unter Agent-Verhalten mit selbst erstelltem Kontext steuern.

Auf der Seite Effektive Fragen stellen finden Sie Tipps dazu, wie Sie Fragen so formulieren, dass Sie zielführendere und genauere Antworten erhalten.

Wie kann ich von KI-Agenten generierten Python-Code sicher prüfen und verarbeiten?

Wenn Sie die erweiterte Analyse mit Python aktiviert haben, gibt Ihr KI-Datenagent möglicherweise Python-Code zurück. Der von KI-Datenagenten zurückgegebene Python-Code ist für die Ausführung in einer sicheren, von Google verwalteten Sandbox konzipiert. Wenn Sie diesen Code in einer lokalen oder anderen nicht verifizierten Umgebung ausführen, werden die Sicherheitsvorkehrungen der Sandbox umgangen und Ihr System kann Sicherheitsrisiken ausgesetzt sein, z. B. der Ausführung von schädlichem Code.

So prüfen und verarbeiten Sie von KI-Agenten generierten Python-Code sicher:

  • Prüfen Sie den generierten Code manuell, bevor Sie ihn ausführen. Achten Sie auf verdächtige Muster wie unerwartete Netzwerkanfragen (z. B. socket, requests oder urllib), Befehle auf Systemebene (z. B. os.system oder subprocess) oder stark verschleierte Stringliterale und Variablen.
  • Führen Sie nicht verifizierten Code niemals direkt auf einem lokalen Computer oder in einer Produktionsumgebung aus. Verwenden Sie eine sichere, isolierte Sandbox wie ein Colaboratory-Notebook, einen kurzlebigen Docker-Container oder eine virtuelle Maschine, die keinen Zugriff auf vertrauliche Anmeldedaten, interne Netzwerke oder lokale Dateisysteme hat.
  • Wenn möglich, sollten Sie vor dem Ausführen des Codes statische Analysetools oder Linter auf den Code anwenden, um potenziell unsichere Vorgänge oder bekannte schädliche Muster zu kennzeichnen.

Kann ich die Conversational Analytics API in Drittanbieteranwendungen einbinden?

Die Conversational Analytics API kann in Drittanbieteranwendungen eingebunden werden, damit Nutzer direkt in ihren täglich verwendeten Tools mit ihren Daten interagieren können.

Jede Drittanbieteranwendung, die mit den Endpunkten der geminidataanalytics.googleapis.com API interagiert, muss in der Lage sein, Nutzernachrichten von der Anwendung an den KI-Agenten zu senden und die Antworten anzuzeigen.

Beispiele oder Bibliotheken für die Entwicklung einer Einbindung finden Sie im Kurzanleitungs-Repository für die konversationelle Analyse. Sie können auch in den Google Developer-Foren nach Beispielen von anderen Nutzern suchen.

Wie viel kostet die Conversational Analytics API?

Die Conversational Analytics API befindet sich in der Vorschauphase. Für Produkte in der Vorschauphase fallen keine Kosten an. Wir werden Sie rechtzeitig über zukünftige Preisänderungen informieren.

Welche Datenquellen werden von der Conversational Analytics API unterstützt?

Die Conversational Analytics API unterstützt folgende Datenquellen:

  • BigQuery
  • Looker-Explores
  • Data Studio
  • AlloyDB for PostgreSQL
  • GoogleSQL for Spanner
  • Cloud SQL und Cloud SQL for PostgreSQL

Außerdem können Sie über BigQuery eine Verbindung zu Quellen wie SAP und Salesforce und über Data Studio eine Verbindung zu CSV-Dateien und Google-Tabellen herstellen.

Welchen Einschränkungen unterliegt die Conversational Analytics API?

Weitere Informationen zu den bekannten Einschränkungen der Conversational Analytics API finden Sie auf der Dokumentationsseite Bekannte Einschränkungen der Conversational Analytics API.

Welche Kontingente muss ich für Google Cloud -Projekte beachten?

Es gibt keine Einschränkungen bei der Auswahl von Google Cloud -Projekten oder Standorten. Sie können KI-Datenagenten erstellen, um unterstützte Datenquellen in einem beliebigen Projekt oder einer beliebigen Region abzufragen.

Unterstützt die Conversational Analytics API die Regionalisierung von Daten?

Da die Conversational Analytics API noch keine Unterstützung für Datenstandorte (Data Residency Zone, DRZ) bietet, können Sie KI-Agenten noch nicht in bestimmten geografischen Regionen hosten. Die Regionalisierung von Daten wird nicht unterstützt.

Unterstützt die Conversational Analytics API andere Sprachen als Englisch?

Die einzige offiziell unterstützte Sprache für die Conversational Analytics API ist Englisch. Die zugrunde liegenden Gemini-Modelle unterstützen zwar mehrere Sprachen und einige Nutzer berichten von Erfolgen mit nicht englischsprachigen Anfragen, jedoch unterstützt die Conversational Analytics API offiziell nur Englisch.