Analisar imagens

Este tutorial mostra como extrair insights de dados de imagem não estruturados integrando o BigQuery ML ao Gemini. No tutorial, você cria um modelo remoto baseado no gemini-2.5-flash e usa a AI.GENERATE_TEXT função para extrair automaticamente metadados, como títulos e anos de lançamento, de uma coleção de pôsteres de filmes.

Objetivos

• Criar uma tabela de objetos do BigQuery sobre dados de imagem em um bucket do Cloud Storage.
• Criar um modelo remoto do BigQuery ML que tenha como destino o modelo gemini-2.5-flash da Gemini Enterprise Agent Platform.
• Usar o modelo remoto com a função AI.GENERATE_TEXT para identificar os filmes associados a um conjunto de pôsteres de filmes.

Custos

Neste tutorial, usamos os seguintes componentes faturáveis do Google Cloud:

• BigQuery ML
• Gemini Enterprise Agent Platform

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

1. No Google Cloud console do, na página do seletor de projetos, escolha ou crie um Google Cloud projeto do.

   Funções necessárias para selecionar ou criar um projeto

   • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
   • Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.
   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

2. Verifique se o faturamento está ativado para o Google Cloud projeto.

3. Ative as APIs do BigQuery, da BigQuery Connection e da Agent Platform.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar as APIs

Funções exigidas

Para seguir este tutorial, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Criar e usar conjuntos de dados, conexões e modelos do BigQuery: administrador do BigQuery (roles/bigquery.admin).
• Conceder permissões à conta de serviço da conexão: administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin).

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste documento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• Criar um conjunto de dados: bigquery.datasets.create
• Criar, delegar e usar uma conexão: bigquery.connections.*
• Definir a conexão padrão: bigquery.config.*
• Definir permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Criar uma tabela de objetos: bigquery.tables.create e bigquery.tables.update
• Criar um modelo e executar a inferência:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Prepare o ambiente

Para realizar a inferência do BigQuery ML em tabelas de objetos usando gemini-2.5-flash, é necessário atribuir uma reserva do BigQuery ao seu projeto. Se já houver uma reserva atribuída ao seu projeto, pule esta etapa.

Criar uma reserva

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No menu de navegação, clique em Gerenciamento de capacidade.

3. Clique em Criar reserva.

4. Na página Criar reserva, siga estas etapas:

   1. Em Nome da reserva, insira bqml-tutorial-reservation.
   2. Em Localização, selecione EUA (várias regiões nos Estados Unidos).
   3. Mantenha as configurações padrão restantes e clique em Salvar.

Atribuir a reserva

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No menu de navegação, clique em Gerenciamento de capacidade.

3. Na tabela Reservas de slots, encontre a reserva que você quer atribuir ao seu projeto.

4. Clique em Ver ações > Criar atribuição.

5. Em Criar uma atribuição, clique em Procurar e selecione seu projeto.

6. Em Tipo de serviço, selecione QUERY. Essa seleção garante que as consultas SQL usem os slots dessa reserva.

7. Clique em Criar.

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar o modelo de ML.

Console

1. No Google Cloud console, acesse a página BigQuery.

   Acessar a página do BigQuery

2. No painel Explorer, clique no nome do seu projeto.

3. Clique em Ver ações > Criar conjunto de dados

4. Na página Criar conjunto de dados, faça o seguinte:

   • Para o código do conjunto de dados, insira bqml_tutorial.

   • Em Tipo de local, selecione Multirregião e selecione EUA.

   • Mantenha as configurações padrão restantes e clique em Criar conjunto de dados.

bq

Para criar um novo conjunto de dados, use o bq mk --dataset comando.

1. Crie um conjunto de dados chamado bqml_tutorial com o local de dados definido como US.

   bq mk --dataset \
     --location=US \
     --description "BigQuery ML tutorial dataset." \
     bqml_tutorial

2. Confirme se o conjunto de dados foi criado:

   bq ls

API

Chame o datasets.insert método com um recurso de conjunto de dados definido.

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

Criar a tabela de objetos

Crie uma tabela de objetos sobre as imagens do pôster do filme no bucket público do Cloud Storage . A tabela de objetos permite analisar as imagens sem movê-las do Cloud Storage.

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte consulta para criar a tabela de objetos:

   CREATE OR REPLACE EXTERNAL TABLE `bqml_tutorial.movie_posters`
     WITH CONNECTION DEFAULT
     OPTIONS (
       object_metadata = 'SIMPLE',
       uris =
         ['gs://cloud-samples-data/vertex-ai/dataset-management/datasets/classic-movie-posters/*']);

Criar o modelo remoto

Crie um modelo remoto que represente um modelo gemini-2.5-flash da Agent Platform:

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte consulta para criar um modelo remoto:

   CREATE OR REPLACE MODEL `bqml_tutorial.gemini-vision`
     REMOTE WITH CONNECTION DEFAULT
     OPTIONS (ENDPOINT = 'gemini-2.5-flash');

   A consulta pode levar alguns minutos para ser concluída. Depois disso, o modelo gemini-vision aparece no conjunto de dados bqml_tutorial no painel Explorer. Como a consulta usa uma instrução CREATE MODEL para criar um modelo, não há resultados de consulta.

Analise os pôsteres de filmes

