O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Visão geral da IA generativa

Este documento descreve as funções de inteligência artificial (IA) generativa com suporte no BigQuery. Essas funções aceitam entradas de linguagem natural e usam modelos pré-treinados da Gemini Enterprise Agent Platform e modelos integrados do BigQuery.

O BigQuery oferece várias funções de IA para ajudar em tarefas como as seguintes:

Gerar conteúdo criativo.
Analisar, detectar sentimentos e responder a perguntas sobre texto ou dados não estruturados, como imagens.
Resumir as principais ideias ou impressões transmitidas pelo conteúdo.
Extrair dados estruturados do texto.
Classificar texto ou dados não estruturados em categorias definidas pelo usuário.
Gerar embeddings para pesquisar textos, imagens e vídeos semelhantes.
Avaliar entradas para classificá-las por qualidade, semelhança ou outros critérios.

As funções de IA são agrupadas nas seguintes categorias para ajudar você a realizar essas tarefas:

Funções de IA de uso geral: essas funções oferecem controle total e transparência na escolha do modelo, do comando e dos parâmetros a serem usados.
- Realizar inferência de LLM, como responder a perguntas sobre seus dados
  - AI.GENERATE é a função de inferência mais flexível, que permite analisar dados estruturados ou não estruturados.
  - AI.GENERATE_TEXT é uma versão com valor de tabela de AI.GENERATE que também oferece suporte a modelos de parceiros e modelos abertos.
- Gerar saída estruturada, como extrair nomes, endereços ou descrições de objetos de textos, documentos ou imagens.
  - AI.GENERATE, quando você especifica um esquema de saída.
  - AI.GENERATE_TABLE é uma versão com valor de tabela de AI.GENERATE que chama um modelo remoto e permite especificar um esquema de saída personalizado.
  - Se o esquema de saída tiver um único campo, você poderá usar uma das funções especializadas: AI.GENERATE_BOOL, AI.GENERATE_DOUBLE ou AI.GENERATE_INT.
- Gerar embeddings para pesquisa semântica e clustering
  - AI.EMBED: cria um embedding com base em dados de texto ou imagem.
  - AI.GENERATE_EMBEDDING: uma função com valor de tabela que adiciona uma coluna de dados de texto, imagem, áudio, vídeo ou documento incorporados à tabela.
Funções de IA gerenciadas: Essas funções têm uma sintaxe simplificada e são otimizadas para custo e qualidade. Com o modo otimizado (visualização), essas funções são escalonadas para milhões ou bilhões de linhas.
- AI.IF: filtra seus dados com condições de linguagem natural.
- AI.SCORE: avalia a entrada, como por qualidade ou sentimento.
- AI.CLASSIFY: classifica a entrada em categorias definidas pelo usuário.
- AI.AGG: agrega a entrada para resumir ou analisar seus dados.
Funções utilitárias: use a AI.COUNT_TOKENS função para estimar o número de tokens em um comando de entrada antes de executar uma consulta.
Funções específicas da tarefa: Essas funções usam APIs da IA do Google Cloud para ajudar você a realizar tarefas como processamento de linguagem natural, tradução automática, processamento de documentos, transcrição de áudio e visão computacional.

Funções de IA de uso geral

As funções de IA de uso geral oferecem controle total e transparência na escolha do modelo, do comando e dos parâmetros a serem usados. A saída delas inclui informações detalhadas sobre a chamada para o modelo, incluindo o status e a resposta completa do modelo, que podem incluir informações sobre a classificação de segurança ou citações.

Realizar inferência de LLM

A função AI.GENERATE é uma função de inferência flexível que funciona enviando solicitações a um modelo do Gemini da Gemini Enterprise Agent Platform e retornando a resposta desse modelo. É possível usar essa função para analisar dados de texto, imagem, áudio, vídeo ou PDF. Por exemplo, você pode analisar imagens de móveis domésticos para gerar texto para uma coluna design_type, de modo que o SKU dos móveis tenha uma descrição associada, como mid-century modern ou farmhouse.

É possível realizar tarefas de IA generativa usando modelos remotos no BigQuery ML para referenciar modelos implantados ou hospedados na Agent Platform com a função com valor de tabela AI.GENERATE_TEXT. É possível usar os seguintes tipos de modelos remotos:

Modelos remotos em qualquer um dos modelos do Gemini disponíveis ou de visualização para analisar conteúdo de texto, imagem, áudio, vídeo ou PDF de tabelas padrão ou de objetos com um comando fornecido como argumento de função.
Modelos remotos em Anthropic Claude, Mistral AI ou Llama modelos de parceiros, ou modelos abertos com suporte, para analisar um comando fornecido em uma consulta ou de uma coluna em uma tabela padrão.

Use os tópicos a seguir para tentar a geração de texto no BigQuery ML:

Para alguns modelos, é possível escolher configurar o ajuste supervisionado, que permite treinar o modelo nos seus próprios dados para que ele seja mais adequado ao seu caso de uso. Toda inferência ocorre na Agent Platform. Os resultados são armazenados no BigQuery.

Gerar dados estruturados

A geração de dados estruturados é muito semelhante à geração de texto, exceto que é possível formatar a resposta do modelo especificando um esquema SQL. Por exemplo, é possível gerar uma tabela que contenha o nome, o número de telefone, o endereço, a solicitação e a cotação de preços de um cliente com base em uma transcrição de uma chamada telefônica.

É possível gerar dados estruturados das seguintes maneiras:

A função AI.GENERATE chama um endpoint da Agent Platform e pode gerar um valor STRUCT com seu esquema personalizado.

Para testar, consulte Como usar a saída estruturada ao chamar a função AI.GENERATE.
A função AI.GENERATE_TABLE chama um modelo remoto e é uma função com valor de tabela que gera uma tabela com seu esquema personalizado.

Para tentar criar dados estruturados, consulte Gerar dados estruturados usando a função AI.GENERATE_TABLE.
Para um único campo de saída, é possível usar uma das seguintes funções de inferência especializadas:

Gerar embeddings

Um embedding é um vetor numérico de alta dimensão que representa uma determinada entidade, como um texto ou um arquivo de áudio. A geração de embeddings permite capturar a semântica dos dados de uma maneira que facilita o raciocínio e a comparação dos dados.

Confira alguns casos de uso comuns para a geração de embeddings:

Usar a geração aumentada por recuperação (RAG) para aumentar as respostas do modelo às consultas do usuário, referenciando dados adicionais de uma fonte confiável. A RAG oferece melhor precisão factual e consistência de resposta, além de acesso a dados mais recentes do que os dados de treinamento do modelo.
Realizar pesquisa multimodal. Por exemplo, usar a entrada de texto para pesquisar imagens.
Realizar pesquisa semântica para encontrar itens semelhantes para recomendações, substituição e desduplicação de registros.
Criar embeddings para usar com um modelo k-means para clustering.

Para mais informações sobre como gerar embeddings e usá-los para realizar essas tarefas, consulte a Introdução a embeddings e pesquisa vetorial.

Funções de IA gerenciadas

As funções de IA gerenciadas simplificam tarefas rotineiras, como filtragem, classificação ou agregação. Essas funções podem analisar dados de texto, imagem, áudio, vídeo ou PDF. Essas funções usam o Gemini e não exigem personalização. O BigQuery usa a engenharia de comandos e pode selecionar o modelo e os parâmetros adequados para usar na tarefa específica para otimizar a qualidade e a consistência dos resultados. Cada função retorna um valor escalar, como BOOL, FLOAT64 ou STRING, e não inclui informações de status adicionais do modelo. As seguintes funções de IA gerenciadas estão disponíveis:

AI.IF: filtra texto ou dados multimodais, como em uma cláusula WHERE ou JOIN, com base em um comando. Por exemplo, é possível filtrar descrições de produtos por aquelas que descrevem um item que seria um bom presente.
AI.SCORE: avalia as entradas com base em um comando para classificar as linhas por qualidade, semelhança ou outros critérios. É possível usar essa função em uma cláusula ORDER BY para extrair os K principais itens de acordo com a pontuação. Por exemplo, é possível encontrar as 10 principais avaliações de usuários mais positivas ou negativas de um produto.
AI.CLASSIFY: classifica o texto em categorias definidas pelo usuário. É possível usar essa função em uma cláusula GROUP BY para agrupar entradas de acordo com as categorias definidas. Por exemplo, é possível classificar tíquetes de suporte por se eles estão relacionados a faturamento, frete, qualidade do produto ou algo mais.
AI.AGG: agrega a entrada com base em instruções de linguagem natural para resumir ou analisar seus dados. Por exemplo, é possível analisar registros de sessões de aplicativos de usuários para determinar onde os clientes estão tendo dificuldades ou resumir o conteúdo de um grande conjunto de imagens.

