Neste tutorial, mostramos como gerar texto de texto, áudio ou vídeo usando a função AI.GENERATE com um modelo hospedado do Gemini. Essa abordagem elimina a necessidade de criar e manter seu próprio modelo.
Objetivos
- Resumir notícias.
- Gerar uma saída estruturada de artigos de notícias que inclua um resumo e um sentimento geral.
- Crie uma transcrição de um vídeo em japonês e traduza para o inglês.
- Gerar um resumo e uma lista de tópicos com base em conteúdo de áudio.
Custos
Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:
- BigQuery ML: You incur costs for the data that you process in BigQuery.
- Gemini Enterprise Agent Platform: You incur costs for calls to the Agent Platform model.
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Para mais informações, consulte os preços do BigQuery e da Agent Platform.
Antes de começar
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Ative a API BigQuery.
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.Para novos projetos, a API BigQuery é ativada automaticamente.
Funções exigidas
Para receber as permissões necessárias para usar a função AI.GENERATE, peça ao administrador que conceda a você os seguintes papéis do IAM:
-
Criar e usar conjuntos de dados e tabelas do BigQuery:
Editor de dados do BigQuery (
roles/bigquery.dataEditor) no seu projeto. -
Crie, delegue e use conexões do BigQuery:
Administrador de conexões do BigQuery (
roles/bigquery.connectionsAdmin) no seu projeto. -
Conceda permissões à conta de serviço da conexão:
Administrador do IAM do projeto (
roles/resourcemanager.projectIamAdmin) no projeto que contém o endpoint da plataforma do agente do Gemini Enterprise. -
Criar jobs do BigQuery:
Usuário de jobs do BigQuery (
roles/bigquery.jobUser) no seu projeto.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esses papéis predefinidos contêm as permissões necessárias para usar a função AI.GENERATE. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para usar a função AI.GENERATE:
-
Crie um conjunto de dados:
bigquery.datasets.create -
Criar, delegar e usar uma conexão:
bigquery.connections.* -
Defina as permissões da conta de serviço:
-
resourcemanager.projects.getIamPolicy -
resourcemanager.projects.setIamPolicy
-
-
Consultar dados da tabela:
bigquery.tables.getData
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Criar um conjunto de dados
Crie um conjunto de dados do BigQuery para conter seus recursos:
Console
No console do Google Cloud , acesse a página BigQuery.
No painel à esquerda, clique em Explorer:

Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.
No painel Explorer, clique no nome do seu projeto.
Clique em Conferir ações > Criar conjunto de dados.
Na página Criar conjunto de dados, faça o seguinte:
Em ID do conjunto de dados, digite um nome para o conjunto de dados.
Em Tipo de local, selecione Região ou Multirregião.
- Se você selecionou Região, escolha um local na lista Região.
- Se você selecionou Multirregião, escolha EUA ou Europa na lista Multirregião.
Clique em Criar conjunto de dados.
bq
Crie uma conexão
Depois de criar o conjunto de dados de treinamento, estabeleça uma conexão para vincular o BigQuery e fontes externas. Crie uma conexão a recursos do Cloud e tenha acesso à conta de serviço da conexão. Crie a conexão no mesmo local do conjunto de dados criado na etapa anterior.
Selecione uma das seguintes opções:Console
Acessar 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 um nome para a conexão.
Em Tipo de local, selecione um local para sua conexão. A conexão precisa estar alocada com seus outros recursos, como conjuntos de dados.
Clique em Criar conexão.
Clique em Ir para conexão.
No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.
SQL
Use a instrução CREATE CONNECTION:
No console do Google Cloud , acesse a página BigQuery.
No editor de consultas, digite a seguinte instrução:
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME` OPTIONS ( connection_type = "CLOUD_RESOURCE", friendly_name = "FRIENDLY_NAME", description = "DESCRIPTION" );
Substitua:
-
CONNECTION_NAME: o nome da conexão no formatoPROJECT_ID.LOCATION.CONNECTION_ID,LOCATION.CONNECTION_IDouCONNECTION_ID. Se o projeto ou local for omitido, eles serão inferidos do projeto e do local em que a instrução é executada. -
FRIENDLY_NAME(opcional): um nome descritivo para a conexão. -
DESCRIPTION(opcional): uma descrição da conexão.
-
Clique em Executar.
Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.
bq
Em um ambiente de linha de comando, crie uma conexão:
bq mk --connection --location=REGION --project_id=PROJECT_ID \ --connection_type=CLOUD_RESOURCE CONNECTION_ID
O parâmetro
--project_idsubstitui o projeto padrão.Substitua:
REGION: sua região de conexãoPROJECT_ID: o ID do projeto do Google CloudCONNECTION_ID: um ID para sua conexão
Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.
Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:
bq show --connection PROJECT_ID.REGION.CONNECTION_ID
O resultado será o seguinte:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Terraform
Use o
recurso
google_bigquery_connection.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
O exemplo a seguir cria uma conexão de recurso do Google Cloud chamada
my_cloud_resource_connection na região US:
Para aplicar a configuração do Terraform em um Google Cloud projeto, siga as etapas nas seções a seguir.
Preparar o Cloud Shell
- Inicie o Cloud Shell.
-
Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.
Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.
Preparar o diretório
Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.
-
No Cloud Shell, crie um diretório e um novo
arquivo dentro dele. O nome do arquivo precisa ter a extensão
.tf, por exemplo,main.tf. Neste tutorial, o arquivo é chamado demain.tf.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.
Copie o exemplo de código no
main.tfrecém-criado.Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
- Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
- Salve as alterações.
-
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
terraform init
Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção
-upgrade:terraform init -upgrade
Aplique as alterações
-
Revise a configuração e verifique se os recursos que o Terraform vai criar ou
atualizar correspondem às suas expectativas:
terraform plan
Faça as correções necessárias na configuração.
-
Para aplicar a configuração do Terraform, execute o comando a seguir e digite
yesno prompt:terraform apply
Aguarde até que o Terraform exiba a mensagem "Apply complete!".
- Abra seu Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.
Conceder acesso à conta de serviço
Conceda à conta de serviço da conexão as funções de usuário da Agent Platform e leitor de objetos do Storage. Para conceder os papéis, siga estas etapas:
Acesse a página IAM e administrador.
Clique em Adicionar.
A caixa de diálogo Adicionar principais é aberta.
No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.
No campo Selecionar um papel, selecione Vertex AI e, em seguida, Usuário da Agent Platform.
Clique em Adicionar outro papel.
No campo Selecionar papel, escolha Cloud Storage e, em seguida, Visualizador de objetos do Storage.
Clique em Salvar.
Resumir texto e usar o formato de saída padrão
Para resumir artigos de notícias, chame a função AI.GENERATE com o texto do artigo como comando. Por padrão, a saída inclui o texto do resumo gerado, a resposta completa e um status vazio se a função for retornada com sucesso.
No console do Google Cloud , acesse a página BigQuery.
No Editor de consultas, execute esta consulta:
WITH bbc_news AS ( SELECT body FROM `bigquery-public-data.bbc_news.fulltext` LIMIT 5 ) SELECT AI.GENERATE(body, endpoint => 'gemini-2.5-pro') AS news FROM bbc_news;
O resultado será o seguinte:
+---------------------------------------------+------------------------------------+---------------+ | news.result | news.full_response | news.status | +---------------------------------------------+------------------------------------+---------------+ | This article presents a debate about the | {"candidates":[{"avg_logprobs": | | | "digital divide" between rich and poor | -0.31465074559841777, content": | | | nations. Here's a breakdown of the key... | {"parts":[{"text":"This article... | | +---------------------------------------------+------------------------------------+---------------+ | This article discusses how advanced | {"candidates":[{"avg_logprobs": | | | mapping technology is aiding humanitarian | -0.21313422900091983,"content": | | | efforts in Darfur, Sudan. Here's a... | {"parts":[{"text":"This article... | | +---------------------------------------------+------------------------------------+---------------+ | ... | ... | ... | +---------------------------------------------+------------------------------------+---------------+
Resumir texto e gerar resultados estruturados
Siga estas etapas para gerar texto usando a função AI.GENERATE e o argumento output_schema da função AI.GENERATE para formatar a saída:
No Google Cloud console, acesse a página BigQuery.
No Editor de consultas, execute esta consulta:
WITH bbc_news AS ( SELECT body FROM `bigquery-public-data`.bbc_news.fulltext LIMIT 5 ) SELECT news.good_sentiment, news.summary FROM bbc_news, UNNEST(ARRAY[AI.GENERATE(body, endpoint => 'gemini-2.5-pro', output_schema => 'summary STRING, good_sentiment BOOL')]) AS news;
O resultado será o seguinte:
+----------------+--------------------------------------------+ | good_sentiment | summary | +----------------+--------------------------------------------+ | true | A World Bank report suggests the digital | | | divide is rapidly closing due to increased | | | access to technology in developing... | +----------------+--------------------------------------------+ | false | A massive earthquake and subsequent | | | waves have devastated southern Asia, with | | | Sri Lanka, India, Indonesia, and... | +----------------+--------------------------------------------+ | ... | ... | +----------------+--------------------------------------------+
Transcrever e traduzir conteúdo de vídeo
É possível processar arquivos multimídia armazenados no Cloud Storage usando tabelas de objetos externos. As etapas a seguir mostram como criar uma tabela de objetos para arquivos de vídeo, transcrever o conteúdo de vídeo em japonês e traduzir o texto para inglês.
No Google Cloud console, acesse a página BigQuery.
No editor de consultas, execute a seguinte consulta para criar a tabela de objetos:
CREATE OR REPLACE EXTERNAL TABLE `bqml_tutorial.video` WITH CONNECTION `us.test_connection` OPTIONS ( object_metadata = 'SIMPLE', uris = ['gs://cloud-samples-data/generative-ai/video/*']);
No editor de consultas, execute a seguinte consulta para transcrever e traduzir o arquivo
pixel8.mp4:SELECT AI.GENERATE( (OBJ.GET_ACCESS_URL(ref, 'r'), 'Transcribe the video in Japanese and then translate to English.'), endpoint => 'gemini-2.5-pro', output_schema => 'japanese_transcript STRING, english_translation STRING' ).* EXCEPT (full_response, status) FROM `bqml_tutorial.video` WHERE REGEXP_CONTAINS(uri, 'pixel8.mp4');
O resultado será o seguinte:
+--------------------------------------------+--------------------------------+ | english_translation | japanese_transcript | +--------------------------------------------+--------------------------------+ | My name is Saeka Shimada. I'm a | 島田 さえか です 。 東京 で フ | | photographer in Tokyo. Tokyo has many | ォトグラファー を し て い ま | | faces. The city at night is totally... | す 。 東京 に は いろんな 顔 が | +--------------------------------------------+--------------------------------+
Analisar o conteúdo de arquivos de áudio
Siga estas etapas para criar uma tabela de objetos com conteúdo de áudio público e analisar o conteúdo dos arquivos de áudio.
No Google Cloud console, acesse a página BigQuery.
No editor de consultas, execute a seguinte consulta para criar a tabela de objetos:
CREATE OR REPLACE EXTERNAL TABLE `bqml_tutorial.audio` WITH CONNECTION `us.test_connection` OPTIONS ( object_metadata = 'SIMPLE', uris = ['gs://cloud-samples-data/generative-ai/audio/*']);
No editor de consultas, execute a seguinte consulta para analisar os arquivos de áudio:
SELECT AI.GENERATE( (OBJ.GET_ACCESS_URL(ref, 'r'), 'Summarize the content of this audio file.'), endpoint => 'gemini-2.5-pro', output_schema => 'topic ARRAY<STRING>, summary STRING' ).* EXCEPT (full_response, status), uri FROM `bqml_tutorial.audio`;
Os resultados são semelhantes aos seguintes:
+--------------------------------------------+-----------------------------------------------------------+ | summary | topic | uri | +--------------------------------------------+-----------------------------------------------------------+ | The audio contains a distinctive 'beep' | beep sound | gs://cloud-samples-data/generativ... | | sound, followed by the characteristic | | | | sound of a large vehicle or bus backing.. | | | +--------------------------------------------+--------------------+--------------------------------------+ | | vehicle backing up | | | +--------------------+ | | | bus | | | +--------------------+ | | | alarm | | +--------------------------------------------+--------------------+--------------------------------------+ | The speaker introduces themselves | Introduction | gs://cloud-samples-data/generativ... | | as Gemini and expresses their excitement | | | | and readiness to dive into something.. | | | +--------------------------------------------+--------------------+--------------------------------------+ | | Readiness | | | +--------------------+ | | | Excitement | | | +--------------------+ | | | Collaboration | | +--------------------------------------------+--------------------+--------------------------------------+ | ... | ... | ... | +--------------------------------------------+--------------------+--------------------------------------+
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
- No console Google Cloud , acesse a página Gerenciar recursos.
- Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
- Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.
Excluir recursos individuais
Se você quiser reutilizar o projeto, exclua os recursos criados para o tutorial.
Console
Acesse a página do BigQuery.
Exclua o conjunto de dados
bqml_tutorial. A exclusão do conjunto de dados também exclui o modelo remoto.No painel Explorer, expanda o projeto e clique em Conjuntos de dados.
Na lista Conjuntos de dados, clique no conjunto
bqml_tutorial.No painel de detalhes, clique em Excluir.
Na caixa de diálogo Excluir conjunto de dados, clique em Excluir.
Exclua a conexão:
No painel Explorer, expanda o projeto e clique em Conexões.
Na lista ID da conexão, clique na conexão que você criou.
No painel de detalhes, clique em Excluir.
Na caixa de diálogo Excluir conexão, digite
deletepara confirmar a exclusão.Clique em Excluir.
gcloud
Exclua o conjunto de dados
bqml_tutoriale o modelo remoto:bq rm --dataset --recursive bqml_tutorialExclua a conexão.
bq rm --connection PROJECT_ID.LOCATION.CONNECTION_IDSubstitua:
- PROJECT_ID: o ID do projeto do Google Cloud
- LOCATION: o local da conexão
- CONNECTION_ID: o ID da conexão.
A seguir
- Saiba mais sobre a IA generativa no BigQuery.
- Saiba mais sobre como escolher uma função de geração de texto.