Criar um app de chat com a análise de conversação e o Looker

1. Antes de começar

Neste codelab, você vai aprender a usar a API Conversational Analytics (CA API) com o Looker para criar seu próprio aplicativo de chat para consultar dados. Para aproveitar ao máximo, é recomendável ter familiaridade com o BigQuery, o Looker, os LLMs e agentes, além do Python.

O que você vai aprender

Depois de seguir este codelab, você vai aprender:

• Como usar as Análises de conversação com o Looker
• Como configurar e usar o app de início rápido do Python do Conversational Analytics (e como ele funciona)
• Benefícios de usar o Looker para modelagem semântica com a Análise de conversas

O que é necessário

Para concluir este codelab, você vai precisar de:

• Uma instância do Looker com o Bloco do Looker de dados demográficos da ASC instalado
• Acesso de API e desenvolvedor à sua instância do Looker
• Um ambiente local com Python v3.11+, Git e gcloud instalados.
• Um projeto do Google Cloud com estes papéis do IAM configurados para sua conta de usuário:
• roles/bigquery.dataViewer Leitor de dados do BigQuery
• roles/bigquery.user Usuário do BigQuery
• roles/looker.instanceUser Usuário da instância do Looker

2. Criar e testar seu app de chat com o BigQuery

Primeiro, vamos configurar e testar o app de início rápido da Análise de conversas com o BigQuery como fonte de dados.

Autenticar e ativar as APIs do Cloud

1. Autentique localmente com sua conta de usuário:

gcloud auth login

2. Ative as APIs do projeto do Cloud. Substitua YOUR_PROJECT_ID pelo ID do seu projeto do Google Cloud:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

3. Defina as credenciais padrão do aplicativo (ADC) e o faturamento:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Configurar o app de início rápido

4. Clone o repositório do GitHub de início rápido no seu ambiente local. Confira o exemplo de comando abaixo:

git clone "https://github.com/looker-open-source/ca-api-quickstarts"

5. Navegue até o diretório ca-api-quickstarts que você clonou:

cd ca-api-quickstarts

6. Crie um arquivo secrets.toml no diretório .streamlit. YOUR_LOOKER_CLIENT_ID e YOUR_LOOKER_CLIENT_SECRET precisam ser o ID e a chave secreta do cliente do Looker na sua instância do Looker. O conteúdo do arquivo deve ser o seguinte:

[cloud]
project_id = "YOUR_PROJECT_ID"

[looker]
client_id = "YOUR_LOOKER_CLIENT_ID"
client_secret = "YOUR_LOOKER_CLIENT_SECRET"

Use o exemplo de comando a seguir para criar o arquivo. Substitua os valores pelo ID do projeto, ID do cliente e segredo do cliente:

cat > .streamlit/secrets.toml <<'EOF'
[cloud]
project_id = "YOUR_PROJECT_ID"

[looker]
client_id = "YOUR_LOOKER_CLIENT_ID"
client_secret = "YOUR_LOOKER_CLIENT_SECRET"
EOF

7. Instale os requisitos do Python do app de início rápido:

pip install -r requirements.txt

8. Execute o app de início rápido:

streamlit run app.py

Você está executando um app Streamlit criado sob medida, um framework de app Python de código aberto que permite criar protótipos de apps de dados interativos. Confira a documentação do Streamlit para saber mais.

9. Abra https://localhost:8501 no navegador de sua preferência.

Testar o app de início rápido

Agora você está na página de agentes do app de início rápido. Não há agentes de dados disponíveis.

O que é um agente de IA de dados? Os agentes de IA são sistemas de software que usam a IA para alcançar objetivos e concluir tarefas em nome dos usuários. Eles demonstram raciocínio, planejamento e memória, com autonomia para tomar decisões, aprender e se adaptar. No nosso caso de uso, usamos agentes de IA para entender nossos dados. O comportamento de um agente é determinado pelas instruções do sistema definidas para ele. Confira O que são agentes de IA? para mais informações.

10. Agora, vamos criar um agente de dados que fale como um pirata no formulário Criar agente:
11. Defina o campo Nome de exibição:

Pirate BQ Agent

2. Defina o campo Instruções do sistema:

You are a pirate. Answer questions like a pirate

3. Selecione a opção BigQuery.
4. Defina o campo Projeto:

bigquery-public-data

5. Defina o campo Conjunto de dados:

google_trends

6. Defina o campo Tabela:

top_rising_terms

11. Selecione Criar agente.

O formulário Criar agente do app de início rápido chama o endpoint create dataAgent da API CA usando o SDK do Python do gcloud, transmitindo as instruções do sistema e a fonte de dados do agente. O app usa o SDK Python do gcloud para todas as chamadas da API CA.

