Gere texto através de um modelo do Gemini e da função ML.GENERATE_TEXT

Este tutorial mostra-lhe como criar um modelo remoto com base no modelo gemini-2.0-flash e, em seguida, como usar esse modelo com a função ML.GENERATE_TEXT para extrair palavras-chave e realizar a análise de sentimentos em críticas de filmes da tabela pública bigquery-public-data.imdb.reviews.

Funções necessárias

Para executar este tutorial, precisa das seguintes funções de gestão de identidade e de acesso (IAM):

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

Estas funções predefinidas contêm as autorizações necessárias para realizar as tarefas descritas neste documento. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

• Crie um conjunto de dados: bigquery.datasets.create
• Crie, delegue e use uma associação: bigquery.connections.*
• Defina a ligação predefinida: bigquery.config.*
• Defina as autorizações da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Crie um modelo e execute a inferência:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Para mais informações acerca dos preços do BigQuery, consulte os preços do BigQuery na documentação do BigQuery.

Para mais informações sobre os preços do Vertex AI, consulte a página de preços do Vertex AI.

Antes de começar

1. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

Crie um conjunto de dados

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

Consola

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda à página do BigQuery

2. No painel Explorador, clique no nome do 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 ID do conjunto de dados, introduza bqml_tutorial.

   • Em Tipo de localização, selecione Várias regiões e, de seguida, selecione EUA (várias regiões nos Estados Unidos).

   • Deixe as restantes predefinições como estão e clique em Criar conjunto de dados.

bq

Para criar um novo conjunto de dados, use o comando bq mk com a flag --location. Para uma lista completa de parâmetros possíveis, consulte a referência do comando bq mk --dataset.

1. Crie um conjunto de dados com o nome bqml_tutorial com a localização dos dados definida como US e uma descrição de BigQuery ML tutorial dataset:

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

   Em vez de usar a flag --dataset, o comando usa o atalho -d. Se omitir -d e --dataset, o comando cria um conjunto de dados por predefinição.

2. Confirme que o conjunto de dados foi criado:

   bq ls

API

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

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

DataFrames do BigQuery

Antes de experimentar este exemplo, siga as instruções de configuração dos DataFrames do BigQuery no início rápido do BigQuery com os DataFrames do BigQuery. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure o ADC para um ambiente de desenvolvimento local.

import google.cloud.bigquery

bqclient = google.cloud.bigquery.Client()
bqclient.create_dataset("bqml_tutorial", exists_ok=True)

Crie uma associação

Crie uma associação de recursos do Google Cloud e obtenha a conta de serviço da associação. Crie a associação na mesma localização que o conjunto de dados criado no passo anterior.

Pode ignorar este passo se tiver uma associação predefinida configurada ou tiver a função de administrador do BigQuery.

Crie uma ligação de recursos da nuvem para o modelo remoto usar e obtenha a conta de serviço da ligação. Crie a associação na mesma localização que o conjunto de dados que criou no passo anterior.

Selecione uma das seguintes opções:

Consola

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, clique em Adicionar dados:

   

   É apresentada a caixa de diálogo Adicionar dados.

3. No painel Filtrar por, na secção Tipo de origem de dados, selecione Aplicações empresariais.

   Em alternativa, no campo Pesquisar origens de dados, pode introduzir Vertex AI.

4. Na secção Origens de dados em destaque, clique em Vertex AI.

5. Clique no cartão da solução Modelos da Vertex AI: federação do BigQuery.

6. Na lista Tipo de ligação, selecione Modelos remotos, funções remotas e BigLake (recurso da nuvem) da Vertex AI.

7. No campo ID da associação, introduza um nome para a associação.

8. Clique em Criar associação.

9. Clique em Aceder à associação.

10. No painel Informações de associação, copie o ID da conta de serviço para utilização num passo posterior.

bq

1. Num ambiente de linha de comandos, crie uma associação:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   O parâmetro --project_id substitui o projeto predefinido.

   Substitua o seguinte:

   • REGION: a sua região de ligação
   • PROJECT_ID: o ID do seu Google Cloud projeto
   • CONNECTION_ID: um ID para a sua ligação

   Quando cria um recurso de ligação, o BigQuery cria uma conta de serviço do sistema única e associa-a à ligação.

   Resolução de problemas: se receber o seguinte erro de ligação, atualize o SDK do Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Obtenha e copie o ID da conta de serviço para utilização num passo posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   O resultado é semelhante ao seguinte:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Use o recurso google_bigquery_connection.

Nota: para criar objetos do BigQuery com o Terraform, tem de ativar a API Cloud Resource Manager.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

O exemplo seguinte cria uma associação de recursos da nuvem com o nome 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 num Google Cloud projeto, conclua os passos nas secções seguintes.

