Ajuste um modelo com os seus dados

Este documento mostra como criar um modelo remoto do BigQuery ML que faz referência a um modelo do Vertex AI e, em seguida, configurar o modelo para realizar a otimização supervisionada. O modelo do Vertex AI tem de ser um dos seguintes:

  • gemini-2.5-pro
  • gemini-2.5-flash-lite
  • gemini-2.0-flash-001
  • gemini-2.0-flash-lite-001

Depois de criar o modelo remoto, usa a função ML.EVALUATE para avaliar o modelo e confirmar que o desempenho do modelo se adequa ao seu caso de utilização. Em seguida, pode usar o modelo em conjunto com a função AI.GENERATE_TEXT para analisar texto numa tabela do BigQuery.

Para mais informações, consulte o artigo Ajuste supervisionado do modelo da API Gemini do Vertex AI.

Funções necessárias

Para criar e avaliar um modelo otimizado, precisa das seguintes funções de gestão de identidade e 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

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.

    Go to project selector

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

  3. Enable the BigQuery, BigQuery Connection,Vertex AI, and Compute Engine 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:

    Botão realçado para o painel do 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 associação de recursos na nuvem 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.

Selecione uma das seguintes opções:

Consola

  1. Aceda à página do BigQuery.

    Aceda ao BigQuery

  2. No painel esquerdo, clique em Explorador:

    Botão realçado para o painel do 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": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Use o recurso google_bigquery_connection.

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.

Conceda acesso à conta de serviço da associação

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

Se planear 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.0-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.0-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 bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com 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 Conceder acesso.

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

  4. Clique em Selecionar uma função.

  5. Em Filtrar, escreva Vertex AI Service Agent e, de seguida, selecione essa função.

  6. 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.serviceAgent' --condition=None

Substitua o seguinte:

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

A conta de serviço associada à sua ligação é uma instância do agente do serviço de delegação da ligação do BigQuery, por isso, não há problema em atribuir-lhe uma função de agente de serviço.

Crie um modelo com ajuste supervisionado

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

    Aceda ao BigQuery

  2. No editor de consultas, execute a seguinte consulta para criar 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',
  MAX_ITERATIONS = MAX_ITERATIONS,
  LEARNING_RATE_MULTIPLIER = LEARNING_RATE_MULTIPLIER,
  DATA_SPLIT_METHOD = 'DATA_SPLIT_METHOD',
  DATA_SPLIT_EVAL_FRACTION = DATA_SPLIT_EVAL_FRACTION,
  DATA_SPLIT_COL = 'DATA_SPLIT_COL',
  EVALUATION_TASK = 'EVALUATION_TASK',
  PROMPT_COL = 'INPUT_PROMPT_COL',
  INPUT_LABEL_COLS = INPUT_LABEL_COLS)
