Mit der Conversational Analytics API lassen sich interaktive Visualisierungen erstellen, die auf Nutzerfragen basieren. Die API gibt Diagramme entweder als Vega-Lite-JSON-Konfigurationen oder als SVG-Bilder zurück (für Looker-Datenquellen und nur in den API-Versionen v1alpha und v1beta). Sie können einen Agent auch anweisen, Diagramme mit bestimmten Anforderungen zu erstellen. Die Visualisierungen werden anhand der Daten erstellt, die als Antwort auf die Frage des Nutzers abgerufen wurden.
Unterstützte Visualisierungen
Die API verwendet Vega-Lite zum Erstellen von Visualisierungen und unterstützt alle Standardfunktionen von Vega-Lite. Die folgenden Diagrammtypen werden unterstützt:
- Gebiet
- Balkendiagramm
- Geoshape
- Heatmap
- Linie (Zeitreihe)
- Kreisdiagramm
- Streudiagramm
So werden Diagramme generiert
Der Agent ermittelt das relevante Datenergebnis und übergibt es an einen untergeordneten Agent. Dieser untergeordnete Agent führt Python-Code aus, um eine Vega-Lite-JSON-Konfiguration für das Diagramm zu generieren. Die API verwendet den Unterhaltungskontext, um die Nutzerabsicht beim Generieren von Diagrammen besser zu verstehen. Durch die Verwendung von Python können mit der API komplexere Diagramme erstellt werden.
Der Agent führt möglicherweise geringfügige Datentransformationen durch, z. B. Aggregationen oder das Anwenden von Filtern, um das Diagramm relevanter und lesbarer zu machen.
Ausgabeformate
Das Diagramm wird in einer chart-Ergebnismeldung zurückgegeben und kann in den folgenden Formaten bereitgestellt werden:
- Vega-Lite-JSON
- SVG-Bild
Sie können Bilder mit dem Feld ChartOptions im Kontext anfordern. Wenn ein Bild angefordert wird, stellt die API sowohl das Bild als auch die Vega-Lite-JSON-Ausgabe bereit.
Antwort eines KI-Agenten als Visualisierung rendern
In diesem Abschnitt wird gezeigt, wie Sie mit dem Python SDK eine Visualisierung aus den Diagrammspezifikationen rendern, die in einer Antwort der Conversational Analytics API enthalten sind. Im Beispielcode wird die Diagrammspezifikation (im Vega-Lite-Format) aus dem Feld chart der Antwort extrahiert und die Altair-Bibliothek (die auf Vega-Lite basiert) verwendet, um das Diagramm zu rendern, als Bild zu speichern und anzuzeigen.
Weitere Informationen zum Rendern von Diagrammen mit Vega-Lite und zum Vega-Lite-Ökosystem finden Sie unter Tools for Authoring Vega-Lite Visualizations.
Beispiel: Diagramm aus Vega-Lite-Ausgabe rendern
In diesem Beispiel wird gezeigt, wie ein Balkendiagramm aus einer Agent-Antwort der Conversational Analytics API gerendert wird. Im Beispiel wird eine Anfrage mit dem folgenden Prompt gesendet:
"Create a bar graph that shows the top five states by the total number of airports."
Im Beispielcode werden die folgenden Hilfsfunktionen definiert:
render_chart_response: Extrahiert die Vega-Lite-Konfiguration aus derchart-Nachricht, konvertiert sie in ein Format, das von der Altair-Bibliothek verwendet werden kann, rendert das Diagramm, speichert es inchart.pngund zeigt es an.chat: Sendet eine Anfrage an die Conversational Analytics API mit der Variableninline_contextund der aktuellen Listemessages, verarbeitet die Streaming-Antwort und ruftrender_chart_responseauf, um das Diagramm anzuzeigen, falls eines zurückgegeben wird.
Wenn Sie den folgenden Beispielcode verwenden möchten, ersetzen Sie Folgendes:
- sqlgen-testing: Die ID Ihres Abrechnungsprojekts, in dem die erforderlichen APIs aktiviert sind.
- Create a bar graph that shows the top five states by the total number of airports: Der Prompt, den Sie an die Conversational Analytics API senden möchten.
from google.cloud import geminidataanalytics
from google.protobuf.json_format import MessageToDict
import altair as alt
import proto
# Helper function for rendering chart response
def render_chart_response(resp):
def _convert(v):
if isinstance(v, proto.marshal.collections.maps.MapComposite):
return {k: _convert(val) for k, val in v.items()}
elif isinstance(v, proto.marshal.collections.RepeatedComposite):
return [_convert(el) for el in v]
elif isinstance(v, (int, float, str, bool, type(None))):
return v
else:
return MessageToDict(v)
try:
vega_config = _convert(resp.result.vega_config)
chart = alt.Chart.from_dict(vega_config)
chart.save('chart.png')
chart.display()
print("Chart rendered and saved as chart.png")
except Exception as e:
print(f"Error rendering chart: {e}")
# Helper function for calling the API
def chat(q: str, inline_context, messages):
billing_project = "sqlgen-testing"
input_message = geminidataanalytics.Message(
user_message=geminidataanalytics.UserMessage(text=q)
)
messages.append(input_message)
client = geminidataanalytics.DataChatServiceClient()
request = geminidataanalytics.ChatRequest(
inline_context=inline_context,
parent=f"projects/{billing_project}/locations/global",
messages=messages,
)
# Make the request
try:
stream = client.chat(request=request)
for reply in stream:
if reply.system_message and hasattr(reply.system_message, 'chart'):
# ChartMessage includes `query` for generating a chart and `result` with the generated chart.
if hasattr(reply.system_message.chart, 'result'):
print("Chart result found in response.")
render_chart_response(reply.system_message.chart)
else:
print("Chart message found, but no result yet.")
# Append system messages to maintain context for follow-up turns
if reply.system_message:
messages.append(geminidataanalytics.Message(system_message=reply.system_message))
except Exception as e:
print(f"Error calling API: {e}")
# Example Usage:
# Assuming 'inline_context' and 'messages' are initialized as per "Build a data agent using the Python SDK"
# Example initialization (replace with your actual context and message history):
# inline_context = geminidataanalytics.InlineContext(...)
# messages = []
# Send the prompt to make a bar graph
chat("Create a bar graph that shows the top five states by the total number of airports")