Prepare o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o Google Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

   Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

   Copie o exemplo de código para o ficheiro main.tf criado recentemente.

   Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
4. Guarde as alterações.
5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade:

   terraform init -upgrade

Aplique as alterações

1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas:

   terraform plan

   Faça as correções necessárias à configuração.

2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando:

   terraform apply

   Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

3. Abra o seu Google Cloud projeto para ver os resultados. Na Google Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

Nota: os exemplos do Terraform partem geralmente do princípio de que as APIs necessárias estão ativadas no seu Google Cloud projeto.

Conceda autorizações à conta de serviço da associação

Conceda à conta de serviço da ligação a função de utilizador do Vertex AI. Tem de conceder esta função no mesmo projeto que criou ou selecionou na secção Antes de começar. A concessão da função num projeto diferente resulta no erro [e-mail] does not have the permission to access resource.

Para conceder a função, siga estes passos:

1. Aceda à página IAM e administrador.

   Aceda a IAM e administração

2. Clique em Conceder acesso.

3. No campo Novos membros, introduza o ID da conta de serviço que copiou anteriormente.

4. No campo Selecionar uma função, escolha Vertex AI e, de seguida, selecione Função de utilizador da Vertex AI.

5. Clique em Guardar.

Crie o modelo remoto

Crie um modelo remoto que represente um modelo do Vertex AI alojado:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaração:

CREATE OR REPLACE MODEL `bqml_tutorial.gemini_model`
  REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
  OPTIONS (ENDPOINT = 'gemini-2.0-flash');

Substitua o seguinte:

• LOCATION: a localização da ligação
• CONNECTION_ID: o ID da sua ligação ao BigQuery

  Quando vê os detalhes da associação na Google Cloud consola, este é o valor na última secção do ID da associação totalmente qualificado que é apresentado em ID da associação, por exemplo projects/myproject/locations/connection_location/connections/myconnection

A consulta demora vários segundos a ser concluída. Após a conclusão, o modelo gemini_model aparece no conjunto de dados bqml_tutorial no painel Explorador. Uma vez que a consulta usa uma declaração CREATE MODEL para criar um modelo, não existem resultados da consulta.

Realize a extração de palavras-chave

