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

Este documento mostra como gerar dados estruturados usando um modelo Gemini Pro 1.5, Gemini Flash 1.5 ou Gemini Flash 2.0 e, em seguida, formatar a resposta do modelo usando um esquema SQL.

Para isso, você precisa concluir as seguintes tarefas:

• Criar um modelo remoto do BigQuery ML que represente um modelo hospedado da Vertex AI Gemini 1.5 ou 2.0.
• Usar o modelo com a função AI.GENERATE_TABLE para gerar dados estruturados com base em dados de tabelas padrão.

Permissões necessárias

• Para criar uma conexão, você precisa da associação no seguinte papel do Identity and Access Management (IAM):

  • roles/bigquery.connectionAdmin

• Para conceder permissões à conta de serviço da conexão, você precisa da seguinte permissão:

  • resourcemanager.projects.setIamPolicy

• Para criar o modelo usando o BigQuery ML, você precisa das seguintes permissões do IAM:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• Para executar a inferência, você precisa das seguintes permissões:

  • bigquery.tables.getData na tabela
  • bigquery.models.getData no modelo
  • bigquery.jobs.create

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 uma conexão

Crie uma Conexão de recursos do Cloud e tenha acesso à conta de serviço da conexão.

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-1.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-1.5-flash', conceda esse papel no mesmo projeto em que planeja criar o modelo remoto.

Conceder o papel em um projeto diferente resulta no erro bqcx-1234567890-xxxx@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 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 `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. Os seguintes modelos são compatíveis:
     • gemini-2.0-flash-001
     • gemini-1.5-flash-001
     • gemini-1.5-flash-002
     • gemini-1.5-pro-001
     • gemini-1.5-pro-002
     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 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:

• 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 utilizar 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 nome de string e 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 configuração de seguranç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 aceitos:
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Para modelos do Gemini 1.5, especifique um tipo de dados FLOAT64 apenas se você tiver certeza de que o valor de retorno não será um número arredondado. Às vezes, esses modelos podem retornar valores INT64 em vez de valores FLOAT64 para números arredondados, por exemplo, 2 em vez de 2.0. Isso pode causar um erro de análise na consulta.

  Ao usar o argumento output_schema para gerar dados estruturados com base em instruções de uma tabela, é importante entender os dados da instrução para especificar um esquema adequado.

  Por exemplo, digamos que você esteja analisando o conteúdo da crítica de um filme em uma tabela que tem os seguintes campos:

  • movie_id
  • review
  • prompt

  Em seguida, você pode criar 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;

  E 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 recebe dados 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 recebe dados 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));