KI-Datenagenten erstellen und mit Ihren Daten chatten

Wichtig:Die Data QnA API wird nicht mehr unterstützt. Wenn Sie von der Data QnA API migrieren, finden Sie in der Migrationsanleitung eine Übersicht über die wichtigsten Unterschiede und erforderlichen Migrationsschritte.

Mit der über geminidataanalytics.googleapis.com oder regionale Endpunkte aufrufbaren Conversational Analytics API können Entwickler eine auf künstlicher Intelligenz (KI) basierende Chat-Oberfläche oder einen Daten-KI-Agenten erstellen. Die API verwendet natürliche Sprache, um Fragen zu strukturierten Daten in BigQuery, Looker und Data Studio zu beantworten. Außerdem unterstützt sie das Abfragen von Daten aus AlloyDB, GoogleSQL for Spanner, Cloud SQL und Cloud SQL for PostgreSQL über die Methode QueryData.

Über die Conversational Analytics API stellen Sie Ihrem Daten-KI-Agenten Informationen zum Unternehmen und Daten (Kontext) sowie Zugriff auf Tools wie SQL, Python und Bibliotheken zur Visualisierung zur Verfügung. Die Antworten des KI-Agenten werden dem Nutzer präsentiert und können von der Clientanwendung protokolliert werden, wodurch ein nahtloser Chat mit prüfbaren Daten entsteht.

Erfahren Sie, wann und wie Gemini für Google Cloud Ihre Daten verwendet

Da es sich bei Produkten von Gemini für Google Cloudum Technologie in einem frühen Entwicklungsstadium handelt, kann es zu Ergebnissen kommen, die zwar plausibel erscheinen, aber faktisch falsch sind. Ausgaben der Produkte von Gemini für Google Cloud sollten daher vor der Verwendung geprüft werden. Weitere Informationen finden Sie unter Gemini für Google Cloud und verantwortungsbewusste Anwendung von KI.

Erste Schritte mit der Conversational Analytics API

Bevor Sie die Conversational Analytics API verwenden, sollten Sie sich die folgende Dokumentation ansehen, um die verfügbaren Integrationsansätze und wichtigsten Konzepte kennenzulernen:

• Architektur und wichtige Konzepte: Hier erfahren Sie, wie Daten-Agents Anfragen verarbeiten, welche Workflows für Ersteller und Nutzer von Agents gelten, welche Konversationsmodi es gibt und welche IAM-Rollen (Identity and Access Management) erforderlich sind.
• Integrationsmuster für Data Agents: Vergleichen Sie verschiedene architektonische Ansätze, um die beste Verbindungsmethode für Ihre Anwendung zu ermitteln.
• Zustandsverwaltung: Informationen zu zustandsbehafteten und zustandslosen Konversationsmodi, zur Verwaltung des Konversationsverlaufs durch die API und zu ADK-Sitzungsstatusbereichen.
• Sicherheit, Datenschutz, Risiko und Compliance: Hier finden Sie Informationen zu den Sicherheits- und Compliance-Optionen für die Conversational Analytics API.
• Standorte der Conversational Analytics API: Hier finden Sie eine Übersicht der regionalen oder multiregionalen API-Endpunkte, mit denen Sie den geografischen Standort der Ressourcen, Konfiguration und Daten Ihres Agents steuern können.

Wenn Sie mit dem Erstellen von Data Agents beginnen möchten, führen Sie die Schritte in der Dokumentation Einrichtung und Voraussetzungen aus. Anleitungen, Beispielanwendungen, SDKs und andere Entwicklungstools finden Sie unter Anleitungen, Demos und Tools für die Conversational Analytics API.

Einrichtung und Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie die API oder die Beispiele verwenden:

• Conversational Analytics API aktivieren: Hier werden die Voraussetzungen für die Aktivierung der Conversational Analytics API beschrieben.
• Zugriffssteuerung mit IAM: Beschreibt, wie Sie mit Identity and Access Management den Zugriff auf Daten-Agents freigeben und verwalten.
• Authentifizieren und Verbindung zu einer Datenquelle herstellen: Hier finden Sie eine Anleitung zur Authentifizierung bei der API und zum Konfigurieren von Verbindungen zu Ihren BigQuery-, Lakehouse-, Looker-, Data Studio- und Cloud Databases-Daten (AlloyDB, GoogleSQL for Spanner, Cloud SQL und Cloud SQL for PostgreSQL).
• Vom Kunden verwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK): Hier wird beschrieben, wie Sie Ihre eigenen Verschlüsselungsschlüssel in Cloud Key Management Service verwenden, um Daten-Agents und Unterhaltungen zu schützen, die Looker-Datenquellen verwenden.
• Einschränkungen für Organisationsrichtlinien: Hier wird beschrieben, wie Sie vordefinierte Einschränkungen für Organisationsrichtlinien verwenden, um Ressourcen auf Organisations-, Ordner- oder Projektebene zu steuern.

KI-Datenagenten erstellen und mit einem KI-Datenagenten interagieren

Nachdem Sie die vorherigen Schritte ausgeführt haben, können Sie mit der Conversational Analytics API einen KI-Datenagenten erstellen und mit dem KI-Datenagenten interagieren. Gehen Sie dazu so vor:

• KI-Datenagenten mit HTTP erstellen: Hier finden Sie ein vollständiges Beispiel für das Erstellen und Interagieren mit einem KI-Datenagenten mithilfe direkter HTTP-Anfragen mit Python.
• Daten-KI-Agenten mit dem Python SDK erstellen: Hier finden Sie ein vollständiges Beispiel für das Erstellen und Interagieren mit einem Daten-KI-Agenten mit dem Python SDK.
• Verhalten von KI-Agenten mit selbst erstelltem Kontext steuern: Hier erfahren Sie, wie Sie selbst erstellten Kontext bereitstellen, um das Verhalten von KI-Agenten zu steuern und die Accuracy der Antworten zu verbessern. Beispiele für selbst erstellten Kontext finden Sie auch unter BigQuery-Datenquellen und Looker-Datenquellen.
• Eine Antwort eines Conversational Analytics API-Agenten als Visualisierung rendern: Hier finden Sie ein Beispiel für die Verarbeitung von Diagrammspezifikationen aus API-Antworten und das Rendern als Visualisierungen mit dem Python SDK und der Vega-Altair-Bibliothek.
  Hinweis:Das Erstellen von KI-Datenagenten mit HTTP oder dem Python SDK und das Rendern von Visualisierungen wird für Datenbankdatenquellen (AlloyDB, GoogleSQL for Spanner, Cloud SQL und Cloud SQL for PostgreSQL) nicht unterstützt.

Best Practices

In den folgenden Anleitungen finden Sie Best Practices für die Verwendung der Conversational Analytics API:

• BigQuery-Kosten für Ihre KI-Agenten verwalten: Hier erfahren Sie, wie Sie die BigQuery-Kosten für Ihre Conversational Analytics API-Agenten überwachen und verwalten, indem Sie Ausgabenlimits auf Projekt-, Nutzer- und Abfrageebene festlegen.
• Effektive Fragen stellen: Hier erfahren Sie, wie Sie effektive Fragen für Ihre KI-Agenten formulieren, um die Conversational Analytics API optimal zu nutzen.
• Datenaufbewahrung und ‑löschung: Hier finden Sie Informationen zur Datenaufbewahrung und ‑löschung für Datenagenten und Unterhaltungen der Conversational Analytics API.
• Kontingente und Limits: Informationen zu den Kontingenten und Limits für die Conversational Analytics API.
• Fehler bei der Conversational Analytics API beheben: Häufige Fehler der Conversational Analytics API beheben.
• Bekannte Einschränkungen: Hier finden Sie detaillierte Informationen zu bekannten Einschränkungen der Conversational Analytics API, einschließlich Einschränkungen bei Abfragen, Daten, Visualisierungen und Fragen.
• Agent-Antworten für Looker-Datenquellen rendern: Hier finden Sie Best Practices für das Rendern von Conversational Analytics API-Antworten in einer Benutzeroberfläche, wenn Sie Looker-Datenquellen verwenden.