Realize a extração de palavras-chave em críticas de filmes do IMDB usando o modelo remoto e a função ML.GENERATE_TEXT:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração para realizar a extração de palavras-chave em cinco críticas de filmes:

   SELECT
     ml_generate_text_result['candidates'][0]['content'] AS generated_text,
     * EXCEPT (ml_generate_text_result)
   FROM
     ML.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT('Extract the key words from the text below: ', review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens));

   O resultado é semelhante ao seguinte, com as colunas não geradas omitidas para maior clareza:

   +----------------------------------------+-------------------------+----------------------------+-----+
   | generated_text                         | ml_generate_text_status | prompt                     | ... |
   +----------------------------------------+-------------------------+----------------------------+-----+
   | {"parts":[{"text":"## Key words:\n\n*  |                         | Extract the key words from |     |
   | **Negative sentiment:** \"terribly     |                         | the text below: I had to   |     |
   | bad acting\", \"dumb story\", \"not    |                         | see this on the British    |     |
   | even a kid would enjoy this\",         |                         | Airways plane. It was      |     |
   | \"something to switch off\"\n*         |                         | terribly bad acting and    |     |
   | **Context:** \"British Airways plane\" |                         | a dumb story. Not even     |     |
   | \n* **Genre:** \"movie\" (implied)...  |                         | a kid would enjoy this...  |     |
   +----------------------------------------+-------------------------+----------------------------+-----+
   | {"parts":[{"text":"## Key words:\n\n*  |                         | Extract the key words from |     |
   | **Movie:** The Real Howard Spitz\n*    |                         | the text below: This is    |     |
   | **Genre:** Family movie\n*             |                         | a family movie that was    |     |
   | **Broadcast:** ITV station, 1.00 am\n* |                         | broadcast on my local      |     |
   | **Director:** Vadim Jean\n*            |                         | ITV station at 1.00 am a   |     |
   | **Main character:** Howard Spitz,      |                         | couple of nights ago.      |     |
   | a children's author who hates...       |                         | This might be a strange... |     |
   +----------------------------------------+-------------------------+----------------------------+-----+
   

   Os resultados incluem as seguintes colunas:

   • generated_text: o texto gerado.
   • ml_generate_text_status: o estado da resposta da API para a linha correspondente. Se a operação tiver sido bem-sucedida, este valor está vazio.
   • prompt: o comando usado para a análise de sensação geral.
   • Todas as colunas da tabela bigquery-public-data.imdb.reviews.

3. Opcional: em vez de analisar manualmente o JSON devolvido pela função, como fez no passo anterior, use o argumento flatten_json_output para devolver o texto gerado e os atributos de segurança em colunas separadas.

   No editor de consultas, execute a seguinte declaração:

   SELECT
     *
   FROM
     ML.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT('Extract the key words from the text below: ', review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens,
         TRUE AS flatten_json_output));

   O resultado é semelhante ao seguinte, com as colunas não geradas omitidas para maior clareza:

   +----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
   | ml_generate_text_llm_result            | ml_generate_text_rai_result                  | ml_generate_text_status | prompt                     | ... |
   +----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
   | ## Keywords:                           |                                              |                         | Extract the key words from |     |
   |                                        |                                              |                         | the text below: I had to   |     |
   | * **Negative sentiment:**              |                                              |                         | see this on the British    |     |
   | "terribly bad acting", "dumb           |                                              |                         | Airways plane. It was      |     |
   | story", "not even a kid would          |                                              |                         | terribly bad acting and    |     |
   | enjoy this", "switch off"              |                                              |                         | a dumb story. Not even     |     |
   | * **Context:** "British                |                                              |                         | a kid would enjoy this...  |     |
   +----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
   | ## Key words:                          |                                              |                         | Extract the key words from |     |
   |                                        |                                              |                         | the text below: This is    |     |
   | * **Movie:** The Real Howard Spitz     |                                              |                         | a family movie that was    |     |
   | * **Genre:** Family movie              |                                              |                         | broadcast on my local      |     |
   | * **Broadcast:** ITV, 1.00             |                                              |                         | ITV station at 1.00 am a   |     |
   | am                                     |                                              |                         | couple of nights ago.      |     |
   | - ...                                  |                                              |                         | This might be a strange... |     |
   +----------------------------------------+----------------------------------------------+-------------------------+----------------------------+-----+
   

   Os resultados incluem as seguintes colunas:

   • ml_generate_text_llm_result: o texto gerado.
   • ml_generate_text_rai_result: os atributos de segurança, juntamente com informações sobre se o conteúdo está bloqueado devido a uma das categorias de bloqueio. Para mais informações sobre os atributos de segurança, consulte o artigo Configure filtros de segurança.
   • ml_generate_text_status: o estado da resposta da API para a linha correspondente. Se a operação tiver sido bem-sucedida, este valor está vazio.
   • prompt: o comando usado para a extração de palavras-chave.
   • Todas as colunas da tabela bigquery-public-data.imdb.reviews.

Realize a análise de sensação geral

Faça uma análise de sentimento das críticas de filmes do IMDB usando o modelo remoto e a função ML.GENERATE_TEXT:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, execute a seguinte declaração para fazer a análise de sentimentos de cinco críticas de filmes:

   SELECT
     ml_generate_text_result['candidates'][0]['content'] AS generated_text,
     * EXCEPT (ml_generate_text_result)
   FROM
     ML.GENERATE_TEXT(
       MODEL `bqml_tutorial.gemini_model`,
       (
         SELECT
           CONCAT(
             'perform sentiment analysis on the following text, return one the following categories: positive, negative: ',
             review) AS prompt,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       ),
       STRUCT(
         0.2 AS temperature,
         100 AS max_output_tokens));

   O resultado é semelhante ao seguinte, com as colunas não geradas omitidas para maior clareza:

   +--------------------------------------------+-------------------------+----------------------------+-----+
   | generated_text                             | ml_generate_text_status | prompt                     | ... |
   +--------------------------------------------+-------------------------+----------------------------+-----+
   | {"parts":[{"text":"## Sentiment Analysis:  |                         | perform sentiment analysis |     |
   | Negative \n\nThis text expresses a         |                         | on the following text,     |     |
   | strongly negative sentiment towards the    |                         | return one the following   |     |
   | movie. Here's why:\n\n* **Negative         |                         | negative: I  had to see    |     |
   | like \"terribly,\" \"dumb,\" and           |                         | this on the British        |     |
   | \"not even\" to describe the acting...     |                         | Airways plane. It was...   |     |
   +--------------------------------------------+-------------------------+----------------------------+-----+
   | {"parts":[{"text":"## Sentiment Analysis:  |                         | perform sentiment analysis |     |
   | Negative \n\nThis review expresses a       |                         | on the following text,     |     |
   | predominantly negative sentiment towards   |                         | return one the following   |     |
   | the movie \"The Real Howard Spitz.\"       |                         | categories: positive,      |     |
   | Here's why:\n\n* **Criticism of the film's |                         | negative: This is a family |     |
   | premise:** The reviewer finds it strange   |                         | movie that was broadcast   |     |
   | that a film about a children's author...   |                         | on my local ITV station... |     |
   +--------------------------------------------+-------------------------+----------------------------+-----+
   

   Os resultados incluem as mesmas colunas documentadas para a função Extrair palavras-chave.

Limpar

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.