Renderizar uma resposta do agente como uma visualização

A API Análises de conversação pode gerar visualizações interativas com base nas perguntas dos usuários. A API retorna gráficos como configurações JSON do Vega-Lite ou imagens SVG (para fontes de dados do Looker e apenas nas versões v1alpha e v1beta da API). Você também pode instruir um agente a gerar gráficos com requisitos específicos. As visualizações são criadas usando os resultados dos dados obtidos em resposta à pergunta do usuário.

Um gráfico de barras mostra o preço promocional total e a contagem de pedidos de calças para as faixas etárias de 20 a 30 anos e de 40 a 50 anos no estado da Califórnia.

Um gráfico de área mostra a performance mensal do preço total de vendas nos últimos 12 meses, com um pico de US $3.395,12 e uma média de US $2.517,68.

Visualizações compatíveis

A API usa o Vega-Lite para criar visualizações e é compatível com todos os recursos padrão do Vega-Lite. Os seguintes tipos de gráficos são aceitos:

  • Área
  • Barras
  • Geoshape
  • Mapa de calor
  • Linha (série temporal)
  • Pizza
  • Dispersão

Como os gráficos são gerados

O agente identifica o resultado de dados relevante e o transmite a um subagente. Esse subagente executa código Python para gerar uma configuração JSON do Vega-Lite para o gráfico. A API usa o contexto da conversa para entender melhor a intenção do usuário ao gerar gráficos. Ao usar Python, a API pode criar gráficos mais complexos.

O agente pode realizar pequenas transformações de dados, como agregações ou aplicação de filtros, para tornar o gráfico mais relevante e legível.

Formatos de saída

O gráfico é retornado em uma mensagem de resultado chart e pode ser fornecido nos seguintes formatos:

É possível solicitar imagens usando o campo ChartOptions no contexto. Quando uma imagem é solicitada, a API fornece a imagem e a saída JSON do Vega-Lite.

Renderizar uma resposta do agente como uma visualização

Esta seção demonstra como usar o SDK do Python para renderizar uma visualização das especificações de gráficos fornecidas em uma resposta da API Análises de conversação. O exemplo de código extrai a especificação do gráfico (no formato Vega-Lite) do campo chart da resposta e usa a biblioteca Altair (criada no Vega-Lite) para renderizar, salvar como imagem e mostrar o gráfico.

Para mais detalhes sobre como renderizar gráficos com o Vega-Lite e o ecossistema dele, consulte Ferramentas para criar visualizações do Vega-Lite.

Exemplo: renderizar um gráfico da saída do Vega-Lite

Este exemplo mostra como renderizar um gráfico de barras com base em uma resposta do agente da API Conversational Analytics. O exemplo envia uma solicitação com o seguinte comando:

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

O exemplo de código define as seguintes funções auxiliares:

  • render_chart_response: extrai a configuração do Vega-Lite da mensagem chart, converte para um formato que pode ser usado pela biblioteca Altair, renderiza o gráfico, salva em chart.png e o mostra.
  • chat: envia uma solicitação à API Conversational Analytics usando a variável inline_context e a lista messages atual, processa a resposta de streaming e, se um gráfico for retornado, chama render_chart_response para mostrá-lo.

Para usar o exemplo de código a seguir, substitua:

  • sqlgen-testing: o ID do seu projeto de faturamento que tem as APIs necessárias ativadas.
  • Create a bar graph that shows the top five states by the total number of airports: o comando que você quer enviar para a 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")