API-Referenz und Clientbibliotheken

• REST-Referenz zur Gemini Data Analytics API: Hier finden Sie detaillierte Beschreibungen von API-Versionen, Methoden, Endpunkten und Typdefinitionen.
• SDKs und Entwicklungstools: Hier werden sprachspezifische Clientbibliotheken aufgeführt.

Wichtige API-Vorgänge

Die API bietet die folgenden Kernendpunkte zum Verwalten von KI-Datenagenten und Unterhaltungen:

Vorgang	HTTP-Methode	Endpunkt	Beschreibung
KI-Agenten erstellen	POST	/v1/projects/*/locations/*/dataAgents	Erstellt einen neuen KI-Datenagenten.
Agent synchron erstellen	POST	/v1/projects/*/locations/*/dataAgents:createSync	Erstellt synchron einen neuen Daten-Agenten.
KI-Agenten abrufen	GET	/v1/projects/*/locations/*/dataAgents/*	Ruft die Details zu einem bestimmten Daten-KI-Agenten ab.
Richtlinie für Identity and Access Management abrufen	POST	/v1/projects/*/locations/*/dataAgents/*:getIamPolicy	Ruft die Identity and Access Management-Berechtigungen ab, die den einzelnen Nutzern für einen bestimmten Daten-KI-Agenten zugewiesen sind. Nutzer mit der Rolle Data Agent Owner können diesen Endpunkt aufrufen und sich die entsprechende IAM-Richtlinie (Identity and Access Management) anschauen, bevor sie Daten-KI-Agenten über den setIAMpolicy-Endpunkt für andere Nutzer freigeben.
Identity and Access Management-Richtlinie festlegen	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Legt die Identity and Access Management-Richtlinie für einen bestimmten Daten-KI-Agenten fest. Nutzer mit der Rolle Data Agent Owner müssen diesen Endpunkt aufrufen, um einen Daten-KI-Agenten für andere Nutzer freizugeben. Dadurch werden die Identity and Access Management-Berechtigungen dieser Nutzer aktualisiert.
KI-Agenten aktualisieren	PATCH	/v1/projects/*/locations/*/dataAgents/*	Ändert einen vorhandenen KI-Datenagenten.
KI-Agenten synchron aktualisieren	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Ändert einen vorhandenen KI-Datenagenten synchron.
KI-Agenten auflisten	GET	/v1/projects/*/locations/*/dataAgents	Listet die verfügbaren Daten-KI-Agenten in einem Projekt auf.
Verfügbare KI-Agenten auflisten	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Listet die verfügbaren Daten-KI-Agenten in einem Projekt auf. Ein Daten-KI-Agent gilt als verfügbar, wenn der Nutzer, der diese API aufruft, die Berechtigung get für den KI-Agent hat. Mit dem Feld creator_filter können Sie festlegen, welche KI-Agenten von dieser Methode zurückgegeben werden: NONE (Standard): Gibt alle Daten-KI-Agenten zurück, auf die der Nutzer zugreifen kann, unabhängig davon, wer die KI-Agenten erstellt hat. CREATOR_ONLY: Gibt nur die Daten-KI-Agenten zurück, auf die der Nutzer zugreifen kann und die von diesem Nutzer erstellt wurden. NOT_CREATOR_ONLY: Gibt nur die Daten-KI-Agenten zurück, auf die der Nutzer zugreifen kann und die von anderen erstellt wurden.
KI-Agenten löschen	DELETE	/v1/projects/*/locations/*/dataAgents/*	Entfernt einen KI-Datenagenten.
KI-Agenten synchron löschen	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Entfernt einen KI-Datenagenten synchron.
Unterhaltung erstellen	POST	/v1/projects/*/locations/*/conversations	Startet eine neue, dauerhafte Unterhaltung.
Mit Unterhaltungsverweis chatten	POST	/v1/projects/*/locations/*:chat	Setzt eine zustandsorientierte Unterhaltung fort, indem eine Chatnachricht gesendet wird, die auf eine vorhandene Unterhaltung und den zugehörigen KI-Agentenkontext verweist. Bei Multi-Turn-Unterhaltungen speichert und verwaltet Google Cloud den Unterhaltungsverlauf.
Mit KI-Datenagentenverweis chatten	POST	/v1/projects/*/locations/*:chat	Sendet eine zustandslose Chatnachricht, die zur Kontextualisierung auf einen gespeicherten KI-Datenagenten verweist. Bei Multi-Turn-Unterhaltungen muss Ihre Anwendung den Unterhaltungsverlauf verwalten und bei jeder Anfrage bereitstellen.
Mit Inline-Kontext chatten	POST	/v1/projects/*/locations/*:chat	Sendet eine zustandslose Chatnachricht, indem der gesamte Kontext direkt in der Anfrage angegeben wird, ohne einen gespeicherten KI-Datenagenten zu verwenden. Bei Multi-Turn-Unterhaltungen muss Ihre Anwendung den Unterhaltungsverlauf verwalten und bei jeder Anfrage bereitstellen.
Unterhaltung abrufen	GET	/v1/projects/*/locations/*/conversations/*	Ruft die Details zu einer bestimmten Unterhaltung ab.
Unterhaltungen auflisten	GET	/v1/projects/*/locations/*/conversations	Listet die Unterhaltungen in einem bestimmten Projekt auf.
Nachrichten in einer Unterhaltung auflisten	GET	/v1/projects/*/locations/*/conversations/*/messages	Listet Nachrichten in einer bestimmten Unterhaltung auf.
Unterhaltungen löschen	DELETE	/v1/projects/*/locations/*/conversations/*	Löscht eine bestimmte Unterhaltung. Für den Aufruf dieses Endpunkts ist die IAM-Rolle (Identity and Access Management) Topic Admin oder mindestens die IAM-Berechtigung cloudaicompanion.topics.delete erforderlich.
Daten abfragen	POST	/v1beta/projects/*/locations/*/conversations:queryData	Daten aus AlloyDB-, GoogleSQL for Spanner-, Cloud SQL- und Cloud SQL for PostgreSQL-Datenbanken in natürlicher Sprache abfragen.

Support und Feedback

Wenn Sie Hilfe benötigen oder ein Problem melden möchten, wenden Sie sich an den Kundenservice. Folgen Sie der Anleitung unter Supportanfragen erstellen und verwalten, um Ihre Supportanfrage zu erstellen. Beachten Sie beim Erstellen Ihres Supportfalls die folgenden Richtlinien:

• Wenn Sie Unterstützung für die Conversational Analytics API mit BigQuery benötigen, wählen Sie in der Liste Produkt auswählen die Option BigQuery und im Feld Funktion die Option KI und maschinelles Lernen::Conversational Analytics API in BigQuery aus.
• Wenn Sie Unterstützung für die Conversational Analytics API mit Looker benötigen, wählen Sie in der Liste Produkt auswählen die Option Looker (Original) und im Feld Funktion die Option Gemini in Looker::Conversational Analytics API aus.

Hinweis:Der Support für die Conversational Analytics API umfasst technische Probleme im Zusammenhang mit der Verwendung des API-Dienstes. Das Debuggen von allgemeinem und benutzerdefiniertem Code fällt nicht in den Supportbereich. Kunden sind für das Debuggen ihres eigenen benutzerdefinierten Codes verantwortlich.

Wenn Sie allgemeines Feedback oder Fragen zur Conversational Analytics API haben, senden Sie eine E-Mail an [e-mail]. Wir garantieren keine Antwort auf E-Mail-Nachrichten, lesen sie aber und berücksichtigen das Feedback bei der Planung der Roadmap.

Sie können auch einen Feature-Request für neue Funktionen der Conversational Analytics API einreichen.