L'API Conversational Analytics peut générer des visualisations interactives basées sur les questions des utilisateurs. L'API renvoie les graphiques sous forme de configurations Vega-Lite JSON ou d'images SVG (pour les sources de données Looker et uniquement dans les versions v1alpha et v1beta de l'API). Vous pouvez également demander à un agent de générer des graphiques avec des exigences spécifiques. Les visualisations sont créées à partir des résultats de données obtenus en réponse à la question de l'utilisateur.
Visualisations compatibles
L'API utilise Vega-Lite pour créer des visualisations et est compatible avec toutes les fonctionnalités Vega-Lite standards. Les types de graphiques suivants sont acceptés :
- Zone
- Bar
- Forme géographique
- Carte de densité
- Courbe (série temporelle)
- Secteurs
- Nuage de points
Comment les graphiques sont-ils générés ?
L'agent identifie le résultat de données pertinent et le transmet à un sous-agent. Ce sous-agent exécute du code Python pour générer une configuration JSON Vega-Lite pour le graphique. L'API utilise le contexte de la conversation pour mieux comprendre l'intention de l'utilisateur lorsqu'elle génère des graphiques. En tirant parti de Python, l'API peut créer des graphiques plus complexes.
L'agent peut effectuer des transformations de données mineures, telles que des agrégations ou l'application de filtres, pour rendre le graphique plus pertinent et plus lisible.
Formats de sortie
Le graphique est renvoyé dans un message de résultat chart et peut être fourni dans les formats suivants :
- JSON Vega-Lite
- image SVG
Vous pouvez demander des images à l'aide du champ ChartOptions dans le contexte. Lorsqu'une image est demandée, l'API fournit à la fois l'image et la sortie JSON Vega-Lite.
Afficher une réponse d'agent sous forme de visualisation
Cette section explique comment utiliser le SDK Python pour afficher une visualisation à partir des spécifications de graphique fournies dans une réponse de l'API Conversational Analytics. L'exemple de code extrait la spécification du graphique (au format Vega-Lite) du champ chart de la réponse et utilise la bibliothèque Altair (qui est basée sur Vega-Lite) pour afficher le graphique, l'enregistrer en tant qu'image et l'afficher.
Pour en savoir plus sur le rendu des graphiques avec Vega-Lite et l'écosystème Vega-Lite, consultez Outils pour créer des visualisations Vega-Lite.
Exemple : afficher un graphique à partir d'une sortie Vega-Lite
Cet exemple montre comment afficher un graphique à barres à partir d'une réponse d'agent de l'API Conversational Analytics. L'exemple envoie une requête avec le prompt suivant :
"Create a bar graph that shows the top five states by the total number of airports."
L'exemple de code définit les fonctions d'assistance suivantes :
render_chart_response: extrait la configuration Vega-Lite du messagechart, la convertit dans un format utilisable par la bibliothèque Altair, affiche le graphique, l'enregistre danschart.pnget l'affiche.chat: envoie une requête à l'API Conversational Analytics à l'aide de la variableinline_contextet de la listemessagesactuelle, traite la réponse affichée et, si un graphique est renvoyé, appellerender_chart_responsepour l'afficher.
Pour utiliser cet exemple de code, remplacez les éléments suivants :
- sqlgen-testing : ID de votre projet de facturation pour lequel les API requises sont activées.
- Create a bar graph that shows the top five states by the total number of airports : prompt que vous souhaitez envoyer à l'API Conversational Analytics.
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")