1. Visão geral
Todos nós conhecemos o problema dos "dados ocultos". São os PDFs, imagens e arquivos de texto armazenados em buckets do Cloud Storage, completamente invisíveis para suas consultas SQL e painéis de BI. Tradicionalmente, para acessar esses dados, eram necessários pipelines complexos de OCR, entrada manual de dados ou scripts personalizados frágeis.
Nada disso.
Neste laboratório, vou mostrar como converter 400 arquivos PDF não estruturados, que abrangem texto, tabelas e imagens, em tabelas do BigQuery bem estruturadas com relações inferidas automaticamente entre elas. Vamos fazer isso em minutos usando o BigQuery Knowledge Catalog e o Dataplex.
O que você vai criar
Para entender melhor, vamos analisar uma empresa fictícia: uma franquia de iogurte congelado em rápido crescimento.
Imagine que você gerencia os dados dessa empresa de Froyo. Você tem centenas de receitas e planilhas de especificações de fornecedores, todas salvas como PDFs. Os líderes empresariais querem lançar um agente de IA para ajudar os gerentes de loja e os clientes a consultar detalhes dos produtos.
Aqui está o cenário de pesadelo: um cliente pergunta: "Estou muito interessado no seu froyo Midnight Swirl. Tem algum alérgeno?"
Para responder a isso, seu sistema normalmente precisaria:
- Encontre o PDF da receita "Midnight Swirl".
- Leia os ingredientes (por exemplo, "cacau em pó", "base láctea", "emulsificante X").
- Pesquise em dezenas de PDFs de fornecedores para encontrar as fichas técnicas desses ingredientes específicos.
- Verifique as planilhas do fornecedor para ver se há alérgenos ocultos relacionados a esses ingredientes.
Tentar criar um agente de IA que faça isso na hora lendo 400 PDFs brutos durante a execução é lento, caro e propenso a alucinações. Em vez disso, vamos usar a inferência semântica para extrair tudo isso em um banco de dados relacional primeiro, tornando nosso futuro agente de IA extremamente rápido e 100% baseado em dados SQL factuais.
Vamos começar a criar!
O que você vai aprender
- Como configurar um bucket do Cloud Storage para os arquivos de origem (PDFs)
- Como configurar e executar um job de verificação de dados e inferência semântica no Knowledge Catalog para extrair dados de PDFs de origem e inferir semanticamente as conexões e o contexto, armazenando tudo no BigQuery
- Como usar os agentes do BigQuery para conversar com o conjunto de dados recém-criado
Requisitos
2. Antes de começar
Criar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Confira se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
- Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.
- Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com seu ID do projeto usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- Se você quiser autenticar
gcloud auth login
- Se o projeto não estiver definido, use este comando:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>
- Ative as APIs necessárias: execute este comando para ativar todas as APIs necessárias:
gcloud services enable \
dataplex.googleapis.com \
datacatalog.googleapis.com \
discoveryengine.googleapis.com \
bigqueryconnection.googleapis.com \
bigquery.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com \
serviceusage.googleapis.com \
storage.googleapis.com
Problemas e solução de problemas
A síndrome do projeto fantasma | Você executou |
A barricada de faturamento | Você ativou o projeto, mas esqueceu a conta de faturamento. O AlloyDB é um mecanismo de alto desempenho. Ele não vai iniciar se o "tanque de combustível" (faturamento) estiver vazio. |
Atraso na propagação da API | Você clicou em "Ativar APIs", mas a linha de comando ainda mostra |
Quags de cota | Se você estiver usando uma conta de teste nova, poderá atingir uma cota regional para instâncias do AlloyDB. Se |
Agente de serviço"oculto" | Às vezes, o agente de serviço do AlloyDB não recebe automaticamente o papel |
3. Configuração do bucket do Cloud Storage
Nesta seção, você vai criar uma estrutura organizacional no BigQuery para armazenar dados de receitas e fornecedores do Froyo, especificamente para detalhes do produto Froyo. Ele também estabelece uma conexão a recursos do Cloud, que atua como uma "ponte" segura, permitindo que o BigQuery leia arquivos de fontes externas, como o Cloud Storage.
Antes de começar:
Este repositório contém receitas e arquivos PDF de fornecedores que vamos usar neste projeto. Faça o download desses arquivos. Para fazer o download dos arquivos, siga estas etapas.
No Cloud Shell, execute este comando:
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
Acesse a pasta recém-criada:
cd next-26-keynotes
Extraia a pasta data-cloud-demo
git sparse-checkout set genkey/data-cloud-demo
Depois que o pagamento for concluído, navegue até a pasta data-cloud-demo e extraia os arquivos ZIP para acessar os recursos do codelab.
Criar um bucket e fazer upload dos arquivos PDF do Froyo (receitas e fornecedores)
- No console do Google Cloud, acesse a página Buckets do Cloud Storage.
- Clique em "Criar".
- Na página Criar um bucket, insira as informações do seu bucket. Após cada uma das etapas a seguir, clique em "Continuar" para prosseguir para a próxima:
- Na seção Começar, insira o nome do bucket. Por exemplo: froyo_data
- Na seção Escolha onde armazenar seus dados, selecione "Região" e insira sua região. us-central1
- Na seção Escolha como controlar o acesso a objetos, desmarque a caixa de seleção "Aplicar a prevenção do acesso público neste bucket".
- Clique em "Criar".
- Na lista de buckets, clique no bucket que você criou.
- Na guia Objetos do bucket, clique em "Fazer upload" e depois em "Fazer upload de pastas".
- Selecione a pasta recipes que você extraiu na seção "Antes de começar" deste codelab.
- Clique em Enviar.
- Repita o processo de upload para a pasta suppliers.
Depois de fazer o upload, a estrutura do bucket vai ficar assim (qualquer que seja o nome do bucket):
4. Configuração da conexão do BigQuery
Crie uma conexão a recursos do Cloud. Isso gera uma conta de serviço exclusiva que funciona como o "documento de identidade" do BigQuery para acessar arquivos externos.
- Acesse a página do BigQuery.
- No painel à esquerda, clique em "Explorer". Se o painel esquerdo não aparecer, clique em "Expandir painel esquerdo" para abrir.
- No painel "Explorer", expanda o nome do projeto e clique em "Conexões".
- Na página "Conexões", clique em "Criar conexão".
- Em "Tipo de conexão", escolha "Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (recurso do Cloud)".
- No campo "ID da conexão", insira o nome do ID da conexão:
- bq-connection. Anote esse ID, porque você vai precisar dele ao configurar a verificação de dados mais tarde neste codelab.
- Defina o tipo de local como "Região" e selecione uma opção. Por exemplo, us-central1. A conexão precisa estar na mesma região que seus outros recursos, como conjuntos de dados.
- Clique em "Criar conexão".
- Clique em "Acessar a conexão".
- No painel "Informações da conexão", copie o ID da conta de serviço para usar em uma etapa posterior. A conta de serviço é semelhante a bqcx-**********-qn3a@gcp-sa-bigquery-condel.iam.gserviceaccount.com.
5. Configuração de permissões
- Conceda as permissões necessárias à conexão do BigQuery para acessar objetos do Cloud Storage e o Knowledge Catalog
Acesse a página "IAM e administrador" e, na seção "Visualizar por principais", clique no botão "Conceder acesso". Adicione um principal colando a conta de serviço que você copiou na última etapa. Na seção "Funções", adicione os nomes das seguintes funções uma por uma e salve:
- roles/storage.objectUser
- roles/storage.objectViewer
- papéis/bigquery.user
- roles/bigquery.dataEditor
- roles/aiplatform.viewer
- roles/agentplatform.user
- roles/storage.admin
- roles/dataproc.serviceAgent
- roles/dataplex.discoveryPublishingServiceAgent
- roles/dataplex.serviceAgent
- roles/dataplex.securityAdmin
- Conceder permissões à conta de serviço do Dataplex para acessar o bucket do Cloud Storage
Acesse a página "IAM e administrador" e, na seção "Visualizar por principais", clique no botão "Conceder acesso" e adicione um principal digitando "Dataplex" na barra de texto "Novo principal". Na lista de preenchimento automático, selecione o principal da conta de serviço do Dataplex que se parece com este:
service-*********@ gcp-sa-dataplex.iam.gserviceaccount.com
Conceda os seguintes papéis a essa conta de serviço:
- roles/storage.objectUser
- roles/storage.objectViewer
- roles/storage.viewer
- roles/dataplex.discoveryBigLakePublishingServiceAgentroles/storage.objectUser
- roles/storage.objectViewer
- roles/storage.viewer
- roles/dataplex.discoveryBigLakePublishingServiceAgentroles/storage.objectUser
- roles/storage.objectViewer
- roles/storage.viewer
- roles/dataplex.discoveryBigLakePublishingServiceAgent
6. Configuração do Knowledge Catalog
Crie um Knowledge Catalog para unificar os dados não estruturados e automatizar a descoberta de arquivos não estruturados (como receitas e fornecedores em PDF).
- Criar o DataScan usando curl
Você também pode criar esse job no console, mas, nesta seção, vamos criar verificações para o bucket do Cloud Storage adicionando o datascan_ID e apontando para os conjuntos de dados do BigQuery. Depois disso, o Knowledge Catalog vai criar automaticamente entradas para seus PDFs no BigQuery.
Execute o conjunto de comandos abaixo no terminal do Cloud Shell no projeto ativo atual de interesse:
# 1. Set your variables
PROJECT_ID="<PROJECT_ID>"
REGION="<REGION>"
ENV_SUFFIX="stg1"
DATASCAN_ID="froyo-data-${ENV_SUFFIX}"
BUCKET_NAME="<BUCKET_NAME>"
# 2. Set this to the Name of the connection you created in Step 7
CONNECTION_ID="<CONNECTION_ID_NAME>"
# 3. Define the API Endpoint
DATAPLEX_API="dataplex.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}"
# 4. Create the DataScan via CURL
echo "Creating Dataplex DataScan: ${DATASCAN_ID}..."
curl -X POST "https://$DATAPLEX_API/dataScans?dataScanId=${DATASCAN_ID}" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"data": {
"resource": "//storage.googleapis.com/projects/'"${PROJECT_ID}"'/buckets/'"${BUCKET_NAME}"'"
},
"executionSpec": {
"trigger": {
"on_demand": {}
}
},
"dataDiscoverySpec": {
"bigqueryPublishingConfig": {
"tableType": "BIGLAKE",
"connection": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/connections/'"${CONNECTION_ID}"'"
},
"storageConfig": {
"unstructuredDataOptions": {
"entity_inference_enabled": true
}
}
}
}'
Substitua os valores das variáveis de marcador acima para que o comando seja executado corretamente. Isso apenas cria o trabalho, não o executa.
- Depois de um ou dois minutos, no console do Google Cloud, acesse a página Criação de metadados.
- Na guia de descoberta do Cloud Storage, clique no nome do item de verificação de descoberta. Não clique no link de origem, que pode ser uma opção tentadora, mas vai abrir o armazenamento.
- Etapa crítica:
Edite o job e confira se a caixa de seleção "Ativar inferência semântica" está marcada. Se não estiver, marque essa opção, insira o ID do projeto e a região e clique em "Salvar".
Depois disso, execute o comando a seguir no terminal do Cloud Shell ou clique no botão "Executar agora" na página "Descoberta do Cloud Storage":
gcloud dataplex datascans run $DATASCAN_ID --location=$REGION
- A conclusão do job de verificação vai levar algum tempo. Quando o job terminar, verifique se o conjunto de dados publicado está presente. Para verificar o status do job, acesse a página Criação de metadados, na guia "Descoberta do Cloud Storage", e clique no nome das verificações de descoberta da execução recente. O conjunto de dados publicado vai aparecer, como mostrado abaixo:
Observação: se você encontrar erros na etapa de verificação, aguarde um pouco e tente de novo. Leva alguns minutos para criar o job e concluir a execução.
Para ver a tabela no BigQuery, clique e navegue até o conjunto de dados froyo_data. Clique no ID da tabela no BigQuery e execute a consulta abaixo na guia "Editor de consultas":
SELECT count(*) FROM `agent-data-cloud.froyo_data.froyo_data` LIMIT 1000;
Isso resulta em 400. Se não, volte e execute o job de DataScan novamente.
7. Extração de dados semânticos
Ótimo! Agora vamos extrair a inferência desses objetos não estruturados usando o Knowledge Catalog.
Vamos usar o recurso Insights para gerar instruções SQL e extrair dados estruturados da tabela não estruturada.
- No console do Google Cloud, acesse a página Pesquisa do Knowledge Catalog.
- Pesquise a tabela do conjunto de dados para que você quer ver insights. Na barra de pesquisa, insira o nome do conjunto de dados / tabela da etapa anterior: "froyo_data" e pressione Enter.
- Na lista de resultados, clique na entrada TABLE (não a do conjunto de dados).
- A guia INSIGHTS vai aparecer. Clique nele. Se for necessário ativar alguma API, siga as instruções e faça isso.
Se você ativou APIs neste momento, execute o job de verificação novamente.
- Na guia "INSIGHTS", você vai encontrar o menu suspenso do botão "EXTRAIR". Clique nessa opção e selecione "Extrair com SQL".
Na caixa de diálogo "Extrair com SQL", defina o conjunto de dados de DESTINO como aquele que você viu no resultado do job de verificação de dados. Comece a digitar o nome dele, que vai aparecer no preenchimento automático. Clique no botão Extrair. Você também pode criar um conjunto de dados e extrair.
Isso vai abrir o editor de consultas do BigQuery com uma guia preenchida com o SQL extraído da inferência da verificação de dados.
8. Validação de SQL e criação de esquema
Se a consulta gerada parecer boa e semanticamente relevante para seus dados não estruturados, clique no botão "Executar" no editor de consultas. A criação do esquema necessário para o armazenamento estruturado da mídia não estruturada leva alguns minutos.
Depois disso, é possível verificar o esquema abrindo o conjunto de dados no painel do explorador do BigQuery Studio, conforme mostrado abaixo:
Tudo bem!!! Foi tão legal que fizemos todas essas coisas de banco de dados muito rápido. Agora é hora do teste final!
9. O teste final!!!
Digamos que eu queira que meu agente responda às perguntas do usuário com informações reais, completas e bem organizadas, baseadas em fatos. Vou fazer uma pergunta que o agente só poderá responder consultando vários arquivos de mídia e referências da minha fonte.
Esta é minha pergunta:
I'm really interested in your Midnight Swirl froyo. Are there any allergens in it?
Agora, uma pesquisa genérica ou de LLM vai dizer "Nenhum ingrediente". Mas criamos uma inferência semântica completa, convertendo toda a mídia não estruturada em dados estruturados. Aqui está um SQL simples que vai buscar essas informações:
SELECT p.product_name, i.ingredient_name, a.allergen_name, category, stability
FROM froyo_data.consistsof c
INNER JOIN froyo_data.product p
ON c.product_id = p.product_id
INNER JOIN froyo_data.ingredient i
ON c.ingredient_id = i.ingredient_name
LEFT OUTER JOIN froyo_data.containsallergen a
ON i.ingredient_id = a.ingredient_id
WHERE
UPPER(p.product_name) LIKE '%MIDNIGHT%SWIRL%'
AND allergen_name IS NOT NULL;
Uhuuu! Confira o resultado:
10. Limpar
Depois de concluir este laboratório, não se esqueça de excluir o job de verificação e as tabelas do BigQuery que ele criou.
Acesse https://console.cloud.google.com/bigquery/governance/metadata-curation/cloud-storage-discovery. Clique nas reticências verticais ao lado do job que você quer excluir e clique em EXCLUIR.
Isso deve limpar o job.
11. Parabéns
Nossa implementação conseguiu identificar o alérgeno oculto. Acabou o dark data, pessoal!!! Na parte 2, vamos federar esses dados do BigQuery em um sistema transacional com o AlloyDB para unificar as necessidades de dados do nosso aplicativo de agente.