12. Agora, acesse a página de chat na navegação principal à esquerda. Nosso agente recém-criado está disponível para conversar. Vamos iniciar uma conversa adicionando um comando/mensagem: "Olá, tudo bem?"
13. Agora vamos saber um pouco mais sobre esse conjunto de dados: "Sobre o que é este conjunto de dados?"

O que acontece quando você envia um comando (ou mensagem) no chat? O app envia sua mensagem como um payload para o endpoint de chat da API CA. A API CA usa nos bastidores as instruções do sistema do agente de dados e informações da fonte de dados como contexto para seu comando e envia o comando e o contexto ao Gemini. Em seguida, a API CA transmite a resposta do Gemini.

14. Faça outra pergunta, como:
15. "Quais locais de [Enter State] estão no conjunto de dados?"
16. "Você pode me dar os dados das últimas duas semanas de [cidade, estado]?"
17. "Você pode criar uma visualização?"

Você acabou de ter uma conversa de várias rodadas com seu agente de dados e seus dados do BigQuery no seu próprio aplicativo de chat.

3. Modelar e analisar seus dados no Looker

Agora vamos modelar e analisar os mesmos dados do BigQuery no Looker.

Consultar dados do censo do BigQuery

O que acontece quando nos conectamos a um conjunto de dados relacional maior? Primeiro, vamos criar um agente.

1. Volte ao formulário Criar agente na página de agentes.
2. Defina o campo Nome de exibição:

BQ Census Agent

2. Defina o campo Instruções do sistema:

You are really excited about census data, you love learning about the demographics in your area because you want to come up with marketing campaigns for your company

3. Selecione a opção BigQuery.
4. Defina o campo Projeto:

bigquery-public-data

5. Defina o campo Conjunto de dados:

census_bureau_acs

6. Defina o campo Tabela:

blockgroup_2018_5yr

2. Selecione Criar agente.
3. Faça estas duas perguntas ao agente recém-criado:
4. "Quais dados você tem?"
5. "Você pode me mostrar uma prévia dos meus dados?"

Quando você pede ao agente uma prévia dos dados, é possível notar que a tabela não tem um local legível para humanos associado a ela, apenas um identificador geográfico (geo_id).

Usar o Looker para modelar os dados do censo

Agora vamos usar um modelo da LookML para definir os dados do censo do BigQuery. Vamos resolver os problemas que acabamos de ver.

4. Faça login na sua instância do Looker
5. Para acessar os arquivos de bloco de dados demográficos do ACS, navegue até a navegação principal à esquerda, selecione Desenvolver e depois marketplace_acs_census-v2.
6. Vamos analisar uma visualização do Looker. Abra os diretórios imported_project, acs_census-v2 e geography.
7. Por fim, abra o arquivo cbsa.view.
8. Na linha 17, podemos ver que o LookML está criando uma tabela derivada. Em outras palavras, esse código cria uma nova tabela combinada ao unir dois conjuntos de dados públicos do BigQuery, um com dados do censo e outro com dados de limites geográficos. O LookML permite unir vários conjuntos de dados criando uma tabela derivada permanente para consultar.

Uma tabela derivada persistente (PDT) é uma tabela criada pelo Looker e armazenada no seu banco de dados (neste caso, o BigQuery). É uma visualização materializada de uma consulta complexa. Em vez de executar a mesma consulta cara sempre que um usuário pede um relatório, o Looker pode consultar de maneira mais eficiente a PDT pré-calculada para aumentar o desempenho e diminuir o tempo de consulta.

Além disso, a junção é definida em um código versionável (LookML) em vez de instruções do sistema, o que torna o desenvolvimento de agentes mais escalonável. Com a LookML, você pode definir proposições e restrições específicas sobre seus dados para ajudar os usuários a conversar com eles usando um agente de dados.

Analisar os dados do censo modelados do Looker

Vamos executar uma consulta rápida em uma análise detalhada para demonstrar que temos uma fonte de dados centralizada para consultar.

9. No menu de navegação principal à esquerda, selecione Analisar > Bloco de dados do censo > Estado e município.
10. Selecione a métrica Educação > Ensino médio técnico.
11. Selecione as seguintes dimensões:
12. Geografia > Grupo de bloqueio
13. Geografia > Condado > Nome do condado
14. Geografia > Estado > Estado.
15. Execute a consulta (canto superior direito). Agora você vai notar que esses IDs de geografia (chamados de "Grupo de blocos") estão associados a strings legíveis para humanos.
16. Abra a guia de visualização para conferir esses dados em um mapa.

4. Teste o app de chat com o Looker

Agora vamos criar um agente de dados para o Looker.

1. Acesse o formulário Criar agente na página do agente do app de início rápido:
2. Defina o campo Nome de exibição:

Cartoon character data analyst

2. Defina o campo Instruções do sistema:

You are [fill in your favorite cartoon character, Bugs Bunny is a favorite]. Answer questions like that cartoon character

