Häufig gestellte Fragen zur Conversational Analytics API

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

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

So wird die Datensicherheit für verschiedene Datenquellen gehandhabt:

  • BigQuery: Die API blockiert Anweisungen der Datendefinitionssprache (Data Definition Language, DDL) und der Datenbearbeitungssprache (Data Manipulation Language, DML). Das System führt einen Testlauf für generierten 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 Leseoperationen wie Auswahl, Filter und Limits beschränkt sind. Diese Methoden unterstützen keine DDL- oder DML-Vorgänge und umfassen 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 Abfragen, die mit dieser Methode ausgeführt werden, sind schreibgeschützt und unterstützen 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?

Im Folgenden finden Sie einige häufige Authentifizierungs- und Berechtigungsfehler, 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.
    • Fehlerbehebung:
      • Der Google Cloud Projektinhaber muss dafür sorgen, dass dem Nutzer oder Dienstkonto die richtigen IAM-Rollen im Google Cloud Projekt zugewiesen sind. Für bestimmte Vorgänge wie das Aktivieren der API oder das Testen ihrer Funktionen sind möglicherweise Rollen wie Project Editor erforderlich.
      • Wenn beim Wechseln von Regionen ein 403-Fehler wie Write access to project 'us-gcp-project-name' was denied auftritt, prüfen Sie die IAM-Konfiguration Ihres Projekts.

  2. Fehler: 500 Internal Server Error, wenn ein Looker-Nutzer mit der Rolle Nutzer versucht, mit einem Daten-Agent 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 den Aktionen, die Sie ausführen möchten, entsprechende Berechtigungen in Google Cloud IAM und in 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 erforderlichen Rollen können von den Aktionen abhängen. Für bestimmte Vorgänge sind jedoch möglicherweise allgemeine Rollen wie Projektbearbeiter 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 zugewiesen sein, die die Berechtigung gemini_in_looker für die Modelle enthält, mit denen er interagiert.

Weitere Informationen zu den Berechtigungen und Rollen, die für die Verwendung der Conversational Analytics API erforderlich sind, 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 Ihr Pro-Abo außerhalb eines VPC-SC-Perimeters liegen.

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 zum neuen, offiziellen Endpunkt für die Conversational Analytics API (geminidataanalytics.googleapis.com).

Was ist der Unterschied zwischen dem Namen und der ID eines Daten-Agents?

Die ID des KI-Datenagenten, die als Wert für data_agent_id definiert ist, ist die eindeutige Kennung für den KI-Datenagenten. Der Name des Daten-Agents, data_agent.name, wird automatisch aus dem data_agent_id als voll qualifizierter Name (FQN) im Format projects/<project>/locations/<location>/dataAgents/<data_agent_id> abgeleitet.

Beim Erstellen eines Daten-Agents wird 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 Kennzeichnung des Daten-Agents behandelt.

Wenn Sie die Conversational Analytics API zum Erstellen von KI-Datenagenten verwenden, gelten die folgenden Szenarien:

  • Wenn Sie data_agent_id nicht definieren, wird automatisch eine eindeutige ID generiert.
  • Wenn Sie data_agent_id beispielsweise als TestID definieren, wird jeder Wert, den Sie möglicherweise für data_agent.name eingegeben haben, mit projects/<project>/locations/<location>/dataAgents/TestID überschrieben.
  • Wenn Sie data_agent_id mit einem FQN definieren, erhalten Sie den Fehler „malformed name“.

Welches Format wird für eine ID in „Create Agent“ oder „Create Conversation“ akzeptiert?

Für KI-Agenten für Datenverarbeitung:

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 entsprechen, das unter https://google.aip.dev/122#resource-id-segments beschrieben wird.

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

Es wird empfohlen, dieses Feld bei der Agent-Erstellung 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 entsprechen, das unter https://google.aip.dev/122#resource-id-segments beschrieben wird.

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

Wir empfehlen, dieses Feld bei der Erstellung von Unterhaltungen nicht festzulegen, da Conversational Analytics es automatisch erkennt und dann mit {parent}/conversations/{conversation_id} überschreibt.

Wie verwende ich die Aktualisierungsmaske?

