Gere dados estruturados com a função AI.GENERATE_TABLE

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais do Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: para enviar feedback ou pedir apoio técnico para esta funcionalidade, contacte [e-mail].

Este documento mostra como gerar dados estruturados através de um modelo do Gemini e, em seguida, formatar a resposta do modelo com um esquema SQL.

Para tal, conclua as seguintes tarefas:

• Criar um modelo remoto do BigQuery ML sobre qualquer um dos modelos Gemini geralmente disponíveis ou em pré-visualização.
• Usando o modelo com a função AI.GENERATE_TABLE para gerar dados estruturados com base em dados de tabelas padrão.

Funções necessárias

Para criar um modelo remoto e usar a função AI.GENERATE_TABLE, precisa das seguintes funções de gestão de identidade e de acesso (IAM):

• Criar e usar conjuntos de dados, tabelas e modelos do BigQuery: Editor de dados do BigQuery (roles/bigquery.dataEditor) no seu projeto.

• Criar, delegar e usar associações do BigQuery: Administrador de associações do BigQuery (roles/bigquery.connectionsAdmin) no seu projeto.

  Se não tiver uma associação predefinida configurada, pode criar e definir uma como parte da execução da declaração CREATE MODEL. Para tal, tem de ter a função de administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações, consulte o artigo Configure a ligação predefinida.

• Conceda autorizações à conta de serviço da ligação: administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto que contém o ponto final do Vertex AI. Este é o projeto atual para modelos remotos que cria especificando o nome do modelo como um ponto final. Este é o projeto identificado no URL para modelos remotos que cria especificando um URL como ponto final.

• Criar tarefas do BigQuery: utilizador de tarefas do BigQuery (roles/bigquery.jobUser) no seu projeto.

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 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
• Consultar dados de tabelas: bigquery.tables.getData

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

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 os seus recursos:

Consola

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

   Aceda ao BigQuery

2. No painel esquerdo, clique em Explorador:

   

   Se não vir o painel do lado esquerdo, clique em Expandir painel do lado esquerdo para o abrir.

3. No painel Explorador, clique no nome do projeto.

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

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

   1. Para ID do conjunto de dados, escreva um nome para o conjunto de dados.

   2. Para Tipo de localização, selecione Região ou Várias regiões.

      • Se selecionou Região, selecione uma localização na lista Região.
      • Se selecionou Multirregional, selecione EUA ou Europa na lista Multirregional.

   3. Clique em Criar conjunto de dados.

bq

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

   bq --location=LOCATION mk -d DATASET_ID

   Substitua o seguinte:

   • LOCATION: a localização do conjunto de dados.
   • DATASET_ID é o ID do conjunto de dados que está a criar.

2. Confirme que o conjunto de dados foi criado:

   bq ls

Crie uma associação

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.

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

Selecione uma das seguintes opções:

Consola

1. Aceda à página do BigQuery.

   Aceda ao BigQuery

2. No painel esquerdo, clique em Explorador:

   

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

3. No painel Explorador, expanda o nome do projeto e, de seguida, clique em Ligações.

4. Na página Associações, clique em Criar associação.

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

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

7. Em Tipo de localização, selecione uma localização para a sua ligação. A ligação deve estar colocada com os seus outros recursos, como conjuntos de dados.

8. Clique em Criar associação.

9. Clique em Aceder à associação.

10. No painel Informações da ligaçã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 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 correções à configuração conforme necessário.

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 do princípio de que as APIs necessárias estão ativadas no seu Google Cloud projeto.

Conceda acesso à conta de serviço

Conceda à conta de serviço da ligação a função de utilizador do Vertex AI.

Se planeia especificar o ponto final como um URL quando 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 esta função no mesmo projeto que especificar no URL.

Se planear especificar o ponto final através do nome do modelo quando criar o modelo remoto, por exemplo, endpoint = 'gemini-2.5-flash', conceda esta função no mesmo projeto onde planeia criar o modelo remoto.

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:

Consola

1. Aceda à página IAM e administrador.

   Aceda a IAM e administração