AS SELECT PROMPT_COLUMN, LABEL_COLUMN
FROM `TABLE_PROJECT_ID.TABLE_DATASET.TABLE_NAME`;

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto no qual criar o modelo.
    • DATASET_ID: o ID do conjunto de dados que vai conter o modelo. Este conjunto de dados tem de estar numa região do Vertex AI compatível.
    • MODEL_NAME: o nome do modelo.
    • REGION: a região usada pela ligação.
    • CONNECTION_ID: o ID da sua ligação ao BigQuery. Esta associação tem de estar na mesma localização que o conjunto de dados que está a usar.

      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 apresentado em ID da associação, por exemplo, projects/myproject/locations/connection_location/connections/myconnection.

    • ENDPOINT: um valor STRING que especifica o nome do modelo a usar.
    • MAX_ITERATIONS: um valor INT64 que especifica o número de passos a executar para a otimização supervisionada. O valor MAX_ITERATIONS tem de estar entre 1 e ∞.

      Os modelos Gemini são preparados com épocas em vez de passos, pelo que o BigQuery ML converte o valor MAX_ITERATIONS em épocas. O valor predefinido para MAX_ITERATIONS é o número de linhas nos dados de entrada, o que equivale a uma época. Para usar várias épocas, especifique um múltiplo do número de linhas nos dados de preparação. Por exemplo, se tiver 100 linhas de dados de entrada e quiser usar duas épocas, especifique 200 para o valor do argumento. Se fornecer um valor que não seja um múltiplo do número de linhas nos dados de entrada, o BigQuery ML arredonda para o número de épocas mais próximo. Por exemplo, se tiver 100 linhas de dados de entrada e especificar 101 para o valor MAX_ITERATIONS, a preparação é realizada com duas épocas.

      Para mais informações sobre os parâmetros usados para otimizar os modelos Gemini, consulte o artigo Crie uma tarefa de otimização.

    • DATA_SPLIT_METHOD: um valor STRING que especifica o método usado para dividir os dados de entrada em conjuntos de preparação e avaliação. As opções válidas são as seguintes:
      • AUTO_SPLIT: o BigQuery ML divide automaticamente os dados. A forma como os dados são divididos varia consoante o número de linhas na tabela de entrada. Este é o valor predefinido.
      • RANDOM: os dados são aleatorizados antes de serem divididos em conjuntos. Para personalizar a divisão de dados, pode usar esta opção com a opção DATA_SPLIT_EVAL_FRACTION.
      • CUSTOM: os dados são divididos através da coluna indicada na opção DATA_SPLIT_COL. O valor DATA_SPLIT_COL tem de ser o nome de uma coluna do tipo BOOL. As linhas com um valor de TRUE ou NULL são usadas como dados de avaliação e as linhas com um valor de FALSE são usadas como dados de preparação.
      • SEQ: divida os dados usando a coluna fornecida na opção DATA_SPLIT_COL. O valor DATA_SPLIT_COL tem de ser o nome de uma coluna de um dos seguintes tipos:
        • NUMERIC
        • BIGNUMERIC
        • STRING
        • TIMESTAMP

        Os dados são ordenados do menor para o maior com base na coluna especificada.

        As primeiras n linhas são usadas como dados de avaliação, em que n é o valor especificado para DATA_SPLIT_EVAL_FRACTION. As linhas restantes são usadas como dados de preparação.

      • NO_SPLIT: sem divisão de dados; todos os dados de entrada são usados como dados de preparação.

      Para mais informações sobre estas opções de divisão de dados, consulte DATA_SPLIT_METHOD.

    • DATA_SPLIT_EVAL_FRACTION: um valor FLOAT64 que especifica a fração dos dados a usar como dados de avaliação quando faz a otimização supervisionada. Tem de ser um valor no intervalo [0, 1.0]. O valor predefinido é 0.2.

      Use esta opção quando especificar RANDOM ou SEQ como o valor da opção DATA_SPLIT_METHOD. Para personalizar a divisão de dados, pode usar a opção DATA_SPLIT_METHOD com a opção DATA_SPLIT_EVAL_FRACTION.

    • DATA_SPLIT_COL: um valor STRING que especifica o nome da coluna a usar para ordenar os dados de entrada no conjunto de preparação ou avaliação. Use quando especificar CUSTOM ou SEQ como o valor da opção DATA_SPLIT_METHOD.
    • EVALUATION_TASK: um valor STRING que especifica o tipo de tarefa para a qual quer otimizar o modelo. As opções válidas são:
      • TEXT_GENERATION
      • CLASSIFICATION
      • SUMMARIZATION
      • QUESTION_ANSWERING
      • UNSPECIFIED

      O valor predefinido é UNSPECIFIED.

    • INPUT_PROMPT_COL: um valor STRING que contém o nome da coluna de comandos na tabela de dados de preparação a usar quando realizar a otimização supervisionada. O valor predefinido é prompt.
    • INPUT_LABEL_COLS: um valor ARRAY<<STRING> que contém o nome da coluna de etiqueta na tabela de dados de preparação para usar no ajuste supervisionado. Só pode especificar um elemento na matriz. O valor predefinido é uma matriz vazia. Isto faz com que label seja o valor predefinido do argumento LABEL_COLUMN.
    • PROMPT_COLUMN: a coluna na tabela de dados de preparação que contém o comando para avaliar o conteúdo na coluna LABEL_COLUMN. Esta coluna tem de ser do tipo STRING ou ser convertida para STRING. Se especificar um valor para a opção INPUT_PROMPT_COL, tem de especificar o mesmo valor para PROMPT_COLUMN. Caso contrário, este valor tem de ser prompt. Se a sua tabela não tiver uma coluna prompt, use um alias para especificar uma coluna da tabela existente. Por exemplo, AS SELECT hint AS prompt, label FROM mydataset.mytable.
    • LABEL_COLUMN: a coluna na tabela de dados de preparação que contém os exemplos para preparar o modelo. Esta coluna tem de ser do tipo STRING ou ser convertida para STRING. Se especificar um valor para a opção INPUT_LABEL_COLS, tem de especificar o mesmo valor para LABEL_COLUMN. Caso contrário, este valor tem de ser label. Se a sua tabela não tiver uma coluna label, use um alias para especificar uma coluna da tabela existente. Por exemplo, AS SELECT prompt, feature AS label FROM mydataset.mytable.
    • TABLE_PROJECT_ID: o ID do projeto do projeto que contém a tabela de dados de preparação.
    • TABLE_DATASET: o nome do conjunto de dados que contém a tabela de dados de preparação.
    • TABLE_NAME: o nome da tabela que contém os dados a usar para preparar o modelo.