Im Update Data Agent flow (Ablauf zum Aktualisieren des Data Agents) verwendet der Parameter updateMask einen FieldMask-Formatstring, der angibt, welche dataAgent-Felder in der dataAgent-Ressource durch die Aktualisierung überschrieben werden. Der Parameter updateMask ist ein Pflichtfeld und wird so validiert:

  • Wenn updateMask leer ist, wird ein BadRequestException ausgegeben und es werden keine Felder aktualisiert.
  • Wenn alle Felder in updateMask gültige dataAgent-Felder sind, werden nur diese Felder aktualisiert.
  • Wenn eine Mischung aus gültigen und ungültigen Feldern angegeben wird, 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 der getIamPolicy-Methode und der setIamPolicy-Methode 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 Speicherfunktionen hat der Daten-Agent der Conversational Analytics API?

  • Innerhalb einer einzelnen Sitzung: Die Conversational Analytics API unterstützt Multi-Turn-Unterhaltungen. Das bedeutet, dass sie sich auf frühere Teile der aktuellen Unterhaltung beziehen kann.
  • Ü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 zustandsbehaftete Agents mit von Google verwalteten Multi-Turn-Unterhaltungen unterstützt.
  • Langzeitspeicher: Daten-Agents für die Conversational Analytics API unterstützen keine expliziten Langzeitspeicherfunktionen.

Erhalte ich von einem Conversational Analytics API-Daten-Agenten immer dieselbe Antwort, wenn ich dieselbe Frage stelle?

  • Antworten in natürlicher Sprache des Daten-KI-Agenten der Conversational Analytics API sind nicht deterministisch. Die vom Agenten bereitgestellte Antwort in natürlicher Sprache kann also auch bei einer identisch formulierten Frage variieren.
  • Antworten auf Datenabfragen: Bei einer Frage, die auf die Suche nach bestimmten Daten abzielt, sollte die zugrunde liegende generierte Abfrage (SQL- oder Looker-Abfrage) deterministisch sein. Die abgerufenen Daten sollten identisch sein, sofern sich die zugrunde liegenden Daten nicht geändert haben.

Wie kann ich die Genauigkeit der Antworten eines Conversational Analytics API-Daten-Agents verbessern?

Eine Möglichkeit, die Genauigkeit der Antworten von Data Agents zu verbessern, besteht darin, dem Data Agent aussagekräftige Kontextinformationen zur Verfügung zu stellen. Sie haben folgende Möglichkeiten, Kontext hinzuzufügen:

  • In der semantischen Ebene von Looker können Sie Kontext in den LookML-Definitionen angeben. Weitere Informationen und Beispiele finden Sie auf der Dokumentationsseite Agent-Verhalten mit selbst erstelltem Kontext in Looker steuern.
  • Wenn Sie einen Daten-Agenten erstellen, können Sie Systemanweisungen angeben. Das sind benutzerdefinierte Anleitungen, die das Verhalten eines Daten-Agenten beeinflussen können. Diese Anleitung umfasst geschäftsspezifische Logik, Antwortformatierung oder Datendarstellung. Sie können auch „Golden Queries“ bereitstellen. Das sind Beispielanfragen in natürlicher Sprache, die mit den entsprechenden korrekten SQL- oder Looker-Abfragen verknüpft sind. Weitere Informationen zu Systemanweisungen finden Sie auf der Dokumentationsseite Agent-Verhalten mit selbst erstelltem Kontext steuern.

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

Kann ich die Conversational Analytics API in Drittanbieteranwendungen einbinden?

Durch die Integration der Conversational Analytics API in Drittanbieteranwendungen können Nutzer direkt in den Tools, die sie täglich verwenden, mit ihren Daten interagieren.

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

Beispiele oder Bibliotheken für die Entwicklung einer Integration finden Sie im Repository für die Kurzanleitung zur konversationellen Analyse. Sie können auch die Google-Entwicklerforen besuchen, um nach Beispielen von anderen Nutzern zu 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 die folgenden Datenquellen:

  • BigQuery
  • Looker-Explores
  • Looker Studio

Sie können auch über BigQuery eine Verbindung zu Quellen wie SAP und Salesforce und über Looker Studio eine Verbindung zu CSV-Dateien und Google-Tabellen herstellen.

Welche Einschränkungen sind bei der Conversational Analytics API bekannt?

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 abzufragen, die zu einem beliebigen Projekt oder einer beliebigen Region gehören.

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

Da die Conversational Analytics API Datenstandort (Data Residency Zone, DRZ) oder Dienstkontrollperimeter (VPC Service Controls, VPC-SC) noch nicht unterstützt, können Sie Agents noch nicht in bestimmten geografischen Regionen hosten. Die Regionalisierung von Daten wird nicht unterstützt.

Unterstützt die Conversational Analytics API auch 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 viele Sprachen und einige Nutzer haben berichtet, dass sie auch mit nicht englischsprachigen Anfragen erfolgreich waren, aber die Conversational Analytics API unterstützt offiziell nur Englisch.