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.
  • Looker Studio (für CSV-Dateien und Google-Tabellen): In Looker 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.

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.

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 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 Looker Studio Pro verwenden möchten, muss sich Ihr Pro-Abo außerhalb eines VPC-SC-Perimeters befinden.

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.
  • Sie können beim Erstellen eines KI-Datenagenten Systemanweisungen angeben. Das sind benutzerdefinierte Anleitungen, die das Verhalten eines KI-Datenagenten steuern. Diese Anleitungen enthalten die geschäftsspezifische Logik, Antwortformatierungen oder Datendarstellungen. Sie können auch „Golden Queries“ verwenden. Das sind Beispielanfragen in natürlicher Sprache, die mit den entsprechenden korrekten SQL- bzw. Looker-Abfragen verknüpft werden. Weitere Informationen zu Systemanweisungen finden Sie auf der Dokumentationsseite KI-Agentenverhalten mit 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.

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
  • Looker Studio

Außerdem können Sie über BigQuery eine Verbindung zu Quellen wie SAP und Salesforce und über Looker 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) oder Service Control-Perimeter (VPC-SC) 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.