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

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.
• Usando 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: 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:

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.

   Go to project selector

2. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para conter seus recursos:

Crie uma conexão

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

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.

Selecione uma das seguintes opções:

# 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 {}
}

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 bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para conceder o papel, siga estas etapas:

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

Criar um modelo remoto do BigQuery ML

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

  Para modelos do Gemini 1.5, especifique um tipo de dados FLOAT64 somente se tiver certeza de que o valor de retorno não será um número inteiro. Às vezes, esses modelos retornam valores INT64 em vez de FLOAT64 para números redondos, por exemplo, 2 em vez de 2.0, o que pode causar um erro de análise na consulta.

  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 crítica de filme em 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));