La API de Conversational Analytics puede generar visualizaciones interactivas basadas en las preguntas de los usuarios. La API devuelve gráficos como configuraciones JSON de Vega-Lite o imágenes SVG (para fuentes de datos de Looker y solo en las versiones de la API v1alpha y v1beta). También puedes indicarle a un agente que genere gráficos con requisitos específicos. Las visualizaciones se crean con los resultados de los datos obtenidos en respuesta a la pregunta del usuario.
Visualizaciones admitidas
La API usa Vega-Lite para crear visualizaciones y admite todas las funciones estándar de Vega-Lite. Se admiten los siguientes tipos de gráficos:
- Área
- Bar
- Geoshape
- Mapa de calor
- Línea (serie temporal)
- Circular
- Dispersión
Cómo se generan los gráficos
El agente identifica el resultado de datos pertinente y lo pasa a un subagente. Este subagente ejecuta código de Python para generar una configuración JSON de Vega-Lite para el gráfico. La API usa el contexto de la conversación para comprender mejor la intención del usuario cuando genera gráficos. Con Python, la API puede crear gráficos más complejos.
El agente puede realizar transformaciones de datos menores, como agregaciones o la aplicación de filtros, para que el gráfico sea más pertinente y legible.
Formatos de salida
El gráfico se devuelve en un mensaje de resultado chart y se puede proporcionar en los siguientes formatos:
- JSON de Vega-Lite
- Imagen SVG
Puedes solicitar imágenes con el campo ChartOptions en el contexto. Cuando se solicita una imagen, la API proporciona la imagen y el resultado JSON de Vega-Lite.
Renderiza una respuesta del agente como una visualización
En esta sección, se muestra cómo usar el SDK de Python para renderizar una visualización a partir de las especificaciones del gráfico que se proporcionan en una respuesta de la API de Conversational Analytics. El código de muestra extrae la especificación del gráfico (en formato de Vega-Lite) del campo chart de la respuesta y usa la biblioteca Altair (que se basa en Vega-Lite) para renderizar el gráfico, guardarlo como una imagen y mostrarlo.
Para obtener más detalles sobre la renderización de gráficos con Vega-Lite y el ecosistema de Vega-Lite, consulta Herramientas para crear visualizaciones de Vega-Lite.
Ejemplo: Renderiza un gráfico a partir de la salida de Vega-Lite
En este ejemplo, se muestra cómo renderizar un gráfico de barras a partir de una respuesta del agente de la API de Conversational Analytics. En el ejemplo, se envía una solicitud con la siguiente instrucción:
"Create a bar graph that shows the top five states by the total number of airports."
El código de muestra define las siguientes funciones auxiliares:
render_chart_response: Extrae la configuración de Vega-Lite del mensajechart, la convierte en un formato que pueda usar la biblioteca de Altair, renderiza el gráfico, lo guarda enchart.pngy, luego, lo muestra.chat: Envía una solicitud a la API de Conversational Analytics con la variableinline_contexty la listamessagesactual, procesa la respuesta de transmisión y, si se muestra un gráfico, llama arender_chart_responsepara mostrarlo.
Para usar el siguiente código de muestra, reemplaza lo siguiente:
- sqlgen-testing: Es el ID de tu proyecto de facturación que tiene las APIs requeridas habilitadas.
- Create a bar graph that shows the top five states by the total number of airports: Es la instrucción que deseas enviar a la API de 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")