Gerar texto com a função AI.GENERATE

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.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Para mais informações, consulte os preços do BigQuery e da Agent Platform.

Antes de começar

  1. 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.
  2. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 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.

    Ativar a API

    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:

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

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

    Acessar o BigQuery

  2. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

    Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

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

  4. Clique em Conferir ações > Criar conjunto de dados.

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

    1. Em ID do conjunto de dados, digite um nome para o conjunto de dados.

    2. 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.
    3. Clique em Criar conjunto de dados.

bq

  1. Para criar um conjunto de dados, use o comando bq mk com a flag --location:

    bq --location=LOCATION mk -d DATASET_ID

    Substitua:

    • LOCATION: o local do conjunto de dados.
    • DATASET_ID: o ID do conjunto de dados que você está criando.
  2. Confirme se o conjunto de dados foi criado:

    bq ls

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

  1. Acessar a página do BigQuery.

    Acessar o BigQuery

  2. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

    Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

  3. No painel Explorer, expanda o nome do projeto e clique em Conexões.

  4. Na página Conexões, clique em Criar conexão.

  5. Em Tipo de conexão, escolha Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (recurso do Cloud).

  6. No campo ID da conexão, insira um nome para a conexão.

  7. 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.

  8. Clique em Criar conexão.

  9. Clique em Ir para conexão.

  10. 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:

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

    Acessar o BigQuery

  2. 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 formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID ou CONNECTION_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.

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

  1. 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_id substitui o projeto padrão.

    Substitua:

    • REGION: sua região de conexão
    • PROJECT_ID: o ID do projeto do Google Cloud
    • CONNECTION_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...
    
  2. 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.

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

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.

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

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:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar a configuração do Terraform em um Google Cloud projeto, siga as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.
  2. 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.

  1. 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 de main.tf.
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. 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.tf recé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.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. 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

  1. 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.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. 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:

  1. Acesse a página IAM e administrador.

    Acessar IAM e administrador

  2. Clique em Adicionar.

    A caixa de diálogo Adicionar principais é aberta.

  3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

  4. No campo Selecionar um papel, selecione Vertex AI e, em seguida, Usuário da Agent Platform.

  5. Clique em Adicionar outro papel.

  6. No campo Selecionar papel, escolha Cloud Storage e, em seguida, Visualizador de objetos do Storage.

  7. 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.

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

    Acessar o BigQuery

  2. 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:

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

    Acessar o BigQuery

  2. 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.

  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.video`
    WITH CONNECTION `us.test_connection`
    OPTIONS (
      object_metadata = 'SIMPLE',
      uris =
        ['gs://cloud-samples-data/generative-ai/video/*']);
  3. 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.

  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.audio`
    WITH CONNECTION `us.test_connection`
    OPTIONS (
      object_metadata = 'SIMPLE',
      uris =
        ['gs://cloud-samples-data/generative-ai/audio/*']);
  3. 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.

  1. No console Google Cloud , 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 Encerrar para excluí-lo.

Excluir recursos individuais

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

Console

  1. Acesse a página do BigQuery.

    Acessar o BigQuery

  2. Exclua o conjunto de dados bqml_tutorial. A exclusão do conjunto de dados também exclui o modelo remoto.

    1. No painel Explorer, expanda o projeto e clique em Conjuntos de dados.

    2. Na lista Conjuntos de dados, clique no conjunto bqml_tutorial.

    3. No painel de detalhes, clique em Excluir.

    4. Na caixa de diálogo Excluir conjunto de dados, clique em Excluir.

  3. Exclua a conexão:

    1. No painel Explorer, expanda o projeto e clique em Conexões.

    2. Na lista ID da conexão, clique na conexão que você criou.

    3. No painel de detalhes, clique em Excluir.

    4. Na caixa de diálogo Excluir conexão, digite delete para confirmar a exclusão.

    5. Clique em Excluir.

gcloud

  1. Exclua o conjunto de dados bqml_tutorial e o modelo remoto:

    bq rm --dataset --recursive bqml_tutorial
    
  2. Exclua a conexão.

    bq rm --connection PROJECT_ID.LOCATION.CONNECTION_ID
    

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud
    • LOCATION: o local da conexão
    • CONNECTION_ID: o ID da conexão.

A seguir