Avalie o modelo otimizado

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

    Aceda ao BigQuery

  2. No editor de consultas, execute a seguinte consulta para avaliar o modelo otimizado:

    SELECT
*
FROM
ML.EVALUATE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE `TABLE_PROJECT_ID.TABLE_DATASET.TABLE_NAME`,
  STRUCT('TASK_TYPE' AS task_type, TOKENS AS max_output_tokens,
    TEMPERATURE AS temperature, TOP_K AS top_k,
    TOP_P AS top_p));

    Substitua o seguinte:

    • PROJECT_ID: o ID do projeto que contém o modelo.
    • DATASET_ID: o ID do conjunto de dados que contém o modelo.
    • MODEL_NAME: o nome do modelo.
    • TABLE_PROJECT_ID: o ID do projeto do projeto que contém a tabela de dados de avaliação.
    • TABLE_DATASET: o nome do conjunto de dados que contém a tabela de dados de avaliação.
    • TABLE_NAME: o nome da tabela que contém os dados de avaliação.

      A tabela tem de ter uma coluna cujo nome corresponda ao nome da coluna de comando fornecido durante a preparação do modelo. Pode fornecer este valor através da opção prompt_col durante a preparação do modelo. Se prompt_col não for especificado, é usada a coluna denominada prompt nos dados de preparação. É devolvido um erro se não existir uma coluna com o nome prompt.

      A tabela tem de ter uma coluna cujo nome corresponda ao nome da coluna de etiqueta fornecido durante a preparação do modelo. Pode fornecer este valor através da opção input_label_cols durante a preparação do modelo. Se input_label_cols não for especificado, é usada a coluna denominada label nos dados de preparação. É devolvido um erro se não existir uma coluna com o nome label.

    • TASK_TYPE: um valor STRING que especifica o tipo de tarefa para a qual quer avaliar o modelo. As opções válidas são:
      • TEXT_GENERATION
      • CLASSIFICATION
      • SUMMARIZATION
      • QUESTION_ANSWERING
      • UNSPECIFIED
    • 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,1024]. 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,1.0] que controla o grau de aleatoriedade na seleção de tokens. A predefinição é 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_K: um valor INT64 no intervalo [1,40] que determina o conjunto inicial de tokens que o modelo considera para seleção. Especifique um valor inferior para respostas menos aleatórias e um valor superior para respostas mais aleatórias. A predefinição é 40.
    • TOP_P: um valor FLOAT64 no intervalo [0.0,1.0] ajuda a determinar que tokens do conjunto determinado por TOP_K são selecionados. Especifique um valor inferior para respostas menos aleatórias e um valor superior para respostas mais aleatórias. A predefinição é 0.95.

