Visualizzare la risposta di un agente come visualizzazione

L'API Conversational Analytics può generare visualizzazioni interattive basate sulle domande degli utenti. L'API restituisce i grafici come configurazioni JSON Vega-Lite o immagini SVG (per le origini dati Looker e solo nelle versioni API v1alpha e v1beta). Puoi anche chiedere a un agente di generare grafici con requisiti specifici. Le visualizzazioni vengono create utilizzando i risultati dei dati ottenuti in risposta alla domanda dell'utente.

Un grafico a barre mostra il prezzo di vendita totale e il conteggio degli ordini di pantaloni per le fasce d'età 20-30 anni e 40-50 anni nello stato della California.

Un grafico ad area mostra il rendimento del prezzo totale di vendita mensile degli ultimi 12 mesi, con un picco di 3395,12 $e una media di 2517,68 $.

Visualizzazioni supportate

L'API utilizza Vega-Lite per creare visualizzazioni e supporta tutte le funzionalità standard di Vega-Lite. Sono supportati i seguenti tipi di grafici:

  • Area
  • A barre
  • Geoshape
  • Mappa termica
  • A linee (serie temporale)
  • Torta
  • A dispersione

Come vengono generati i grafici

L'agente identifica il risultato dei dati pertinente e lo trasmette a un subagente. Questo subagent esegue il codice Python per generare una configurazione JSON Vega-Lite per il grafico. L'API utilizza il contesto della conversazione per comprendere meglio l'intent dell'utente durante la generazione dei grafici. Sfruttando Python, l'API può creare grafici più complessi.

L'agente potrebbe eseguire piccole trasformazioni dei dati, come aggregazioni o applicazione di filtri, per rendere il grafico più pertinente e leggibile.

Formati di output

Il grafico viene restituito in un messaggio di risultato chart e può essere fornito nei seguenti formati:

Puoi richiedere immagini utilizzando il campo ChartOptions nel contesto. Quando viene richiesta un'immagine, l'API fornisce sia l'immagine che l'output JSON Vega-Lite.

Visualizzare la risposta di un agente come visualizzazione

Questa sezione mostra come utilizzare l'SDK Python per eseguire il rendering di una visualizzazione dalle specifiche del grafico fornite in una risposta dell'API Conversational Analytics. Il codice campione estrae la specifica del grafico (in formato Vega-Lite) dal campo chart della risposta e utilizza la libreria Altair (basata su Vega-Lite) per eseguire il rendering del grafico, salvarlo come immagine e visualizzarlo.

Per maggiori dettagli sul rendering dei grafici con Vega-Lite e l'ecosistema Vega-Lite, consulta Strumenti per la creazione di visualizzazioni Vega-Lite.

Esempio: rendering di un grafico dall'output di Vega-Lite

Questo esempio mostra come visualizzare un grafico a barre da una risposta dell'agente dell'API Conversational Analytics. L'esempio invia una richiesta con il seguente prompt:

"Create a bar graph that shows the top five states by the total number of airports."

Il codice campione definisce le seguenti funzioni di assistenza:

  • render_chart_response: estrae la configurazione Vega-Lite dal messaggio chart, la converte in un formato utilizzabile dalla libreria Altair, esegue il rendering del grafico, lo salva in chart.png e lo visualizza.
  • chat: invia una richiesta all'API Conversational Analytics utilizzando la variabile inline_context e l'elenco messages corrente, elabora la risposta di streaming e, se viene restituito un grafico, chiama render_chart_response per visualizzarlo.

Per utilizzare il seguente codice campione, sostituisci quanto segue:

  • sqlgen-testing: l'ID del tuo progetto di fatturazione in cui sono abilitate le API richieste.
  • Create a bar graph that shows the top five states by the total number of airports: il prompt che vuoi inviare all'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")