3. Selecione a opção Looker.
4. Defina o campo Url como o URL da sua instância do Looker: "https://..."
5. Defina o campo Modelo:

data_block_acs_bigquery

6. Defina o campo Explorar:

cbsa

7. Selecione Criar agente.
8. Acesse a página de chat e selecione o agente recém-criado.
9. Vamos iniciar uma conversa adicionando um comando/mensagem: "Olá, tudo bem?"
10. Vamos pedir ao agente para descrever o conjunto de dados: "Quais dados você tem disponíveis?"
11. Vamos fazer mais algumas perguntas:
12. "Qual condado de Nova York tem a maior população?"
13. "E os formados do ensino médio per capita?"
14. "Você pode me dar a população por gênero e estado?"
15. "Quero ver um gráfico de barras dos 10 estados mais populosos."

Você viu a visualização do gráfico de barras na sua conversa? A API CA enviou uma mensagem ao app com uma especificação de gráfico Vega. A especificação do gráfico Vega contém os dados e as configurações da visualização, como cores, eixos, tipo de gráfico etc. Com a especificação, o app Streamlit renderizou o gráfico como um gráfico Vega interativo para você visualizar e interagir. Com a API CA, é possível consultar e visualizar seus dados com agentes de dados, produzindo configurações de visualização padrão para facilitar a visualização.

5. O que mais o app de início rápido pode fazer?

Agora você:

• Configurar o app de chat localmente
• Criou um agente de dados do BigQuery e um agente de dados do Looker
• Conversas com seus agentes de dados
• Conheceu os benefícios da modelagem semântica do Looker como contexto para suas conversas

Vamos testar os outros recursos do app de início rápido:

1. Atualize a página da Web do app de início rápido e navegue até a página de chat.
2. Você pode conferir suas conversas anteriores com todas as mensagens dos agentes do BigQuery e do Looker. O front-end do app não armazena as conversas ou mensagens anteriores, mas as busca na API CA.

A API CA fornece endpoints para todas as conversas anteriores e as mensagens delas. O app busca conversas anteriores no endpoint list conversations da API CA. Em seguida, o app busca todas as mensagens anteriores da conversa no endpoint list messages. Quando você envia uma mensagem para uma conversa, a API CA pode associar as mensagens a uma conversa para incluir todas as mensagens anteriores como contexto para uma conversa de várias interações mais útil.

3. Agora, navegue até a página de agentes e selecione seu agente do Looker na lista.
4. Você pode atualizar as configurações do agente ou excluí-lo, se quiser. Nenhum agente é armazenado no front-end do app.

O app chama os endpoints fornecidos da API CA para listar, criar, atualizar e excluir agentes. O app usa a capacidade da API CA de armazenar e gerenciar os agentes. A API CA também oferece outras operações em agentes.

6. Desafios opcionais e mais informações

Se quiser, aproveite para conhecer a análise de conversas e o app de início rápido. Ou então, modifique o app de início rápido. Você pode testar algumas das sugestões e desafios a seguir ou pular para a seção final.

Saiba mais sobre a API do CA e o app de início rápido

• Saiba mais sobre instruções detalhadas do sistema para controlar o comportamento do seu agente.
• Configure outro agente de dados apontando para um novo conjunto de dados do BigQuery.
• Instale um novo bloco do Looker na sua instância, crie um agente e direcione-o para um novo conjunto de dados do Looker.

Desafios da modificação rápida de apps

• Você conhece a incorporação do Looker? Se sim, tente incorporar um painel do Looker no app de início rápido. Considere usar o componente iframe do Streamlit.
• Encontre um conjunto de dados públicos com URLs de vídeos e atualize a lógica de renderização do chat do app para mostrar um vídeo na conversa.

7. Conclusão e principais pontos

Acabou! Você criou um app de chat, agentes de dados e conversou com seus dados usando a API Conversational Analytics. Vamos revisar alguns recursos e conceitos importantes.

Recursos das Análises de conversação

Abordamos muitos recursos da Análise de Conversação, como a capacidade de:

• Criar, atualizar, listar, receber e excluir agentes de dados.
• Direcione os agentes de dados para o BigQuery ou o Looker como uma fonte de dados.
• Crie, liste e receba conversas e as respectivas mensagens.
• Produza especificações de gráficos Vega para visualização imersiva em conversas.
• Usar mensagens anteriores em uma conversa como contexto útil para mensagens futuras.

Benefícios de usar o Looker com a API CA

O Looker oferece uma modelagem semântica centralizada, testável e governável dos seus dados. Combinado com as Análises de conversação, o Looker oferece uma maneira escalonável de fornecer contexto para seus agentes de dados.

A seguir

• Confira a documentação da análise de conversas para mais guias, recursos e casos de uso.
• Fique por dentro e contribua com o repositório de aplicativos de início rápido.