A
função AI.TRANSLATE
permite traduzir textos entre idiomas diretamente no BigQuery. Por
exemplo, é possível localizar catálogos de produtos, traduzir o feedback dos clientes para
equipes de suporte globais ou padronizar respostas de pesquisas multilíngues sem
criar pipelines de dados separados. A função conecta o BigQuery
à API Cloud Translation usando suas credenciais de usuário final. Assim, não é necessário
criar uma conexão ou um modelo remoto.
Neste tutorial, você vai criar uma tabela de amostra de feedback multilíngue de clientes, traduzir texto para o inglês com detecção automática de idioma, inspecionar metadados de tradução e traduzir avaliações de filmes para o espanhol usando o modelo LLM de tradução.
Objetivos
- Criar um conjunto de dados e uma tabela de amostra de texto multilíngue.
- Traduza textos multilíngues para o inglês com a detecção automática de idioma.
- Retornar metadados de tradução e códigos de idioma de origem detectados.
- Traduza textos com nuances usando o modelo de LLM de tradução.
Custos
Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:
- BigQuery. You incur costs for the data that you process in BigQuery.
- Cloud Translation. You incur costs for calls to the Cloud Translation API.
Para gerar uma estimativa de custo baseada na sua projeção de uso,
use a calculadora de preços.
Para mais informações, consulte Preços do BigQuery e Preços do Translation.
Antes de começar
Console
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery and Translation APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Verifique se você tem os seguintes papéis no projeto: Editor de dados do BigQuery, Usuário de jobs do BigQuery, Usuário da API Cloud Translation.
Verificar os papéis
-
No console do Google Cloud , acesse a página IAM.
Acessar IAM - Selecione o projeto.
-
Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.
- Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.
Conceder os papéis
-
No console do Google Cloud , acesse a página IAM.
Acessar IAM - Selecione o projeto.
- Clique em Conceder acesso.
-
No campo Novos principais, digite seu identificador de usuário. Normalmente, é o identificador de um usuário em um pool de identidades de força de trabalho. Saiba mais em Representar usuários do pool de força de trabalho nas políticas do IAM ou entre em contato com seu administrador.
- Clique em Selecionar um papel e pesquise o papel.
- Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
- Clique em Salvar.
-
gcloud
-
Instale a CLI do Google Cloud.
-
Configure a CLI gcloud para usar sua identidade federada.
Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
Crie ou selecione um projeto do Google Cloud .
Papéis necessários para selecionar ou criar um projeto
- Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. É possível selecionar qualquer projeto em que você tenha recebido um papel.
-
Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos
(
roles/resourcemanager.projectCreator), que contém a permissãoresourcemanager.projects.create. Saiba como conceder papéis.
-
Crie um projeto do Google Cloud :
gcloud projects create PROJECT_ID
Substitua
PROJECT_IDpor um nome para o projeto do Google Cloud que você está criando. -
Selecione o projeto do Google Cloud que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_IDpelo nome do projeto do Google Cloud .
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative as APIs BigQuery e Translation, se ainda não estiverem ativadas:
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.gcloud services enable bigquery.googleapis.com
translate.googleapis.com -
Conceda papéis à sua conta de usuário. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM:
roles/bigquery.dataEditor, roles/bigquery.jobUser, roles/cloudtranslate.usergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Substitua:
PROJECT_ID: o ID do projeto.USER_IDENTIFIER: o identificador da sua conta de usuário . Para ver exemplos, consulte Representar usuários do pool de força de trabalho nas políticas do IAM.ROLE: o papel do IAM que você concede à sua conta de usuário.
Criar um conjunto de dados
Para criar um conjunto de dados do BigQuery, selecione uma das seguintes opções:
Console
No console do Google Cloud , acesse a página BigQuery.
No painel à esquerda, clique em Explorer:

Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.
No Explorer, expanda o projeto e clique em Conjuntos de dados.
Na página Conjuntos de dados, clique em Criar conjunto de dados.
No painel Criar conjunto de dados, faça o seguinte:
Para o código do conjunto de dados, insira
bqml_tutorial.Em Local dos dados, selecione EUA.
Não altere as outras configurações padrão.
Clique em Criar conjunto de dados.
bq
Para criar um novo conjunto de dados, use o
comando bq mk --dataset.
Crie um conjunto de dados chamado
bqml_tutorialcom o local de dados definido comoUS:bq mk --dataset \ --location=US \ --description "BigQuery ML tutorial dataset." \ bqml_tutorial
Confirme se o conjunto de dados foi criado:
bq ls
API
Chame o método datasets.insert com um recurso de conjunto de dados definido:
{ "datasetReference": { "datasetId": "bqml_tutorial" } }
Criar uma tabela de amostra
Use a
instrução CREATE TABLE
para criar uma tabela de feedback multilíngue de clientes no conjunto de dados
bqml_tutorial:
No console do Google Cloud , acesse a página BigQuery.
No editor de consultas, execute a seguinte instrução:
CREATE OR REPLACE TABLE `bqml_tutorial.customer_feedback` AS ( SELECT * FROM UNNEST( [ STRUCT<feedback_id INT64, feedback_text STRING>( 1, 'El servicio de entrega fue rápido y confiable.'), (2, 'Je suis très satisfait de la qualité de ce produit.'), (3, 'Die Benutzeroberfläche der App ist sehr übersichtlich.'), (4, 'O suporte ao cliente resolveu meu problema com rapidez.') ]) );
Traduzir texto multilíngue
Use a
função AI.TRANSLATE
para traduzir o feedback do cliente para o inglês (en). Quando você omite o
argumento source_language, a API Cloud Translation detecta automaticamente
o idioma de origem de cada linha e traduz o texto usando o modelo padrão de
tradução automática neural (NMT):
No console do Google Cloud , acesse a página BigQuery.
No editor de consultas, execute a seguinte instrução para traduzir o feedback para o inglês:
SELECT feedback_id, feedback_text, AI.TRANSLATE(feedback_text, 'en') AS translated_text FROM `bqml_tutorial.customer_feedback`;
Para ver uma lista de códigos de idioma de destino válidos, consulte os idiomas compatíveis.
O resultado será o seguinte:
+-------------+-----------------------------+-----------------------------+ | feedback_id | feedback_text | translated_text | +-------------+-----------------------------+-----------------------------+ | 1 | El servicio de entrega fue | The delivery service was | | | rápido y confiable. | fast and reliable. | +-------------+-----------------------------+-----------------------------+ | 2 | Je suis très satisfait de | I am very satisfied with | | | la qualité de ce produit. | the quality of this | | | | product. | +-------------+-----------------------------+-----------------------------+ | 3 | Die Benutzeroberfläche der | The app's user interface is | | | App ist sehr übersichtlich. | very clear. | +-------------+-----------------------------+-----------------------------+ | 4 | O suporte ao cliente | Customer support resolved | | | resolveu meu problema com | my issue quickly. | | | rapidez. | | +-------------+-----------------------------+-----------------------------+
Retornar detalhes da tradução e idiomas detectados
Ao processar textos de várias regiões, talvez você queira registrar o
idioma de origem detectado em cada tradução ou verificar se há erros por linha.
Defina return_details => TRUE na
função AI.TRANSLATE
para retornar um valor STRUCT que inclua o texto traduzido, o status de execução
e os metadados de resposta da API:
No console do Google Cloud , acesse a página BigQuery.
No editor de consultas, execute a seguinte instrução para extrair o código de idioma detectado, o texto traduzido e o status de cada linha:
WITH translations AS ( SELECT feedback_id, AI.TRANSLATE( feedback_text, 'en', return_details => TRUE) AS translation FROM `bqml_tutorial.customer_feedback` ) SELECT feedback_id, STRING(translation.details.detected_language_code) AS detected_language, translation.result AS translated_text, translation.status FROM translations;
O resultado será o seguinte:
+-------------+-------------------+-----------------------------+--------+ | feedback_id | detected_language | translated_text | status | +-------------+-------------------+-----------------------------+--------+ | 1 | es | The delivery service was | OK | | | | fast and reliable. | | +-------------+-------------------+-----------------------------+--------+ | 2 | fr | I am very satisfied with | OK | | | | the quality of this | | | | | product. | | +-------------+-------------------+-----------------------------+--------+ | 3 | de | The app's user interface is | OK | | | | very clear. | | +-------------+-------------------+-----------------------------+--------+ | 4 | pt | Customer support resolved | OK | | | | my issue quickly. | | +-------------+-------------------+-----------------------------+--------+
Quando
return_detailsé definido comoTRUE, oSTRUCTretornado contém os seguintes campos:result: um valorSTRINGque contém o texto traduzido ouNULLse ocorrer um erro.status: um valorSTRINGque contémOKquando a operação é bem-sucedida ou uma mensagem de erro se ocorrer um erro.details: um valorJSONque contém a resposta da API Cloud Translation para a linha, incluindodetected_language_codequando o idioma de origem é detectado automaticamente, ou detalhes do erro, se houver.
Traduzir textos com o LLM de tradução
Para textos que contêm linguagem informal, gírias ou sentimentos complexos, como
avaliações de clientes ou filmes, defina model => 'translation-llm' na
função AI.TRANSLATE
para usar o modelo LLM de tradução em vez do
modelo NMT padrão. Quando você sabe o idioma da coluna de entrada, também pode
especificar o argumento source_language:
No console do Google Cloud , acesse a página BigQuery.
No editor de consultas, execute a seguinte instrução para traduzir cinco avaliações de filmes em inglês de um conjunto de dados público para o espanhol (
es):SELECT review, AI.TRANSLATE( review, 'es', source_language => 'en', model => 'translation-llm') AS translated_review FROM `bigquery-public-data.imdb.reviews` LIMIT 5;
O resultado será o seguinte:
+------------------------------------+------------------------------------+ | review | translated_review | +------------------------------------+------------------------------------+ | Once again Mr. Costner has dragged | Una vez más, el Sr. Costner ha | | out a movie for far longer than... | alargado una película mucho más... | +------------------------------------+------------------------------------+ | This movie is amazing because the | Esta película es increíble porque | | fact that real people portray... | las personas reales se... | +------------------------------------+------------------------------------+ | ... | ... | +------------------------------------+------------------------------------+
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Excluir o projeto
Excluir um projeto do Google Cloud :
gcloud projects delete PROJECT_ID
Excluir recursos individuais
Se você quiser reutilizar o projeto, exclua o conjunto de dados criado para este tutorial:
Console
No console do Google Cloud , acesse a página BigQuery.
Exclua o conjunto de dados
bqml_tutorial. A exclusão do conjunto de dados também exclui a tabelacustomer_feedback:No painel Explorer, expanda o projeto e clique em Conjuntos de dados.
Na lista Conjuntos de dados, clique no conjunto de dados
bqml_tutorial.No painel de detalhes, clique em Excluir.
Na caixa de diálogo Excluir conjunto de dados, clique em Excluir.
gcloud
- Exclua o conjunto de dados
bqml_tutoriale a tabelacustomer_feedback:
bq rm --dataset --recursive bqml_tutorial
A seguir
- Saiba mais sobre a
função
AI.TRANSLATE. - Saiba mais sobre os modelos de LLM de tradução e tradução automática neural.
- Compare as opções de análise de texto em Escolher uma função de processamento de linguagem natural.
- Saiba mais sobre a IA generativa no BigQuery.
- Consulte as instruções e funções SQL compatíveis em Jornadas do usuário completas para modelos de IA generativa.