Para um tutorial que mostra exemplos de como usar essas funções, consulte Realizar análises semânticas com funções de IA gerenciadas.

Para um tutorial de notebook que mostra como usar funções de IA gerenciadas e de uso geral funções, consulte Análise semântica com funções de IA.

Funções específicas da tarefa

Além das funções mais gerais descritas nas seções anteriores, é possível desenvolver soluções específicas para tarefas no BigQuery ML usando APIs de IA do Google Cloud. Veja a seguir algumas das tarefas disponíveis:

Para mais informações, consulte Visão geral das soluções específicas para tarefas.

Locais

Os locais com suporte para modelos de geração de texto e embedding variam de acordo com o tipo e a versão do modelo usado. Veja mais informações em Locais.

O BigQuery oferece suporte aos modelos gemini-3.1-flash-lite e gemini-3.5-flash. A Agent Platform oferece suporte apenas a endpoints multirregionais para esses modelos. Endpoints regionais não são aceitos. Se você especificar um nome de endpoint curto que omite a região, como gemini-3.5-flash, o BigQuery selecionará um endpoint de acordo com as seguintes regras:

Se a consulta for executada na região us ou em qualquer região única nos EUA, então o BigQuery usará o endpoint us.
Se a consulta for executada na região eu ou em qualquer região única na UE, exceto europe-west2 ou europe-west6, o BigQuery usará o endpoint eu.
Para todos os outros locais, incluindo europe-west2 e europe-west6, o BigQuery usa o endpoint global.

Para especificar um endpoint específico, use um nome de endpoint multirregional totalmente qualificado em um dos seguintes formatos:

https://aiplatform.us.rep.googleapis.com/v1/projects/PROJECT_ID/locations/us/publishers/google/models/MODEL_ID
https://aiplatform.eu.rep.googleapis.com/v1/projects/PROJECT_ID/locations/eu/publishers/google/models/MODEL_ID
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID

Se a consulta for executada na região asia-south1, será necessário usar o nome do endpoint global totalmente qualificado.

Limitações

Dentro de um perímetro do VPC Service Controls, as funções de IA não podem processar ObjectRef valores que usam acesso delegado. O acesso delegado gera um URL HTTPS assinado para o objeto, e a Agent Platform bloqueia buscas HTTP e HTTPS para projetos dentro de um perímetro. A função grava o seguinte erro no campo status da saída:

INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC.

Como a coluna ref de uma tabela de objetos sempre usa a conexão da tabela de objetos como autorizador, a transmissão de ref para uma função de IA dentro de um perímetro sempre retorna esse erro. Para analisar o objeto, transmita um valor de argumento único OBJ.MAKE_REF(uri), que usa acesso direto e envia o URI do Cloud Storage para o modelo sem gerar um URL assinado.

Preços

Você paga pelos recursos de computação usados para executar consultas em modelos. Os modelos remotos fazem chamadas para modelos da Agent Platform. Portanto, as consultas em modelos remotos também geram cobranças da Agent Platform.

Para mais informações, consulte Preços do BigQuery ML.

Acompanhar o uso de tokens

Ao chamar uma função de IA generativa que usa um modelo do Gemini diferente de um modelo de embedding, é possível conferir o número total de cada tipo de token processado pela consulta. No painel Resultados da consulta, clique em Informações do job. As seguintes contagens aparecem, divididas por modalidade, se aplicável:

Contagem de tokens de entrada:o número total de tokens de entrada para todas as funções de IA generativa chamadas na consulta.
Contagem de tokens de saída. O número total de tokens em todas as respostas candidatas geradas pela consulta.
Contagem de tokens de raciocínio. O número total de tokens que faziam parte dos pensamentos gerados do modelo, se aplicável.
Contagem de tokens do cache. O número total de tokens de entrada que foram armazenados em cache implicitamente pela consulta.

Acompanhar custos

As funções de IA generativa no BigQuery funcionam enviando solicitações para a Gemini Enterprise Agent Platform, o que pode gerar custos. Para estimar a contagem de tokens de entrada antes de executar uma consulta, use a AI.COUNT_TOKENS função. Para acompanhar os custos da Agent Platform incorridos por um job executado no BigQuery, siga estas etapas:

Consulte seus relatórios de faturamento em Cloud Billing.
Use filtros para refinar os resultados.

Para serviços, selecione Vertex AI.
Para conferir as cobranças de um job específico, filtre por rótulo.

Defina a chave como bigquery_job_id_prefix e o valor como o ID do job. Se o ID do job tiver mais de 63 caracteres, use apenas os primeiros 63 caracteres. Se o ID do job contiver caracteres maiúsculos, mude-os para minúsculos. Como alternativa, é possível associar jobs a um rótulo personalizado para ajudar a pesquisá-los mais tarde.

Pode levar até 24 horas para que algumas cobranças apareçam no Cloud Billing.

Monitoramento

Para entender melhor o comportamento das funções de IA chamadas no BigQuery, é possível ativar o registro de solicitações e respostas. Para registrar toda a solicitação e resposta enviada e recebida da Agent Platform, siga estas etapas:

Ative os registros de solicitação/resposta na Gemini Enterprise Agent Platform. Os registros são armazenados no BigQuery. É necessário ativar a geração de registros separadamente para cada modelo de fundação e região. Para registrar consultas executadas na região us, especifique a us-central1 região na solicitação. Para registrar consultas executadas na região eu, especifique a região europe-west4 na solicitação.
Execute uma consulta usando uma função de IA que faça uma chamada para a Agent Platform usando o modelo para o qual você ativou o registro na etapa anterior.
Para conferir a solicitação e a resposta completas da Agent Platform, consulte a tabela de registro para linhas em que o labels.bigquery_job_id_prefix campo da coluna full_request corresponde aos primeiros 63 caracteres do ID do job. Opcionalmente, é possível usar um rótulo de consulta personalizado para ajudar a pesquisar a consulta nos registros.

Por exemplo, é possível usar uma consulta semelhante a esta:
```
SELECT *
FROM `my_project.my_dataset.request_response_logging`
WHERE JSON_VALUE(full_request, '$.labels.bigquery_job_id_prefix') = 'bquxjob_123456...';
```

Gerenciamento de erros

Erros no nível da linha, como RESOURCE_EXHAUSTED, podem ocorrer se uma função de IA exceder a cota ou os limites do serviço remoto. Quando ocorre um erro no nível da linha, a função retorna NULL para essa linha, o que pode resultar em resultados de consulta incompletos.

Todas as funções de IA podem encontrar esses erros. No entanto, as funções de IA gerenciadas (AI.IF, AI.CLASSIFY e AI.SCORE) oferecem suporte ao argumento max_error_ratio para ajudar a gerenciá-los. Use esse argumento para definir um limite de falha que permita que a consulta seja bem-sucedida, apesar das falhas no nível da linha.

O valor padrão de max_error_ratio é 1.0. Para diminuir a tolerância a erros, defina-o como um valor menor (por exemplo, 0.2), para que a consulta falhe em vez de ser bem-sucedida com falhas parciais. Para detalhes de sintaxe, consulte a referência documentação de AI.IF, AI.CLASSIFY, ou AI.SCORE.

Se a consulta for bem-sucedida com falhas parciais, o BigQuery retornará um aviso. Para mais informações sobre os erros de função, confira o campo Erros de função de IA generativa na guia Informações do job dos resultados da consulta no console Google Cloud .

Se a consulta incluir uma cláusula LIMIT, o limite será aplicado depois que o modelo processar um lote de linhas. Consequentemente, a proporção de valores NULL no conjunto de resultados final poderá parecer maior do que o max_error_ratio especificado.

Por exemplo, suponha que a consulta tenha uma cláusula LIMIT 10 e um max_error_ratio de 0.2. O modelo pode processar 20 linhas antes que o limite seja aplicado. Se 3 dessas 20 linhas falharem, a taxa de erros será 0.15 (15%), que está dentro do limite de 20%. No entanto, se o subconjunto de linhas selecionado pela cláusula LIMIT incluir todas as 3 linhas com falha, a saída visível vai conter 30% de valores NULL.

A seguir

Para uma introdução à IA e ao ML no BigQuery, consulte Introdução à IA e ao ML no BigQuery.
Para mais informações sobre como realizar inferência em modelos de machine learning, consulte Visão geral da inferência de modelos.
Para mais informações sobre instruções e funções SQL com suporte para modelos de IA generativa, consulte Jornadas do usuário completas para modelos de IA generativa.