2. Clique em Adicionar.

   É apresentada a caixa de diálogo Adicionar responsáveis.

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

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

5. Clique em Guardar.

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 o seguinte:

• PROJECT_NUMBER: o número do seu projeto
• MEMBER: o ID da conta de serviço que copiou anteriormente

Crie um modelo remoto do BigQuery ML

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

   Aceda ao 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 o seguinte:

   • PROJECT_ID: o ID do seu projeto
   • DATASET_ID: o ID do conjunto de dados que vai conter o modelo. Este conjunto de dados tem de estar na mesma localização que a ligação que está a usar
   • MODEL_NAME: o nome do modelo
   • REGION: a região usada pela associação
   • CONNECTION_ID: o ID da sua ligação ao BigQuery

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

   • ENDPOINT: o nome do modelo Gemini a usar. Para os modelos do Gemini suportados, pode especificar o ponto final global para melhorar a disponibilidade. Para mais informações, consulte ENDPOINT.

Gere dados estruturados

Gere dados estruturados através da função AI.GENERATE_TABLE com um modelo remoto e usando dados de comandos de uma coluna de 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 o seguinte:

• 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. Esta tabela tem de ter uma coluna com o nome prompt ou pode 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 em si pode ser extraído de uma coluna ou pode especificá-lo como um valor de estrutura 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. Este valor tem de estar no intervalo [1,8192]. Especifique um valor inferior para respostas mais curtas e um valor superior para respostas mais longas. A predefinição é 128.
• TEMPERATURE: um valor FLOAT64 no intervalo [0.0,2.0] que controla o grau de aleatoriedade na seleção de tokens. A predefinição é 1.0.

  Os valores mais baixos para temperature são adequados para comandos que requerem uma resposta mais determinística e menos aberta ou criativa, enquanto os valores mais elevados para temperature podem gerar resultados mais diversificados ou criativos. Um valor de 0 para temperature é determinístico, o que significa que a resposta com a probabilidade mais elevada é sempre selecionada.

• TOP_P: um valor FLOAT64 no intervalo [0.0,1.0] ajuda a determinar a probabilidade dos tokens selecionados. Especifique um valor inferior para respostas menos aleatórias e um valor superior para respostas mais aleatórias. A predefinição é 0.95.
• STOP_SEQUENCES: um valor ARRAY<STRING> que remove as strings especificadas se estiverem incluídas nas respostas do modelo. As strings de carateres são correspondidas exatamente, incluindo a utilização de letras maiúsculas. A predefinição é uma matriz vazia.
• SAFETY_SETTINGS: um valor ARRAY<STRUCT<STRING AS category, STRING AS threshold>> que configura os limites de segurança do conteúdo para filtrar as respostas. O primeiro elemento na struct especifica uma categoria de danos, e o segundo elemento na struct especifica um limite de bloqueio correspondente. O modelo filtra o conteúdo que viola estas definições. Só pode especificar cada categoria uma vez. Por exemplo, não pode 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). Se não existir uma definição de segurança para uma determinada categoria, é usada a definição de segurança BLOCK_MEDIUM_AND_ABOVE.

  As categorias suportadas são as seguintes:

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  Os limites suportados são os seguintes:

  • BLOCK_NONE (Restrito)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (Predefinição)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Para mais informações, consulte as 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 tem de ser uma definição do esquema SQL, semelhante à usada na declaração CREATE TABLE. Os seguintes tipos de dados são suportados:
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Quando usa o argumento output_schema para gerar dados estruturados com base em comandos de uma tabela, é importante compreender os dados dos comandos para especificar um esquema adequado.

  Por exemplo, suponhamos que está a analisar conteúdo de críticas de filmes a partir de uma tabela que tem os seguintes campos:

  • movie_id
  • crítica
  • comando

  Em seguida, pode criar texto de comando executando uma consulta semelhante à seguinte:

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

  Também pode especificar um valor output_schema semelhante a "keywords ARRAY<STRING>, sentiment STRING" AS output_schema.

Exemplos

O exemplo seguinte mostra um pedido que extrai dados de comandos 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 seguinte mostra um pedido que extrai dados de comandos 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));