Gerar texto

Gere texto com a função AI.GENERATE_TEXT:

Coluna de comandos

Gere texto usando uma coluna de tabela para fornecer o comando.

SELECT *
FROM AI.GENERATE_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p,
  STOP_SEQUENCES AS stop_sequences)
);

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 cujo nome corresponda ao nome da coluna de caraterísticas no modelo otimizado. O nome da coluna de caraterísticas no modelo pode ser definido através da opção PROMPT_COL ao criar o modelo. Caso contrário, o nome da coluna de caraterísticas no modelo é prompt por predefinição ou pode usar um alias para usar uma coluna com um nome diferente.
  • 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,1.0] que controla o grau de aleatoriedade na seleção de tokens. A predefinição é 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 são correspondidas exatamente, incluindo a utilização de letras maiúsculas. A predefinição é uma matriz vazia.
  • GROUND_WITH_GOOGLE_SEARCH: um valor BOOL que determina se o modelo da Vertex AI usa a fundamentação com a Pesquisa Google ao gerar respostas. A fundamentação permite que o modelo use informações adicionais da Internet ao gerar uma resposta, de forma a tornar as respostas do modelo mais específicas e factuais. Quando este campo está definido como True, é incluída uma coluna grounding_result adicional nos resultados, que indica as fontes que o modelo usou para recolher informações adicionais. A predefinição é FALSE.
  • 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 a definição de categoria de segurança e limite de bloqueio.

  • REQUEST_TYPE: um valor STRING que especifica o tipo de pedido de inferência a enviar para o modelo Gemini. O tipo de pedido determina a quota que o pedido usa. Os valores válidos são os seguintes:
    • DEDICATED: a função AI.GENERATE_TEXT usa apenas a quota de débito aprovisionado. A função AI.GENERATE_TEXT devolve o erro Provisioned throughput is not purchased or is not active se a quota de débito processado aprovisionado não estiver disponível.
    • SHARED: a função AI.GENERATE_TEXT só usa quota partilhada dinâmica (DSQ), mesmo que tenha comprado quota de débito processado.
    • UNSPECIFIED: a função AI.GENERATE_TEXT usa a quota da seguinte forma:
      • Se não tiver comprado a quota de débito processado, a função AI.GENERATE_TEXT usa a quota de DSQ.
      • Se comprou uma quota de débito processado aprovisionado, a função AI.GENERATE_TEXT usa primeiro a quota de débito processado aprovisionado. Se os pedidos excederem a quota de débito processado, o tráfego de overflow usa a quota de DSQ.

    O valor predefinido é UNSPECIFIED.

    Para mais informações, consulte o artigo Use o débito aprovisionado da Vertex AI.

  • MODEL_PARAMS: um literal de string formatado em JSON que fornece parâmetros ao modelo. O valor tem de estar em conformidade com o formato do generateContent corpo do pedido. Pode fornecer um valor para qualquer campo no corpo do pedido, exceto para o campo contents[]. Se definir este campo, também não pode especificar parâmetros do modelo no argumento struct de nível superior para a função AI.GENERATE_TEXT. Tem de especificar todos os parâmetros do modelo no campo MODEL_PARAMS ou omitir este campo e especificar cada parâmetro separadamente.

O exemplo seguinte mostra um pedido com estas características:

  • Usa a coluna prompt da tabela prompts para o comando.
  • Devolve uma resposta curta e moderadamente provável.
  • Devolve o texto gerado e os atributos de segurança em colunas separadas.
SELECT *
FROM
  AI.GENERATE_TEXT(
    MODEL `mydataset.mymodel`,
    TABLE mydataset.prompts,
    STRUCT(
      0.4 AS temperature, 100 AS max_output_tokens, 0.5 AS top_p));

Consulta de comando

Gere texto através de uma consulta para fornecer o comando.