Use o modelo remoto para analisar os pôsteres de filmes e determinar qual filme cada pôster representa e, em seguida, gravar esses dados em uma tabela.

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte consulta para analisar as imagens do pôster do filme:

   CREATE OR REPLACE TABLE
     `bqml_tutorial.movie_posters_results` AS (
     SELECT
       uri,
      result
     FROM
       AI.GENERATE_TEXT( MODEL `bqml_tutorial.gemini-vision`,
         TABLE `bqml_tutorial.movie_posters`,
         STRUCT( 0.2 AS temperature,
           'For the movie represented by this poster, what is the movie title and year of release? Answer in JSON format with two keys: title, year. title should be string, year should be integer.' AS PROMPT)));
       

3. No editor de consultas, execute a seguinte instrução para visualizar os dados da tabela:

   SELECT * FROM `bqml_tutorial.movie_posters_results`;

   O resultado será assim:

   +--------------------------------------------+----------------------------------+
   | uri                                        | result                           |
   +--------------------------------------------+----------------------------------+
   | gs://cloud-samples-data/vertex-ai/dataset- | json                          |
   | management/datasets/classic-movie-         | {                                |
   | posters/little_annie_rooney.jpg            |  "title": "Little Annie Rooney", |
   |                                            |  "year": 1912                    |
   |                                            | }                                |
   |                                            |                              |
   +--------------------------------------------+----------------------------------+
   | gs://cloud-samples-data/vertex-ai/dataset- | json                          |
   | management/datasets/classic-movie-         | {                                |
   | posters/mighty_like_a_mouse.jpg            |  "title": "Mighty Like a Moose", |
   |                                            |  "year": 1926                    |
   |                                            | }                                |
   |                                            |                              |
   +--------------------------------------------+----------------------------------+
   | gs://cloud-samples-data/vertex-ai/dataset- | json                          |
   | management/datasets/classic-movie-         | {                                |
   | posters/brown_of_harvard.jpeg              |  "title": "Brown of Harvard",    |
   |                                            |  "year": 1926                    |
   |                                            | }                                |
   |                                            |                              |
   +--------------------------------------------+----------------------------------+
   

Formatar a saída do modelo

Para facilitar a leitura do título do filme e dos dados do ano, formate os dados retornados pelo modelo.

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte consulta para formatar os dados:

   CREATE OR REPLACE TABLE
     `bqml_tutorial.movie_posters_results_formatted` AS (
     SELECT
       uri,
       JSON_QUERY(RTRIM(LTRIM(results.result, " ```json"), "```"), "$.title") AS title,
       JSON_QUERY(RTRIM(LTRIM(results.result, " ```json"), "```"), "$.year") AS year
     FROM
       `bqml_tutorial.movie_posters_results` results );

3. No editor de consultas, execute a seguinte instrução para visualizar os dados da tabela:

   SELECT * FROM `bqml_tutorial.movie_posters_results_formatted`;

   O resultado será assim:

   +--------------------------------------------+----------------------------+------+
   | uri                                        | title                      | year |
   +--------------------------------------------+----------------------------+------+
   | gs://cloud-samples-data/vertex-ai/dataset- | "Barque sortant du port"   | 1895 |
   | management/datasets/classic-movie-         |                            |      |
   | posters/barque_sortant_du_port.jpeg        |                            |      |
   +--------------------------------------------+----------------------------+------+
   | gs://cloud-samples-data/vertex-ai/dataset- | "The Great Train Robbery"  | 1903 |
   | management/datasets/classic-movie-         |                            |      |
   | posters/the_great_train_robbery.jpg        |                            |      |
   +--------------------------------------------+----------------------------+------+
   | gs://cloud-samples-data/vertex-ai/dataset- | "Little Annie Rooney"      | 1912 |
   | management/datasets/classic-movie-         |                            |      |
   | posters/little_annie_rooney.jpg            |                            |      |
   +--------------------------------------------+----------------------------+------+
   

Excluir o projeto

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

1. No Google Cloud console, acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
3. Na caixa de diálogo, digite o ID do projeto e clique em Desligar para excluir o projeto.

Excluir recursos individuais

Se você quiser reutilizar o projeto, exclua os recursos criados para o tutorial.

Excluir o conjunto de dados

Console

Exclua todo o conjunto de dados bqml_tutorial e todo o conteúdo dele executando o seguinte comando SQL:

DROP SCHEMA IF EXISTS `bqml_tutorial` CASCADE;

bq

Exclua todo o conjunto de dados bqml_tutorial e todo o conteúdo dele:

bq rm -r bqml_tutorial

Excluir a reserva

Console

Se você criou uma reserva do BigQuery como parte deste tutorial, remova-a para evitar cobranças contínuas de slots.

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No menu de navegação, clique em Gerenciamento de capacidade.

3. Na tabela Reservas de slots, encontre bqml-tutorial-reservation.

4. Clique em Ver ações > Excluir.

bq

Se você criou uma reserva do BigQuery chamada bqml-tutorial-reservation no local us, use o comando a seguir para removê-la:

bq rm --reservation --location=us bqml-tutorial-reservation

Excluir a conexão

Console

1. No Google Cloud console, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel esquerdo, clique em Explorer, localize seu projeto e clique em Conexões.

3. Na tabela, encontre sua conexão.

4. Clique em Ver ações > Excluir.

bq

Exclua a conexão:

bq rm --connection --location=us CONNECTION_ID

Substitua CONNECTION_ID pelo ID real da sua conexão.

A seguir

• Saiba mais sobre as funções de IA generativa no BigQuery.
• Saiba como ajustar um modelo usando seus dados.
• Confira arquiteturas de referência, diagramas, tutoriais e práticas recomendadas do Google Cloud. Confira o Centro de arquitetura do Cloud.