O Google AI Studio recebe mais de 27 mil pesquisas por mês em Portugal e continua a crescer, mas a maior parte dos tutoriais em português trata a ferramenta como um simples chat de teste. Isso deixa de fora a parte mais útil: usar o AI Studio para construir uma aplicação real com a API Gemini, gerar uma chave, afinar um modelo com os seus próprios dados através de ajuste supervisionado (supervised fine-tuning) e publicar tudo em código. Este tutorial cobre o processo completo, do zero a um projeto funcional em Node.js, com os passos que costumam falhar e as soluções para cada um.
Vamos construir um assistente de suporte ao cliente para uma loja fictícia, treinado com exemplos reais de perguntas e respostas da marca. O resultado final é um modelo Gemini afinado, acessível pela API, mais barato e mais consistente do que usar prompts genéricos.
O que é o Google AI Studio e porque interessa em 2026
O Google AI Studio é a interface gratuita da Google para experimentar, testar e construir com os modelos Gemini antes de escrever uma única linha de código de produção. Nasceu como sandbox para o Gemini Pro e, segundo o próprio blog da Google, “developers have free access to Gemini Pro and Gemini Pro Vision through Google AI Studio, with up to 60 requests per minute, making it suitable for most app development needs” (Google, blog oficial). Essa promessa de acesso gratuito manteve-se como o pilar da ferramenta até hoje.
Em setembro de 2026, o AI Studio já não é apenas uma caixa de chat. Serve três funções distintas: prototipagem rápida de prompts, geração de chaves de API para a Gemini Developer API, e agora também o ponto de entrada para tarefas de ajuste supervisionado em modelos específicos, como o gemini-3.5-flash. A família de modelos evoluiu bastante desde o lançamento inicial: o Gemini 3.5 Flash tornou-se a versão GA (generally available) em maio de 2026, segundo as notas de lançamento da Gemini API, e passou a ser o modelo por trás do alias gemini-flash-latest. Em julho de 2026 a Google avançou ainda mais, apresentando o Gemini 3.6 Flash junto com o 3.5 Flash-Lite e o 3.5 Flash Cyber, conforme o anúncio no blog da Google.
Nem todos esses modelos aceitam ajuste fino. Segundo a documentação de tuning supervisionado do Vertex AI, apenas o gemini-3.1-flash-lite e o gemini-3.5-flash suportam supervised fine-tuning em preview público, com jobs restritos às regiões us-central1 e europe-west4. É esse detalhe que decide todo o resto deste tutorial: vamos trabalhar com o gemini-3.5-flash, porque é o único da geração atual que combina disponibilidade GA com suporte a ajuste fino documentado.
Explorar o editor de prompts antes de escrever código
Antes de qualquer linha de código, vale a pena passar 15 minutos dentro do próprio AI Studio. O editor de prompts, acessível em aistudio.google.com/prompts/new_chat, tem três painéis relevantes: a área de conversa à esquerda, as instruções de sistema (System instructions) no topo, e um conjunto de controlos à direita com o seletor de modelo, temperatura, top-p e o limite de tokens de saída.
Escreva ali as instruções de sistema que descrevem o assistente que quer construir – por exemplo, “Respondes sempre em português europeu, como apoio ao cliente de uma loja online. Sê direto e educado.” – e teste algumas perguntas reais antes de decidir se precisa mesmo de ajuste fino. Esta etapa evita um erro comum: gastar tempo a preparar um dataset de treino quando um bom prompt de sistema já resolve o problema sozinho.
O AI Studio também tem um modo de comparação (Compare mode), que corre o mesmo prompt em dois modelos ou duas configurações lado a lado. É útil para decidir, por exemplo, se o gemini-3.5-flash já responde bem o suficiente sem tuning, ou se vale a pena avançar para o processo mais longo descrito neste tutorial. Só quando o prompt de sistema já não é suficiente – porque o tom continua inconsistente, ou porque o modelo ignora regras específicas do negócio com frequência – é que o ajuste fino supervisionado começa a compensar o esforço extra.
Quando estiver satisfeito com um prompt de teste, o botão “Get code” no canto superior direito gera automaticamente o equivalente em Python, Node.js ou REST, já com a chamada à API formatada. É o ponto de partida mais rápido para o código dos passos seguintes, porque poupa o trabalho de escrever a estrutura inicial da chamada à mão.
Pré-requisitos e versões usadas neste tutorial
Antes de abrir o navegador, confirme que tem tudo isto pronto. Ignorar qualquer um destes pontos é a causa mais comum de bloqueios a meio do processo.
| Requisito | Versão/detalhe | Onde obter |
|---|---|---|
| Conta Google | Pessoal ou Workspace, com verificação em dois passos ativa | accounts.google.com |
| Node.js | 20 LTS ou superior | nodejs.org |
| SDK oficial | @google/genai (pacote npm atual, substitui o antigo @google/generative-ai) | npm install @google/genai |
| Projeto Google Cloud | Com faturação ativa (necessário para tuning via Vertex AI) | console.cloud.google.com |
| Editor de texto | VS Code ou equivalente, com extensão JSON | code.visualstudio.com |
| Dataset próprio | Ficheiro .jsonl com pares pergunta/resposta | Criado neste tutorial |
Não é preciso cartão de crédito só para experimentar no AI Studio: a camada gratuita da Gemini Developer API continua ativa para o gemini-3.5-flash-lite e outros modelos leves. Mas o ajuste supervisionado corre em Vertex AI, o que implica um projeto com faturação associada, mesmo que o custo final fique perto de zero para um dataset pequeno.
Passo 1: Criar o projeto e ativar a Gemini API
Aceda a aistudio.google.com e inicie sessão com a conta Google. No canto superior esquerdo, escolha “Get API key” e depois “Create API key in new project”. O AI Studio cria automaticamente um projeto Google Cloud associado à chave, o que evita ter de configurar manualmente a Cloud Console nesta fase inicial.
Guarde a chave num local seguro, nunca em código versionado. Vamos usá-la já a seguir para testar a ligação.
mkdir assistente-gemini
cd assistente-gemini
npm init -y
npm install @google/genai dotenv
echo "GEMINI_API_KEY=cole_a_sua_chave_aqui" > .env
echo ".env" >> .gitignorePasso 2: Testar a chamada básica à API Gemini
Antes de pensar em ajuste fino, confirme que a chave funciona com o modelo base. Crie um ficheiro chamado teste.js:
import { GoogleGenAI } from "@google/genai";
import "dotenv/config";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: "Responde em português europeu: o que é ajuste fino de um modelo de linguagem?",
});
console.log(response.text);
}
main();Corra com node –experimental-modules teste.js ou adicione “type”: “module” ao package.json e execute node teste.js. Se receber texto coerente em português, a ligação está pronta. Se receber um erro 403 ou API_KEY_INVALID, avance já para a secção de resolução de problemas mais abaixo – poupa tempo resolver isto antes de preparar o dataset.
Passo 3: Preparar o dataset para ajuste supervisionado
O ajuste supervisionado do Gemini aceita um ficheiro JSONL (JSON Lines), em que cada linha é um objeto independente com o par entrada/saída esperado. Para um assistente de suporte ao cliente, cada linha representa uma pergunta típica e a resposta que a marca quer que o modelo dê.
{"text_input": "Qual é o prazo de entrega em Portugal Continental?", "output": "As entregas em Portugal Continental demoram entre 2 a 4 dias úteis. Ilhas e regiões autónomas podem levar até 7 dias úteis."}
{"text_input": "Como troco um artigo que não serve?", "output": "Tem 30 dias após a receção para trocar qualquer artigo. Basta preencher o formulário de devolução na sua conta e levar o pacote a um ponto CTT."}
{"text_input": "Aceitam MB Way?", "output": "Sim, aceitamos MB Way, Multibanco, cartão de crédito e PayPal em todas as encomendas para Portugal."}Segundo a documentação do Vertex AI sobre ajuste supervisionado, o limite máximo por exemplo é de 131.072 tokens de entrada e saída combinados, o dataset de treino pode ir até 10 milhões de exemplos apenas de texto, e o ficheiro JSONL completo não pode exceder 1 GB. O conjunto de validação, quando usado, aceita até 5.000 exemplos ou 30% do total de treino, o que for menor. Para um caso como este, entre 200 e 1.000 exemplos de qualidade elevada já produzem diferença percetível face ao modelo base – a documentação oficial não fixa um mínimo obrigatório, mas a consistência dos exemplos pesa mais do que o volume.
Crie um script simples para validar o formato antes de submeter, porque um único JSON malformado faz o job inteiro falhar:
import { readFileSync } from "fs";
const linhas = readFileSync("dataset.jsonl", "utf-8").trim().split("\n");
let erros = 0;
linhas.forEach((linha, i) => {
try {
const obj = JSON.parse(linha);
if (!obj.text_input || !obj.output) {
console.log(`Linha ${i + 1}: falta text_input ou output`);
erros++;
}
} catch (e) {
console.log(`Linha ${i + 1}: JSON inválido – ${e.message}`);
erros++;
}
});
console.log(`${linhas.length} linhas verificadas, ${erros} com problemas.`);Passo 4: Carregar o dataset para o Cloud Storage
O Vertex AI lê o dataset de tuning a partir de um bucket do Google Cloud Storage, não de um upload direto no AI Studio. Na Cloud Console, abra Cloud Storage, crie um bucket (por exemplo gs://assistente-gemini-tuning) e carregue o ficheiro dataset.jsonl. Se preferir linha de comandos, com o gcloud CLI instalado:
gcloud storage buckets create gs://assistente-gemini-tuning --location=eu
gcloud storage cp dataset.jsonl gs://assistente-gemini-tuning/dataset.jsonlRepare na região: os jobs de tuning supervisionado do gemini-3.5-flash só correm em us-central1 ou europe-west4 segundo as notas de lançamento da plataforma Gemini Enterprise. Escolher europe-west4 (Países Baixos) mantém os dados dentro da União Europeia, o que costuma ser relevante para equipas em Portugal sujeitas ao RGPD.
Passo 5: Criar o job de ajuste supervisionado
Com o dataset no bucket, o próximo passo é lançar o job de tuning. Pode fazer isto pela Cloud Console (Vertex AI → Model Garden → Gemini → Tune a model) ou por código. A via programática é mais fácil de repetir e documentar:
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
vertexai: true,
project: "o-seu-projeto-gcp",
location: "europe-west4",
});
const tuningJob = await ai.tunings.tune({
baseModel: "gemini-3.5-flash",
trainingDataset: {
gcsUri: "gs://assistente-gemini-tuning/dataset.jsonl",
},
tuningJob: {
epochCount: 3,
tunedModelDisplayName: "assistente-suporte-pt",
},
});
console.log("Job criado:", tuningJob.name);O número de épocas (epochCount) controla quantas vezes o modelo percorre o dataset completo durante o treino. Três épocas é um ponto de partida razoável para datasets pequenos; valores mais altos aumentam o risco de overfitting, em que o modelo memoriza os exemplos em vez de generalizar.
Passo 6: Acompanhar o progresso do job
O tuning é assíncrono – o pedido devolve um identificador de operação e o treino continua em segundo plano. A documentação da plataforma não publica uma duração garantida, porque depende do modelo, do número de exemplos, do número de épocas e da fila da região escolhida. Para um dataset de algumas centenas de exemplos, a experiência típica fica entre 20 minutos e cerca de 2 horas.
let estado = await ai.tunings.get({ name: tuningJob.name });
while (estado.state !== "JOB_STATE_SUCCEEDED" && estado.state !== "JOB_STATE_FAILED") {
console.log("Estado atual:", estado.state);
await new Promise((r) => setTimeout(r, 60000));
estado = await ai.tunings.get({ name: tuningJob.name });
}
console.log("Resultado final:", estado.state);
if (estado.state === "JOB_STATE_SUCCEEDED") {
console.log("Modelo afinado:", estado.tunedModel.model);
}Pode também acompanhar visualmente pela Cloud Console, em Vertex AI → Tuning, onde aparecem métricas de perda (loss) por época em tempo real para este tipo de job, segundo as notas de lançamento mais recentes da plataforma Gemini Enterprise Agent.
Passo 7: Chamar o modelo afinado a partir do código
Quando o job termina com sucesso, o identificador do modelo afinado substitui o nome do modelo base nas chamadas seguintes. A estrutura da chamada mantém-se igual à do Passo 2, muda apenas o valor de model:
const resposta = await ai.models.generateContent({
model: estado.tunedModel.model,
contents: "Qual é o prazo de entrega em Portugal Continental?",
});
console.log(resposta.text);A diferença prática, quando comparada com um prompt genérico no modelo base, costuma aparecer em dois pontos: consistência de tom (o modelo afinado tende a manter o estilo dos exemplos de treino) e menos necessidade de repetir instruções longas em cada pedido, já que o comportamento desejado ficou incorporado no próprio modelo.
Passo 8: Integrar o modelo afinado numa API Express
Para transformar isto num serviço utilizável, envolva a chamada num endpoint Express simples. Isto também é o ponto onde a maioria dos projetos reais adiciona limites de taxa e registo de erros.
import express from "express";
import { GoogleGenAI } from "@google/genai";
import "dotenv/config";
const app = express();
app.use(express.json());
const ai = new GoogleGenAI({
vertexai: true,
project: process.env.GCP_PROJECT,
location: "europe-west4",
});
const MODELO_AFINADO = process.env.TUNED_MODEL_ID;
app.post("/perguntar", async (req, res) => {
const { pergunta } = req.body;
if (!pergunta || pergunta.length > 500) {
return res.status(400).json({ erro: "Pergunta em falta ou demasiado longa." });
}
try {
const resposta = await ai.models.generateContent({
model: MODELO_AFINADO,
contents: pergunta,
});
res.json({ resposta: resposta.text });
} catch (e) {
console.error(e);
res.status(502).json({ erro: "Falha ao contactar o modelo." });
}
});
app.listen(3000, () => console.log("A correr em http://localhost:3000"));Exemplo de resposta esperada ao testar com curl -X POST http://localhost:3000/perguntar -H “Content-Type: application/json” -d ‘{“pergunta”:”Aceitam MB Way?”}’:
{"resposta":"Sim, aceitamos MB Way, Multibanco, cartão de crédito e PayPal em todas as encomendas para Portugal."}Passo 9: Avaliar a qualidade do modelo afinado
Um modelo afinado sem avaliação estruturada é um risco disfarçado de funcionalidade. Separe sempre uma fatia do dataset (por exemplo 15%) que nunca entra no treino, e use-a só para testar. Um script simples de comparação:
import { readFileSync } from "fs";
const validacao = readFileSync("validacao.jsonl", "utf-8").trim().split("\n").map(JSON.parse);
for (const exemplo of validacao) {
const resposta = await ai.models.generateContent({
model: MODELO_AFINADO,
contents: exemplo.text_input,
});
const parece_correta = resposta.text.toLowerCase().includes(
exemplo.output.toLowerCase().slice(0, 20)
);
console.log(exemplo.text_input, "->", parece_correta ? "OK" : "REVER");
}Isto é uma verificação superficial, útil como primeiro filtro. Para um caso de produção real, vale a pena complementar com revisão humana de uma amostra e, se a equipa já usa outras ferramentas de teste de LLMs, aplicar os mesmos critérios aqui.
Testes de regressão automatizados para o modelo afinado
A avaliação manual do Passo 9 resolve a primeira verificação, mas não escala. Assim que existir uma segunda versão do modelo (v2, depois v3), é preciso saber se a nova versão piorou algo que a anterior fazia bem. A solução é tratar o conjunto de validação como um conjunto de testes de regressão, correndo-o automaticamente sempre que um novo modelo é treinado, antes de o substituir em produção.
import { readFileSync, writeFileSync } from "fs";
async function testarVersao(modeloId, ficheiroValidacao) {
const casos = readFileSync(ficheiroValidacao, "utf-8").trim().split("\n").map(JSON.parse);
const resultados = [];
for (const caso of casos) {
const resposta = await ai.models.generateContent({
model: modeloId,
contents: caso.text_input,
});
resultados.push({
pergunta: caso.text_input,
esperado: caso.output,
obtido: resposta.text,
});
}
return resultados;
}
const versaoAnterior = await testarVersao("modelos/assistente-suporte-pt-v2", "validacao.jsonl");
const versaoNova = await testarVersao("modelos/assistente-suporte-pt-v3", "validacao.jsonl");
writeFileSync(
"comparacao-versoes.json",
JSON.stringify({ versaoAnterior, versaoNova }, null, 2)
);
console.log("Comparação guardada. Reveja manualmente antes de substituir em produção.");Este script não substitui a revisão humana, mas transforma-a num processo de comparação lado a lado em vez de um teste às cegas. Integre-o num pipeline de CI que corre sempre que um novo dataset é submetido a tuning, e bloqueie a promoção automática para produção sempre que a taxa de respostas corretas cair face à versão anterior. Equipas que já seguem esta disciplina com testes de código tradicional tendem a adaptar-se rápido a este padrão, porque a lógica é a mesma: nenhuma versão nova substitui a anterior sem primeiro passar no conjunto de testes.
Vale também registar as respostas divergentes num histórico separado. Com o tempo, esse histórico transforma-se na próxima ronda de exemplos de treino: perguntas em que o modelo falhou tornam-se, depois de corrigidas manualmente, novas linhas no dataset.jsonl da versão seguinte. É este ciclo – treinar, avaliar, registar falhas, treinar de novo – que separa um modelo afinado uma vez de um sistema que melhora de forma sustentada ao longo dos meses.
Passo 10: Controlar custos e limites de utilização
A tabela pública de preços da Gemini Developer API marca o preço de tuning como “Not available” nos modelos listados, ou seja, a Google não publica um valor fixo por token de treino diretamente na API de desenvolvedor. No Vertex AI, o custo faturável de treino é calculado como o número de tokens do dataset multiplicado pelo número de épocas, sujeito à tabela de preços vigente do Vertex AI. Depois do treino, cada chamada ao modelo afinado continua a ser cobrada à tarifa normal de inferência do modelo base.
| Item | Detalhe confirmado | Fonte |
|---|---|---|
| Preço de tuning na Gemini API | Não publicado (“Not available” na tabela) | ai.google.dev/gemini-api/docs/pricing |
| Cálculo de tokens faturáveis (Vertex AI) | Tokens do dataset × número de épocas | Documentação de tuning supervisionado Vertex AI |
| Limite de tokens por exemplo | 131.072 tokens (entrada + saída) | Documentação de tuning supervisionado Vertex AI |
| Limite de exemplos (texto) | Até 10 milhões | Documentação de tuning supervisionado Vertex AI |
| Limite de ficheiro JSONL | 1 GB | Documentação de tuning supervisionado Vertex AI |
| Jobs simultâneos | Quota por projeto, ampliável por pedido | Documentação de tuning supervisionado Vertex AI |
Se o custo de treino ainda assim preocupar a equipa, comece com um dataset pequeno (200 a 300 exemplos), confirme que o comportamento melhora, e só depois escale o volume de dados. É mais barato falhar cedo com um job pequeno do que descobrir um dataset mal formatado depois de submeter dez mil exemplos.
Exemplo prático de cálculo de custo
Como a Gemini Developer API não publica um preço fixo de tuning, o exercício mais útil é estimar o volume de tokens do seu próprio dataset antes de submeter o job. Um exemplo com números redondos: um dataset de 500 pares pergunta/resposta, com cerca de 60 tokens por exemplo (entrada mais saída), soma aproximadamente 30.000 tokens de treino. Com epochCount definido para 3, o número de tokens faturáveis sobe para cerca de 90.000 (30.000 tokens × 3 épocas), seguindo a fórmula publicada na documentação de estimativa de custos do Vertex AI.
Isto é uma fração ínfima dos limites máximos documentados (10 milhões de exemplos de texto, 131.072 tokens por exemplo), o que confirma que um projeto piloto como o deste tutorial fica bem longe de qualquer limite de quota. Depois de aplicado o preço vigente na tabela do Vertex AI para o modelo escolhido, o custo de treino de um dataset deste tamanho tende a ficar na casa de poucos dólares – o valor exato depende da tabela de preços em vigor no momento do job, que deve ser consultada diretamente na Cloud Console antes de confirmar.
A parte que mais pesa a médio prazo não é o treino, é a inferência recorrente. Se o assistente responder a 10.000 perguntas por mês, com uma média de 150 tokens de saída por resposta, isso são 1,5 milhões de tokens de output mensais, cobrados à tarifa normal de inferência do gemini-3.5-flash. Faça sempre esta conta antes de decidir entre um modelo afinado na nuvem da Google e um modelo aberto autogerido: para volumes baixos a médios, a simplicidade operacional do AI Studio costuma compensar; para volumes muito altos e previsíveis, vale a pena comparar com o custo de correr um modelo aberto em hardware próprio.
Passo 11: Versionar e reproduzir o pipeline de tuning
Um erro comum em projetos de ajuste fino é tratar o job de tuning como um evento único, sem guardar o dataset exato, a versão do modelo base e os parâmetros usados. Isso torna impossível repetir o treino mais tarde com um dataset atualizado. A prática simples que resolve isto: guarde o dataset.jsonl e um ficheiro de configuração no mesmo repositório do código da aplicação.
{
"baseModel": "gemini-3.5-flash",
"region": "europe-west4",
"epochCount": 3,
"datasetFile": "dataset.jsonl",
"datasetVersion": "2026-09-28",
"tunedModelDisplayName": "assistente-suporte-pt-v3"
}Ao incrementar a versão no nome do modelo (v1, v2, v3), evita substituir silenciosamente um modelo em produção por outro com comportamento diferente, e mantém a possibilidade de reverter para uma versão anterior se algo correr mal.
Passo 12: Colocar o modelo afinado em produção
Com a API Express a funcionar localmente, o último passo é publicá-la. As opções mais diretas para uma equipa pequena em Portugal passam por Cloud Run (mesmo ecossistema Google, integração simples com Vertex AI e faturação por utilização) ou qualquer VPS com Node.js e um proxy reverso à frente. Independentemente da escolha, mantenha três hábitos:
- Nunca exponha a chave da API ou as credenciais do projeto GCP no lado do cliente – todas as chamadas ao modelo devem passar pelo seu servidor.
- Registe (log) as perguntas e respostas de produção, com consentimento adequado ao RGPD, para alimentar a próxima ronda de ajuste fino.
- Defina um limite de taxa por utilizador, porque um modelo afinado ainda cobra por token de inferência tal como o modelo base.
Erros comuns e como evitá-los
Estes são os pontos onde a maioria dos leitores fica presa, por ordem de frequência.
- Dataset com formato inconsistente. Misturar o esquema text_input/output com o esquema de mensagens (messages com role/content) no mesmo ficheiro faz o job falhar sem aviso claro. Escolha um esquema e mantenha-o em todas as linhas.
- Região errada no bucket. Criar o bucket do Cloud Storage numa região diferente de us-central1 ou europe-west4 obriga a copiar os dados de novo antes de o tuning aceitar o ficheiro.
- Faturação não ativada no projeto. O AI Studio deixa criar a chave de API sem faturação, mas o job de tuning via Vertex AI rejeita o pedido até existir uma conta de faturação associada.
- Dataset demasiado pequeno ou repetitivo. Vinte exemplos quase idênticos não dão ao modelo variedade suficiente para generalizar; o resultado tende a decorar frases em vez de aprender o padrão.
- Ignorar o conjunto de validação. Sem um conjunto separado do treino, não há forma fiável de saber se o modelo melhorou ou apenas memorizou os exemplos.
Resolução de problemas: os 8 erros mais frequentes
1. Erro API_KEY_INVALID ao testar a chamada básica. A chave foi copiada com espaços extra ou pertence a um projeto diferente do que está ativo no terminal. Gere uma nova chave no AI Studio e confirme que o ficheiro .env não tem aspas à volta do valor.
2. Job de tuning fica preso em JOB_STATE_PENDING durante muito tempo. Normalmente é fila de capacidade na região escolhida. Espere mais tempo antes de cancelar, ou tente a outra região suportada (us-central1 ↔ europe-west4).
3. JOB_STATE_FAILED sem mensagem clara. Corra o script de validação do Passo 3 novamente sobre o ficheiro exato que foi carregado para o bucket – muitas vezes o ficheiro local difere do que ficou no Cloud Storage por causa de um upload incompleto.
4. Erro 403 PERMISSION_DENIED ao chamar tunings.tune. A conta de serviço ou o utilizador não tem a role Vertex AI User atribuída no projeto. Adicione a role em IAM & Admin na Cloud Console.
5. O modelo afinado responde pior do que o modelo base. Sinal de overfitting ou de dataset com respostas inconsistentes entre si. Reduza o número de épocas para 1 ou 2 e reveja se todas as respostas do dataset seguem o mesmo estilo.
6. RESOURCE_EXHAUSTED ao correr vários testes seguidos. A quota gratuita da Gemini Developer API tem limite de pedidos por minuto. Adicione um pequeno atraso entre chamadas ou peça aumento de quota na Cloud Console.
7. O bucket do Cloud Storage não é encontrado pelo job. Confirme que o URI começa por gs:// e que a conta de serviço do Vertex AI tem permissão de leitura sobre o bucket específico, não apenas sobre o projeto.
8. Respostas em inglês mesmo pedindo português. Isto acontece mais no modelo base do que no afinado. Inclua explicitamente exemplos em português europeu no dataset de treino – o modelo afinado tende a seguir o idioma predominante dos exemplos.
Dicas avançadas para quem já passou do primeiro modelo afinado
Depois do primeiro ciclo funcionar, há três ajustes que costumam trazer ganho real. Primeiro, experimente ajuste por preferências (preference tuning), disponível também no Vertex AI, em que em vez de um único output correto fornece um par de respostas (uma preferida, outra rejeitada) para a mesma pergunta – útil quando o problema não é “certo vs errado” mas sim “melhor vs pior” tom de resposta.
Segundo, use thinking_level em vez do antigo thinking_budget ao chamar modelos da família Gemini 3.x – é a recomendação atual da documentação para controlar o esforço de raciocínio do modelo sem penalizar a latência desnecessariamente. Terceiro, evite alterar temperature, top_p e top_k dos valores por omissão ao trabalhar com o gemini-3.5-flash: a própria documentação da Google recomenda mantê-los nos valores padrão, porque a capacidade de raciocínio do Gemini 3 foi otimizada para essa configuração.
Por fim, se a equipa cresce e o número de modelos afinados aumenta (um por cliente, por exemplo), automatize a criação de jobs a partir de um pipeline CI/CD em vez de correr o script manualmente – o padrão de versionar dataset e configuração do Passo 11 torna isso trivial de escalar.
Google AI Studio vs afinar modelos abertos: quando escolher cada um
Nem todo o projeto precisa de um modelo Gemini afinado. Um modelo aberto, ajustado localmente com ferramentas como Hugging Face ou Unsloth, continua a fazer mais sentido quando a prioridade é controlo total dos pesos, execução totalmente offline ou dados extremamente sensíveis que não podem sair da infraestrutura da empresa.
| Critério | Google AI Studio + Vertex AI | Modelos abertos (Hugging Face/Unsloth) |
|---|---|---|
| Infraestrutura | Gerida pela Google | Gerida pelo utilizador ou por um provedor de nuvem |
| Acesso aos pesos do modelo | Não disponível | Total, incluindo checkpoints e adaptadores |
| Complexidade inicial | Baixa – upload de dataset e job por API | Média a alta – requer escolher modelo, ambiente e pipeline |
| Hardware necessário | Nenhum, tudo gerido na nuvem Google | GPUs próprias ou serviço gerido pago à parte |
| Portabilidade do modelo final | Permanece no ecossistema Google | Pode ser exportado, quantizado e implantado noutro lugar |
| Melhor cenário de uso | Equipas pequenas que querem resultado rápido sem gerir infraestrutura | Casos com requisitos de execução local ou dados muito sensíveis |
A recomendação prática: comece pelo AI Studio se o objetivo é validar rapidamente se o ajuste fino resolve o problema. Só migre para um modelo aberto autogerido se, depois de validado, os custos de inferência a longo prazo ou requisitos de privacidade tornarem isso necessário.
Como migrar de prompt engineering para ajuste fino sem perder o que já funciona
Muitas equipas chegam a este tutorial já com um prompt de sistema longo, cheio de regras acumuladas ao longo de meses: “nunca prometas prazos abaixo de X”, “usa sempre este tom”, “para perguntas sobre Y, responde assim”. Migrar para um modelo afinado não significa deitar fora esse prompt – significa transformar cada regra numa série de exemplos concretos no dataset de treino.
Uma forma prática de fazer essa transição: mantenha o prompt de sistema atual em produção durante duas a três semanas, registando cada pergunta real e a resposta que o prompt gerou. Depois, reveja manualmente esse registo, corrija as respostas que ficaram fracas ou inconsistentes, e use o conjunto corrigido como base do dataset.jsonl do Passo 3. Isto garante que o modelo afinado aprende com perguntas reais dos seus utilizadores, não com exemplos artificiais inventados à pressa – e costuma produzir resultados bem mais sólidos do que escrever exemplos do zero.
Depois do primeiro modelo afinado em produção, não é preciso escolher entre prompt engineering e fine-tuning como se fossem mutuamente exclusivos. Um prompt de sistema curto, com uma ou duas regras que mudam com frequência (por exemplo, uma promoção sazonal), continua a fazer sentido por cima do modelo afinado – reserve o ajuste fino para o comportamento estável e estrutural, e o prompt de sistema para o que muda semana a semana.
Segurança e privacidade dos dados de treino
Antes de carregar qualquer dataset com dados reais de clientes, vale a pena ler os termos adicionais da Gemini API. Segundo esses termos, o conteúdo importado para a funcionalidade de tuning pode ser retido em associação com o modelo afinado, para permitir novo ajuste quando os modelos suportados mudarem, e apagar o modelo afinado também apaga o conteúdo de tuning relacionado. Na prática, isto significa que deve anonimizar ou pseudonimizar dados pessoais antes de os incluir no dataset, especialmente para cumprir o RGPD ao operar a partir de Portugal.
Evite também incluir segredos, chaves de API ou credenciais de teste dentro dos exemplos de treino – um modelo afinado pode, em teoria, reproduzir padrões memorizados do dataset em respostas futuras.
Projeto completo: estrutura final de ficheiros
No final deste tutorial, a pasta do projeto deve ter esta estrutura:
assistente-gemini/
├── .env
├── .gitignore
├── package.json
├── dataset.jsonl
├── validacao.jsonl
├── config-tuning.json
├── validar-dataset.js
├── criar-tuning.js
├── testar-modelo.js
└── servidor.jsEsta estrutura separa claramente a preparação de dados (dataset.jsonl, validacao.jsonl, validar-dataset.js), o processo de treino (criar-tuning.js, config-tuning.json) e o serviço final em produção (servidor.js). É esta separação que torna possível repetir o ciclo completo – atualizar o dataset, correr novo tuning, comparar com a versão anterior – sem reescrever a aplicação inteira a cada iteração.
Perguntas frequentes
O Google AI Studio é mesmo gratuito?
Sim, para experimentar prompts e gerar chaves de API a camada gratuita mantém-se ativa, incluindo acesso a modelos como o gemini-3.5-flash-lite. O ajuste supervisionado via Vertex AI, no entanto, exige um projeto Google Cloud com faturação ativada.
Preciso de saber Python para seguir este tutorial?
Não. Todos os exemplos usam Node.js e o SDK oficial @google/genai. O mesmo fluxo de tuning existe também em Python, se preferir essa linguagem.
Quanto tempo demora um job de ajuste fino?
A documentação oficial não garante uma duração fixa, porque depende do modelo, do número de exemplos e da fila da região. Para datasets de algumas centenas de exemplos, a experiência típica varia entre 20 minutos e cerca de 2 horas.
Posso afinar o Gemini 3.6 Flash?
Com base na documentação disponível em setembro de 2026, o suporte a ajuste supervisionado documentado está limitado ao gemini-3.1-flash-lite e ao gemini-3.5-flash. O Gemini 3.6 Flash está disponível para inferência, mas não há confirmação oficial de suporte a tuning supervisionado até à data.
Quantos exemplos preciso no mínimo para ver resultados?
Não existe um mínimo oficial publicado pela Google. Na prática, datasets entre 200 e 1.000 exemplos consistentes costumam já produzir diferenças percetíveis face ao modelo base, especialmente em tarefas de tom e formato de resposta.
O modelo afinado fica mais caro de usar do que o modelo base?
O custo de inferência do modelo afinado segue a tarifa aplicável ao modelo base equivalente. O custo extra fica apenas na fase de treino, calculado por tokens do dataset multiplicados pelo número de épocas.
Posso usar este processo para outro idioma além do português?
Sim. O processo de tuning é o mesmo independentemente do idioma; basta que o dataset de treino contenha exemplos no idioma pretendido, já que o modelo tende a seguir o idioma predominante dos exemplos fornecidos.
O que acontece se apagar o modelo afinado?
Segundo os termos adicionais da Gemini API, apagar o modelo afinado remove também o conteúdo de tuning associado a esse modelo específico. O dataset original, se guardado noutro local (como o bucket do Cloud Storage), não é afetado.