SELECT *
FROM AI.GENERATE_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (PROMPT_QUERY),
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p,
  STOP_SEQUENCES AS stop_sequences)
);

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.
  • PROMPT_QUERY: uma consulta que fornece os dados do comando.
  • 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,1.0] que controla o grau de aleatoriedade na seleção de tokens. A predefinição é 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 são correspondidas exatamente, incluindo a utilização de letras maiúsculas. A predefinição é uma matriz vazia.
  • GROUND_WITH_GOOGLE_SEARCH: um valor BOOL que determina se o modelo da Vertex AI usa a fundamentação com a Pesquisa Google ao gerar respostas. A fundamentação permite que o modelo use informações adicionais da Internet ao gerar uma resposta, de forma a tornar as respostas do modelo mais específicas e factuais. Quando este campo está definido como True, é incluída uma coluna grounding_result adicional nos resultados, que indica as fontes que o modelo usou para recolher informações adicionais. A predefinição é FALSE.
  • 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 a definição de categoria de segurança e limite de bloqueio.

  • REQUEST_TYPE: um valor STRING que especifica o tipo de pedido de inferência a enviar para o modelo Gemini. O tipo de pedido determina a quota que o pedido usa. Os valores válidos são os seguintes:
    • DEDICATED: a função AI.GENERATE_TEXT usa apenas a quota de débito aprovisionado. A função AI.GENERATE_TEXT devolve o erro Provisioned throughput is not purchased or is not active se a quota de débito processado aprovisionado não estiver disponível.
    • SHARED: a função AI.GENERATE_TEXT só usa quota partilhada dinâmica (DSQ), mesmo que tenha comprado quota de débito processado.
    • UNSPECIFIED: a função AI.GENERATE_TEXT usa a quota da seguinte forma:
      • Se não tiver comprado a quota de débito processado, a função AI.GENERATE_TEXT usa a quota de DSQ.
      • Se comprou uma quota de débito processado aprovisionado, a função AI.GENERATE_TEXT usa primeiro a quota de débito processado aprovisionado. Se os pedidos excederem a quota de débito processado, o tráfego de overflow usa a quota de DSQ.

    O valor predefinido é UNSPECIFIED.

    Para mais informações, consulte o artigo Use o débito aprovisionado da Vertex AI.

  • MODEL_PARAMS: um literal de string formatado em JSON que fornece parâmetros ao modelo. O valor tem de estar em conformidade com o formato do generateContent corpo do pedido. Pode fornecer um valor para qualquer campo no corpo do pedido, exceto para o campo contents[]. Se definir este campo, também não pode especificar parâmetros do modelo no argumento struct de nível superior para a função AI.GENERATE_TEXT. Tem de especificar todos os parâmetros do modelo no campo MODEL_PARAMS ou omitir este campo e especificar cada parâmetro separadamente.

Exemplo 1

O exemplo seguinte mostra um pedido com estas características:

  • Pede um resumo do texto na coluna body da tabela articles.
  • Devolve uma resposta moderadamente longa e mais provável.
  • Devolve o texto gerado e os atributos de segurança em colunas separadas.
SELECT *
FROM
  AI.GENERATE_TEXT(
    MODEL `mydataset.mymodel`,
    (
      SELECT CONCAT('Summarize this text', body) AS prompt
      FROM mydataset.articles
    ),
    STRUCT(
      0.2 AS temperature, 650 AS max_output_tokens, 0.2 AS top_p));

Exemplo 2

O exemplo seguinte mostra um pedido com estas características:

  • Usa uma consulta para criar os dados de comando concatenando strings que fornecem prefixos de comando com colunas de tabelas.
  • Devolve uma resposta curta e moderadamente provável.
  • Não devolve o texto gerado e os atributos de segurança em colunas separadas.
SELECT *
FROM
  AI.GENERATE_TEXT(
    MODEL `mydataset.mytuned_model`,
    (
      SELECT CONCAT(question, 'Text:', description, 'Category') AS prompt
      FROM mydataset.input_table
    ),
    STRUCT(
      0.4 AS temperature, 100 AS max_output_tokens, 0.5 AS top_p));