Gerar dados estruturados usando a função AI.GENERATE_TABLE

Pré-lançamento

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Observação :para enviar feedback ou solicitar suporte sobre esse recurso, entre em contato com [e-mail].

Este documento mostra como gerar dados estruturados usando um modelo do Gemini e formatar a resposta do modelo usando um esquema SQL.

Para fazer isso, conclua as seguintes tarefas:

• Criar um modelo remoto do BigQuery ML usando qualquer um dos modelos do Gemini disponíveis de maneira geral ou em prévia.
• Usar o modelo com a função AI.GENERATE_TABLE para gerar dados estruturados com base em dados de tabelas padrão.

Funções exigidas

Para criar um modelo remoto e usar a função AI.GENERATE_TABLE, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Criar e usar conjuntos de dados, tabelas e modelos do BigQuery: função de 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.

  Se você não tiver uma conexão padrão configurada, crie e defina uma como parte da execução da instrução CREATE MODEL. Para isso, você precisa ter a função de administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações, consulte Configurar a conexão padrão.

• 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 Vertex AI. Este é o projeto atual para modelos remotos que você cria especificando o nome do modelo como um endpoint. Esse é o projeto identificado no URL para modelos remotos que você cria especificando um URL como endpoint.

• Criar jobs do BigQuery: usuário de jobs do BigQuery (roles/bigquery.jobUser) no seu projeto.

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.*
• Defina as permissõ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
• Consultar dados da tabela: bigquery.tables.getData

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

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 role (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 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:

   

   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

Crie uma Conexão de recursos do Cloud para o modelo remoto usar 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.

Pule esta etapa se você tiver uma conexão padrão configurada ou a função de administrador do BigQuery.

Selecione uma das seguintes opções:

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se você não vir o painel à esquerda, clique em Expandir painel esquerdo para abrir o painel.

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 usar em uma etapa posterior.

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á assim:

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

Terraform

Use o recurso google_bigquery_connection.

Observação: para criar objetos do BigQuery usando o Terraform, é necessário ativar a API Cloud Resource Manager.

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 projeto Google Cloud , 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 interface para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto Google Cloud .

Conceder acesso à conta de serviço

Conceda à conta de serviço da conexão a função de usuário da Vertex AI.

Se você planeja especificar o endpoint como um URL ao criar o modelo remoto, por exemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.5-flash', conceda essa função no mesmo projeto especificado no URL.

Se você planeja especificar o endpoint usando o nome do modelo ao criar o modelo remoto, por exemplo, endpoint = 'gemini-2.5-flash', conceda essa função no mesmo projeto em que planeja criar o modelo remoto.

Conceder a função em um projeto diferente resulta no erro [e-mail] does not have the permission to access resource.

Para conceder o papel, siga estas etapas:

Console

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, selecione Usuário da Vertex AI.

5. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding.

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Substitua:

• PROJECT_NUMBER: o ID do seu projeto
• MEMBER: o ID da conta de serviço que você copiou anteriormente

Criar um modelo remoto do BigQuery ML

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

   Acessar o BigQuery

2. Usando o editor de SQL, crie um modelo remoto:

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Substitua:

   • PROJECT_ID: ID do projeto;
   • DATASET_ID: o ID do conjunto de dados para conter o modelo. Esse conjunto de dados precisa estar no mesmo local que a conexão que você está usando.
   • MODEL_NAME: o nome do modelo
   • REGION: a região usada pela conexão
   • CONNECTION_ID: o ID da conexão do BigQuery

     Quando você visualiza os detalhes da conexão no console do Google Cloud , esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo, projects/myproject/locations/connection_location/connections/myconnection

   • ENDPOINT: o nome do modelo do Gemini a ser usado. Para modelos do Gemini compatíveis, é possível especificar o endpoint global para melhorar a disponibilidade. Para mais informações, consulte ENDPOINT.

Gerar dados estruturados

Gere dados estruturados usando a função AI.GENERATE_TABLE com um modelo remoto e usando dados de comando de uma coluna da tabela:

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

Substitua:

• PROJECT_ID: o ID do projeto.
• DATASET_ID: o ID do conjunto de dados que contém o modelo.
• MODEL_NAME: o nome do modelo
• TABLE_NAME: o nome da tabela que contém o comando. Essa tabela precisa ter uma coluna chamada prompt ou é possível usar um alias para usar uma coluna com um nome diferente.
• PROMPT_QUERY: a consulta GoogleSQL que gera os dados do comando. O valor do comando pode ser extraído de uma coluna ou especificado como um valor de struct com um número arbitrário de subcampos de string e nome da coluna. Por exemplo, SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt.
• TOKENS: um valor INT64 que define o número máximo de tokens que podem ser gerados na resposta. Esse valor precisa estar no intervalo [1,8192]. Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas mais longas. O padrão é 128.
• TEMPERATURE: um valor FLOAT64 no intervalo [0.0,2.0] que controla o grau de aleatoriedade na seleção de token. O padrão é 1.0.

  Valores mais baixos para temperature são bons para comandos que exigem uma resposta mais determinista e menos aberta ou criativa, enquanto valores mais altos para temperature podem gerar resultados mais diversos ou criativos. Um valor de 0 para temperature é determinista, o que significa que a resposta de maior probabilidade é sempre selecionada.

• TOP_P: um valor FLOAT64 no intervalo [0.0,1.0] ajuda a determinar a probabilidade dos tokens selecionados. Especifique um valor mais baixo para respostas menos aleatórias e um valor mais alto para respostas mais aleatórias. O padrão é 0.95.
• STOP_SEQUENCES: um valor ARRAY<STRING> que remove as strings especificadas se elas estiverem incluídas nas respostas do modelo. As strings têm correspondência exata, incluindo as letras maiúsculas. O padrão é uma matriz vazia.
• SAFETY_SETTINGS: um valor de ARRAY<STRUCT<STRING AS category, STRING AS threshold>> que configura limites de segurança de conteúdo para filtrar respostas. O primeiro elemento no struct especifica uma categoria de dano, e o segundo especifica um limite de bloqueio correspondente. O modelo filtra o conteúdo que viola essas configurações. Só é possível especificar cada categoria uma vez. Por exemplo, não é possível especificar STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) e STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold) ao mesmo tempo. Se não houver uma configuração de segurança para uma determinada categoria, a BLOCK_MEDIUM_AND_ABOVE será usada.

  As categorias compatíveis são as seguintes:

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  Os limites aceitos são os seguintes:

  • BLOCK_NONE (Restrito)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (padrão)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Para mais informações, consulte Categorias de danos e Como configurar filtros de conteúdo.

• OUTPUT_SCHEMA: um valor STRING que especifica o formato da resposta do modelo. O valor output_schema precisa ser uma definição de esquema SQL, semelhante à usada na instrução CREATE TABLE. Os seguintes tipos de dados são compatíveis:
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Ao usar o argumento output_schema para gerar dados estruturados com base em comandos de uma tabela, é importante entender os dados do comando para especificar um esquema adequado.

  Por exemplo, digamos que você esteja analisando o conteúdo de uma tabela com os seguintes campos:

  • movie_id
  • review
  • prompt

  Em seguida, crie um texto de comando executando uma consulta semelhante a esta:

  UPDATE mydataset.movie_review
  SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
  WHERE review IS NOT NULL;

  Você pode especificar um valor output_schema semelhante a "keywords ARRAY<STRING>, sentiment STRING" AS output_schema.

Exemplos

O exemplo a seguir mostra uma solicitação que usa dados de comando de uma tabela e fornece um esquema SQL para formatar a resposta do modelo:

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

O exemplo a seguir mostra uma solicitação que usa dados de comando de uma consulta e fornece um esquema SQL para formatar a resposta do modelo:

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));