Conversational Analytics API: KI-Datenagenten erstellen und mit Ihren Daten chatten

Dieses Produkt oder diese Funktion unterliegt den Bedingungen für Pre-GA-Angebote im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und ‑Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

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 aufrufbaren Conversational Analytics API können Entwickler eine auf künstlicher Intelligenz (KI) basierende Chat-Oberfläche oder einen Daten-KI-Agenten erstellen, der Fragen zu strukturierten Daten in BigQuery, Looker und Looker Studio in natürlicher Sprache beantwortet. Ü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 im Abschnitt zu Gemini für Google Cloud und verantwortungsbewusste Anwendung von KI.

Hinweis: Pre-GA-Vorabversionen (1) sind nur für die Verwendung in Testumgebungen vorgesehen und dürfen nicht in einer Produktionsumgebung oder zur Verarbeitung personenbezogener Daten oder anderer Daten verwendet werden, die rechtlichen oder behördlichen Compliance-Anforderungen unterliegen, und (2) unterliegen den Bedingungen für Pre‑GA-Angebote in den dienstspezifischen Nutzungsbedingungen und dem Einwilligungsnachtrag für Gemini für Google Cloud im Rahmen des Google Cloud Trusted Tester-Programms.

Erste Schritte mit der Conversational Analytics API

Schauen Sie sich vor der Nutzung der Conversational Analytics API die Dokumentation zur Architektur und zu den wichtigsten Konzepten an. Darin erfahren Sie, wie KI-Agenten Anfragen verarbeiten und lernen die Workflows für Ersteller und Nutzer von KI-Agenten, die Konversationsmodi und die IAM-Rollen (Identity and Access Management) kennen. Wenn Sie dann mit der Entwicklung von Daten-KI-Agenten beginnen möchten, können Sie entweder den geführten Abläufen in den Kurzanleitungen, Codelabs und Notebooks oder eigenständig den Schritten unter Einrichtung und Voraussetzungen folgen.

Kurzanleitungen, Codelabs und Notebooks

Die folgenden Ressourcen bieten geführte Abläufe, die Ihnen den Einstieg in die Conversational Analytics API erleichtern:

• Schnellstart-App: Mit dieser Streamlit-Schnellstartanwendung können Sie die Conversational Analytics API in eine lokale Testumgebung einbinden.
• Codelab zur Conversational Analytics API: In dieser Schritt-für-Schritt-Anleitung erfahren Sie, wie Sie das Python SDK mit BigQuery-Daten verwenden.
• Colaboratory-Notebooks für die Conversational Analytics API:
  • HTTP-Colaboratory-Notebook: Hier finden Sie eine interaktive, detaillierte Anleitung zum Einrichten Ihrer Umgebung, zum Erstellen eines KI-Datenagenten und zum Ausführen von API-Aufrufen mithilfe von HTTP-Anfragen.
  • Colaboratory-Notebook für das Python SDK: Hier finden Sie eine interaktive, detaillierte Anleitung zum Einrichten Ihrer Umgebung, zum Erstellen eines KI-Datenagenten und zum Ausführen von API-Aufrufen mit dem Python SDK.

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 für die Conversational Analytics API mit IAM: Hier wird beschrieben, wie Sie Identity and Access Management verwenden, um den Zugriff auf Daten-Agents freizugeben und zu verwalten.
• Bei der Conversational Analytics API authentifizieren und eine Verbindung zu einer Datenquelle herstellen: Hier finden Sie eine Anleitung zur Authentifizierung bei der API und zum Konfigurieren von Verbindungen zu Ihren BigQuery-, Looker- und Looker Studio-Daten.

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.
• KI-Datenagenten mit dem Python SDK erstellen: Hier finden Sie ein vollständiges Beispiel für das Erstellen und Interagieren mit einem KI-Datenagenten 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 Genauigkeit 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.

Best Practices

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

• BigQuery-Kosten für Ihre 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 Agenten formulieren, um die Conversational Analytics API optimal zu nutzen.
• Fehler bei der Conversational Analytics API beheben: Häufige Fehler der Conversation 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.

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	/v1beta/projects/*/locations/*/dataAgents	Erstellt einen neuen KI-Datenagenten.
KI-Agenten abrufen	GET	/v1beta/projects/*/locations/*/dataAgents/*	Ruft die Details zu einem bestimmten Daten-KI-Agenten ab.
Richtlinie für Identity and Access Management abrufen	POST	/v1beta/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 Richtlinie anschauen, bevor sie Daten-KI-Agenten über den setIAMpolicy-Endpunkt für andere Nutzer freigeben.
Identity and Access Management-Richtlinie festlegen	POST	/v1beta/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	/v1beta/projects/*/locations/*/dataAgents/*	Ändert einen vorhandenen KI-Datenagenten.
KI-Agenten auflisten	GET	/v1beta/projects/*/locations/*/dataAgents	Listet die verfügbaren KI-Datenagenten in einem Projekt auf.
Zugängliche KI-Agenten auflisten	GET	/v1beta/projects/*/locations/*/dataAgents:listaccessible	Listet die zugänglichen KI-Datenagenten in einem Projekt auf. Ein Daten-Agent gilt als zugänglich, wenn der Nutzer, der diese API aufruft, die Berechtigung get für den Agent hat. Mit dem Feld creator_filter können Sie festlegen, welche Kundenservicemitarbeiter von dieser Methode zurückgegeben werden: NONE (Standard): Gibt alle Daten-Agents zurück, auf die der Nutzer zugreifen kann, unabhängig davon, wer die Agents erstellt hat. CREATOR_ONLY: Gibt nur die Daten-Agents zurück, auf die der Nutzer zugreifen kann und die von diesem Nutzer erstellt wurden. NOT_CREATOR_ONLY: Gibt nur die Daten-Agents zurück, auf die der Nutzer zugreifen kann und die von anderen erstellt wurden.
KI-Agenten löschen	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Entfernt einen KI-Datenagenten.
Unterhaltung erstellen	POST	/v1beta/projects/*/locations/*/conversations	Startet eine neue, dauerhafte Unterhaltung.
Mit Unterhaltungsverweis chatten	POST	/v1beta/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	/v1beta/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	/v1beta/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	/v1beta/projects/*/locations/*/conversations/*	Ruft die Details zu einer bestimmten Unterhaltung ab.
Unterhaltungen auflisten	GET	/v1beta/projects/*/locations/*/conversations	Listet die Unterhaltungen in einem bestimmten Projekt auf.
Nachrichten in einer Unterhaltung auflisten	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Listet Nachrichten in einer bestimmten Unterhaltung auf.

Feedback geben

Über die folgenden Links können Sie einen Fehler melden oder eine Funktion anfordern.

• Einen Fehlerbericht senden
• Eine Feature Request stellen

Zusätzliche Ressourcen

Die folgenden Ressourcen enthalten Referenzdokumentation, Beispiele und Tools, die Ihnen beim Erstellen von Anwendungen mit der Conversational Analytics API helfen:

• REST-Referenz zur Conversational Analytics API: Hier finden Sie detaillierte Beschreibungen von Methoden, Endpunkten und Typdefinitionen für Anfrage- und Antwortstrukturen.
• Demos und Tools für Conversational Analytics: Hier finden Sie Demos und Tools, die API-Funktionen veranschaulichen und praktische Integrationsmuster bieten.
• Agent Development Kit (ADK): Hier erfahren Sie, wie Sie die Funktion ask_data_insights im ADK verwenden, um Fragen zu Ihren Daten in natürlicher Sprache zu beantworten.