Gemini Decisions API: testando o novo modelo de decisão do Google em latência e custo
Aprenda como o Gemini Decision 1 pontua opções fixas sem gerar texto, crie um classificador de intenção bancária com a Decisions API e compare com o Gemini 3.5 Flash-Lite em acurácia, latência, calibração e custo.
A maioria dos apps com LLMs é cheia de pequenas decisões: qual ferramenta o agente deve chamar? Qual modelo deve atender esta consulta? Esta mensagem viola alguma política?
Hoje, muitos times respondem a essas perguntas pedindo para um modelo generativo escrever a resposta em texto e depois fazem o parsing desse texto para tomar a decisão.
A Gemini Decisions API do Google propõe outra abordagem. Ela usa o modelo Gemini Decision 1 para pontuar um conjunto fixo de opções em um único forward pass e retorna uma probabilidade para cada opção, com zero tokens de saída cobrados.
Neste tutorial, vamos rodar a mesma tarefa de classificação de intenção em duas configurações:
Gemini Decision 1 via a Decisions API
Gemini 3.5 Flash-Lite via a Interactions API, com saída JSON estruturada
Vamos compará-los em acurácia, latência, uso de tokens, custo e calibração, e depois aumentar de 1 para 100 perguntas em uma única requisição.
Ao final deste tutorial, você vai saber como:
Chamar a Decisions API com perguntas choice e ler suas probabilidades e escores de confiança
Construir uma baseline generativa com a Interactions API e um schema JSON
Medir latência, uso de tokens e custo nas duas abordagens
Verificar se a confiança de um modelo é confiável usando um diagrama de confiabilidade e o erro de calibração esperado (ECE)
Decidir quando um modelo de decisão se encaixa melhor no seu app do que um generativo
Você pode rodar o código completo neste Google Colab.
Modelos de decisão vs. modelos generativos
Antes de ver como cada um funciona, vamos definir os dois termos.
Modelo generativo: produz conteúdo novo. Você fornece um prompt e ele escreve a resposta token por token. Essa resposta pode ser uma resposta, um resumo, um código ou um rótulo. O Gemini 3.5 Flash-Lite, como a maioria dos LLMs que usamos em apps de chat, é um modelo generativo.
Modelo de decisão: escolhe entre as opções que você define. Você passa um input e uma lista fixa de respostas possíveis, e ele retorna a probabilidade de cada opção sem escrever uma linha de texto. O Gemini Decision 1 é um modelo de decisão.
Veja um exemplo.
Um cliente escreve para um banco: "Meu cartão ainda não chegou. Quando vai chegar?"
Se você perguntar a um modelo generativo, "O que este cliente quer?", ele pode responder:
“O cliente está aguardando um novo cartão e quer saber quando ele vai chegar.”
É uma boa resposta para um humano ler. Mas se seu app precisa rotear a mensagem para o time certo, seu código agora tem que transformar essa frase em um rótulo. Você pode forçar um rótulo com um schema JSON, mas o modelo ainda escreve a resposta token por token.
Já se você perguntar a um modelo de decisão a mesma coisa, primeiro você passa as opções, como card_arrival, lost_or_stolen_card e exchange_rate. Ele retorna uma probabilidade para cada uma:
Seu código pode agir diretamente sobre essa probabilidade, roteando para o time de cartões se card_arrival estiver acima de um limite e mandando para um humano caso contrário. Em resumo:
Modelo generativo
Modelo de decisão
Retorna
Texto que ele escreve
Uma probabilidade para cada opção que você define
Respostas possíveis
Abertas
Conjunto fixo
Bom para
Respostas, resumos, explicações e extração
Roteamento, seleção de ferramentas, checagens de política e correção
Na prática, muitos apps usam um modelo generativo para as duas funções. É isso que vamos testar a seguir: se um modelo de decisão faz a parte de classificação melhor do que um modelo generativo.
Quando você usa um generativo como classificador, ele escreve a resposta token por token. Para uma resposta JSON como a nossa, a saída fica assim enquanto é gerada:
Cada token é um passo de decodificação separado, e cada token de saída é cobrado. Se você quiser um escore de confiança, o modelo também precisa escrever esse número. Esse número é o próprio palpite do modelo sobre si mesmo, não uma probabilidade medida de seus internos.
Um modelo de decisão, por sua vez, pula essa etapa de escrita. Você passa as opções de antemão e ele pontua todas contra o input em um único forward pass. O resultado é uma probabilidade para cada opção:
Latência: não há loop de decodificação, então a latência não deve crescer com o tamanho da resposta.
Custo: não há tokens de saída para cobrar. Você paga apenas pelos tokens de entrada, que incluem o texto da pergunta e as descrições das opções.
Confiança: a confiança vem das próprias probabilidades, então deve acompanhar a frequência com que o modelo acerta.
A troca é que você só pode fazer perguntas de conjunto fechado. Um modelo de decisão não explica sua resposta, não extrai valores nem escreve texto livre.
Demo: construindo um classificador de intenção bancária
Neste demo, vamos construir um classificador de intenção bancária. Usaremos a partição de teste do Banking77, um dataset público de mensagens de clientes rotuladas com 77 intenções, e manteremos 12 intenções que são fáceis de confundir entre si:
card_arrival e card_delivery_estimate
pending_card_payment, declined_card_payment e card_payment_fee_charged
pending_transfer, transfer_not_received_by_recipient e balance_not_updated_after_bank_transfer
lost_or_stolen_card, card_not_working, exchange_rate e top_up_failed
Intenções parecidas deixam a tarefa mais difícil, o que torna os escores de confiança mais interessantes de estudar.
Vamos rodar o classificador com ambos os modelos de duas formas:
Uma mensagem por requisição: 180 mensagens (15 por intenção), enviadas para cada modelo uma de cada vez.
Muitas perguntas por requisição: N mensagens em um input compartilhado, com uma pergunta por mensagem, para N = 1, 5, 10, 25, 50 e 100.
Aqui estão as configurações que mantemos iguais em ambos os modelos:
Configuração
Valor usado
Por quê
Modelo de decisão
gemini-decision-1
O modelo em teste
Modelo generativo
gemini-3.5-flash-lite
A baseline generativa econômica usada na comparação do post de lançamento
Temperatura do Flash-Lite
0.0
Remove ruído de amostragem da baseline
Nível de thinking do Flash-Lite
minimal
Mantém a comparação sobre decodificação, não raciocínio
Formato de saída
Schema JSON com um enum das 12 labels
O Flash-Lite só pode retornar um rótulo válido
Descrições das opções
Uma frase curta por intenção
Ambos os modelos veem as mesmas definições de rótulo
Chamadas de aquecimento
2 por modelo
Tira a configuração de conexão das medições
Repetições (muitas perguntas por requisição)
3 por configuração
Relatamos a mediana, não uma única execução
Observação: estas são configurações funcionais para este demo, não configurações otimizadas para nenhum dos modelos.
A Decisions API tem uma camada sem custo no Google AI Studio para prototipagem, então você pode testar antes de pagar. Eu rodei este demo no Colab, mas use qualquer ambiente Python 3 à vontade.
Aqui, google-genai é o SDK Python do Google para a Gemini API. Ele fornece os métodos client.decisions.create e client.interactions.create, que enviam requisições para a Decisions API e a Interactions API. Usamos pandas para carregar o dataset e organizar resultados, e matplotlib para gerar gráficos.
Em seguida, criamos o client. A Decisions API requer a versão v1beta da API:
import os, time, json
import numpy as np
import pandas as pd
from google import genai
client = genai.Client(
api_key=os.environ["GEMINI_API_KEY"],
http_options={"api_version":"v1beta"},)
DECISION_MODEL ="gemini-decision-1"
GEN_MODEL ="gemini-3.5-flash-lite"Tecnologia
Aqui, genai.Client() lê a chave de API de GEMINI_API_KEY definida nos segredos do Colab ou como variável de ambiente, e http_options aponta para a API v1beta, onde está a Decisions API.
Depois, vamos carregar o dataset Banking77 e definir nossas 12 intenções. Cada intenção recebe uma descrição de uma sentença que ambos os modelos verão:
BANKING77_URL =("https://raw.githubusercontent.com/PolyAI-LDN/task-specific-datasets/master/banking_data/test.csv")
INTENTS ={"card_arrival":"The customer is asking where their new card is or why it has not arrived yet.","card_delivery_estimate":"The customer wants to know how long card delivery usually takes.","lost_or_stolen_card":"The customer's card was lost or stolen.",# ... 9 more intents}
LABELS =list(INTENTS)
df = pd.read_csv(BANKING77_URL)
df = df[df["category"].isin(LABELS)].reset_index(drop=True)
sample =(
df.groupby("category").sample(n=15, random_state=42).sample(frac=1, random_state=42).reset_index(drop=True))Tecnologia
O trecho acima faz o download da partição de teste do Banking77 em CSV e mantém apenas as linhas rotuladas com uma das nossas 12 intenções. Em seguida, amostra 15 mensagens por intenção com semente fixa, para você obter a mesma amostra em toda execução. O .sample(frac=1) final embaralha as linhas para misturar as intenções.
Isso nos dá 180 mensagens, 15 por intenção.
Etapa 2: classificar com a Decisions API
Uma pergunta choice recebe um dicionário que mapeia cada ID de opção para uma descrição. Passamos a mensagem como input e fazemos uma pergunta, com chave intent:
defdecide_intent(text):
start = time.perf_counter()
result = client.decisions.create(
model=DECISION_MODEL,input=text,
questions={"intent":{"type":"choice","instructions":"Which intent best describes this banking customer message?","criteria": INTENTS,}},)
latency = time.perf_counter()- start
ans = result.answers["intent"]return{"pred": ans.choice,"confidence":float(ans.confidence),"probabilities":dict(ans.probabilities),"latency_s": latency,"input_tokens": result.usage.total_input_tokens,"output_tokens": result.usage.total_output_tokens,}Tecnologia
A função decide_intent() envia uma mensagem como input e uma pergunta choice com nossas 12 intenções como opções. Medimos o tempo com time.perf_counter() e lemos da resposta a opção escolhida, a confiança, as probabilidades de todas as opções e a contagem de tokens.
Cada resposta traz três campos:
choice: a opção com maior probabilidade
probabilities: uma probabilidade por opção, somando 1
confidence: a probabilidade estimada de que a resposta principal esteja correta
O objeto usage relata tokens de entrada, e total_output_tokens é sempre 0.
Veja o resultado para a primeira mensagem da nossa amostra:
O modelo confundiu duas intenções parecidas, mas a confiança de 0,846 indica alguma incerteza. A boa notícia é que a intenção correta, card_arrival, veio em segundo lugar com quase toda a probabilidade restante (cerca de 0,15). As demais opções ficaram perto de zero.
Etapa 3: classificar com o Flash-Lite
Para a baseline generativa, usamos saída estruturada com um enum das mesmas 12 labels, para que o Flash-Lite só consiga retornar um rótulo válido. Também pedimos uma confiança entre 0 e 1, que é como a maioria dos apps obtém um escore de confiança de um modelo generativo:
LABEL_LIST ="\n".join(f"- {k}: {v}"for k, v in INTENTS.items())
GEN_SCHEMA ={"type":"object","properties":{"intent":{"type":"string","enum": LABELS},"confidence":{"type":"number"},},"required":["intent","confidence"],}defgenerate_intent(text):
prompt =("Which intent best describes this banking customer message?\n\n"f"Intents:\n{LABEL_LIST}\n\n"f"Message: {text}\n\n""Return the intent and your confidence from 0 to 1.")
start = time.perf_counter()
interaction = client.interactions.create(
model=GEN_MODEL,input=prompt,
response_format={"type":"text","mime_type":"application/json","schema": GEN_SCHEMA,},
generation_config={"temperature":0.0,"thinking_level":"minimal"},
store=False,)
latency = time.perf_counter()- start
parsed = json.loads(interaction.output_text)return{"pred": parsed["intent"],"confidence":float(parsed["confidence"]),"latency_s": latency,"input_tokens": interaction.usage.total_input_tokens,"output_tokens": interaction.usage.total_output_tokens,"thought_tokens": interaction.usage.total_thought_tokens,}Tecnologia
A função generate_intent() monta um prompt com as 12 intenções e suas descrições. Ela chama o Flash-Lite com response_format definido para o nosso schema JSON, então a saída deve ser um JSON válido com uma das 12 labels. A temperatura é 0 com nível de thinking minimal para manter a resposta estável e curta. Depois fazemos o parse de interaction.output_text com json.loads() e lemos as contagens de tokens em interaction.usage.
Testei a mesma mensagem da etapa anterior no Flash-Lite e ele cometeu o mesmo erro com confiança mais alta:
Os thinking tokens são 0, o que confirma que o minimal manteve o Flash-Lite apenas escrevendo a resposta. O Flash-Lite usou menos tokens de entrada do que o Decision 1 (277 vs. 337) porque a Decisions API conta as descrições das opções dentro da pergunta como input.
Etapa 4: classificar uma mensagem por requisição
Agora, vamos enviar as 180 mensagens para ambos os modelos, uma requisição por vez, após duas chamadas de aquecimento para cada um:
rows =[]for i, r in sample.iterrows():for model_name, fn in(("decision", decide_intent),("generative", generate_intent)):
out = fn(r["text"])
rows.append({"model": model_name,"gold": r["category"],"pred": out["pred"],"confidence": out["confidence"],"latency_s": out["latency_s"],"input_tokens": out["input_tokens"],"output_tokens": out["output_tokens"],})
exp1 = pd.DataFrame(rows)
exp1["correct"]= exp1["pred"]== exp1["gold"]Tecnologia
Esse loop envia cada mensagem para as duas funções e salva a predição, a confiança, a latência e as contagens de tokens em uma linha. Depois transformamos as linhas em um DataFrame e adicionamos a coluna correct que marca se a predição bate com o rótulo verdadeiro.
Aqui estão os resultados:
Métrica
Gemini Decision 1
Gemini 3.5 Flash-Lite
Acurácia
84,4%
83,9%
Latência mediana
325 ms
1.068 ms
Latência p90
412 ms
6.483 ms
Requisição mais lenta
1,0 s
101,6 s
Requisições acima de 5 s
0 de 180
33 de 180
Média de tokens de entrada
339
279
Média de tokens de saída
0
25
Três aprendizados a partir dessas métricas:
Acurácia: os dois modelos foram praticamente equivalentes.
Latência: o Decision 1 foi cerca de 3x mais rápido na mediana e muito mais consistente, enquanto o Flash-Lite teve uma cauda longa de requisições lentas.
Tokens: o Decision 1 usou mais tokens de entrada porque as descrições das opções contam como input, mas não gerou tokens de saída.
Observação: nosso tempo inclui a ida e volta de rede do Colab, então trate essa diferença como dependente do setup.
Etapa 5: verificar a calibração
Acurácia diz com que frequência um modelo acerta, mas calibração diz se a confiança dele significa algo ou não. Um modelo está bem calibrado quando sua confiança bate com sua acurácia; ou seja, se ele diz 0,8 em um grupo de respostas, cerca de 80% delas devem estar corretas.
Para medir isso, agrupamos as predições em 10 faixas de confiança e comparamos a confiança média de cada faixa com sua acurácia. O erro de calibração esperado (ECE) é o gap médio ponderado pela quantidade de predições em cada faixa. Quanto menor, melhor.
defece(conf, correct, n_bins=10):
conf = np.asarray(conf, dtype=float)
correct = np.asarray(correct, dtype=float)
edges = np.linspace(0,1, n_bins +1)
ids = np.clip(np.digitize(conf, edges[1:-1]),0, n_bins -1)
total =0.0for b inrange(n_bins):
mask = ids == b
if mask.sum():
total += mask.mean()*abs(conf[mask].mean()- correct[mask].mean())return totalTecnologia
A função ece() coloca cada predição em uma de 10 faixas por confiança (0 a 0,1; 0,1 a 0,2; e assim por diante). Para cada faixa, calcula o gap entre a confiança média e a acurácia, pondera pela participação de predições naquela faixa e soma os resultados.
Veja como os dois modelos se comparam:
Métrica
Gemini Decision 1
Gemini 3.5 Flash-Lite
Acurácia
84,4%
83,9%
Confiança média
0,867
0,957
ECE
0,050
0,124
Confiança média quando acerta
0,901
0,966
Confiança média quando erra
0,686
0,912
Figura: diagramas de confiabilidade para ambos os modelos
A confiança do Decision 1 fica próxima da sua acurácia, com ECE de 0,050. Ela também é visivelmente menor quando o modelo erra (0,686) do que quando acerta (0,901).
O Flash-Lite é superconfiante. Reporta em média 0,957 enquanto acerta 83,9% das vezes. Ele usou apenas 9 valores distintos de confiança em 180 respostas, e 158 delas foram 0,95 ou mais. Mesmo as respostas erradas ficaram em média 0,912. O número parece uma probabilidade, mas é a própria estimativa do modelo escrita em texto.
Calibração importa quando você age com base no escore. Um padrão comum é aceitar respostas acima de um limite de confiança e enviar o restante para um modelo de fallback ou um humano:
Limite
Decision 1: % mantida
Decision 1: acurácia nas mantidas
Flash-Lite: % mantida
Flash-Lite: acurácia nas mantidas
0,50
94,4%
85,9%
99,4%
84,4%
0,70
78,3%
92,2%
98,9%
84,3%
0,80
74,4%
93,3%
98,9%
84,3%
0,90
63,3%
95,6%
88,9%
87,5%
0,95
53,9%
96,9%
87,8%
87,3%
Com o Decision 1, um limite mais alto funciona como esperado. Em 0,9, ele mantém 63% das mensagens com 95,6% de acurácia. Com o Flash-Lite, o limite quase não ajuda, porque a maioria das respostas erradas também tem confiança alta. A documentação oficial recomenda escolher um limite a partir de exemplos rotulados do seu próprio tráfego.
Etapa 6: classificar 100 mensagens em uma requisição
A Decisions API pode responder até 1.000 perguntas sobre um input compartilhado em uma única requisição. Para testar isso, colocamos N mensagens de clientes em um input e fazemos uma pergunta por mensagem.
Para o Decision 1, isso significa N perguntas choice com as chaves de m1 a mN:
defbuild_batch(n):
msgs = pool.iloc[:n]
shared ="Banking customer messages:\n"+"".join(f"Message {i +1}: {t}\n"for i, t inenumerate(msgs["text"]))return shared,list(msgs["category"])defdecide_batch(n):
shared, gold = build_batch(n)
questions ={f"m{i +1}":{"type":"choice","instructions":f"Which intent best describes Message {i +1}?","criteria": INTENTS,}for i inrange(n)}
result = client.decisions.create(
model=DECISION_MODEL,input=shared, questions=questions
)
preds =[result.answers[f"m{i +1}"].choice for i inrange(n)]return preds, gold, result.usageTecnologia
Aqui, a função build_batch() numera as primeiras N mensagens e as junta em um input compartilhado. Depois, decide_batch() cria uma pergunta choice por mensagem, com chave de m1 a mN, envia tudo em uma única requisição e lê uma resposta por chave.
Para o Flash-Lite, enviamos o mesmo input compartilhado com um schema JSON que tem N campos, cada um limitado às 12 labels. Cada N usa as mesmas mensagens para ambos os modelos, e cada configuração roda três vezes.
Perguntas por requisição
Decision 1: latência mediana
Flash-Lite: latência mediana
Decision 1: tokens de entrada
Flash-Lite: tokens de entrada / saída
1
318 ms
888 ms
344
291 / 14
5
353 ms
858 ms
1.554
369 / 64
10
398 ms
1.063 ms
3.056
456 / 129
25
546 ms
2.753 ms
7.570
710 / 350
50
592 ms
Falhou
15.100
Falhou
100
59.095 ms
Falhou
30.309
Falhou
Até 25 perguntas, a latência mediana do Decision 1 ficou abaixo de 550 ms. A mediana do Flash-Lite cresceu com N, de menos de 1 s em 1 a 5 perguntas para 2,75 s em 25, porque ele precisa escrever cada resposta como tokens de saída. Mesmo com 50 perguntas, a mediana do Decision 1 foi 592 ms, embora uma das três execuções tenha levado 70 s.
Dois pontos para refletir:
O Flash-Lite falhou em 50 e 100 perguntas: as linhas "Falhou" na tabela acima são todas o mesmo erro 400. Indicam que o schema "tem estados demais para servir". Um schema com 50 ou mais campos, cada um limitado a 12 labels, excede o que a API aceita.
O Decision 1 desacelerou em 100 perguntas: cada pergunta repete todas as 12 descrições de opção, cerca de 300 tokens por pergunta, então a requisição chegou a 30.309 tokens, enquanto a promessa de latência plana do Google cobre contextos de até 16K tokens.
Etapa 7: enxugar as requisições
Agora surge a pergunta óbvia: dá para corrigir a lentidão e as falhas? Para o Decision 1, usamos descrições vazias (""). Para o Flash-Lite, pedimos uma única lista de N rótulos em vez de N campos separados:
# Decision 1: apenas IDs das opções, sem descrições"criteria":{k:""for k in LABELS}# Flash-Lite: um campo de lista em vez de N campos
schema ={"type":"object","properties":{"intents":{"type":"array","items":{"type":"string","enum": LABELS},"minItems": n,"maxItems": n,}},"required":["intents"],}Tecnologia
Veja como o Decision 1 se saiu com descrições vazias:
Perguntas por requisição
Latência mediana
Acurácia
Tokens de entrada
25
357 ms
84,0%
3.995
50
649 ms
78,0%
7.950
100
1.603 ms
83,0%
16.009
Remover as descrições praticamente cortou pela metade os tokens de entrada. Em 100 perguntas, a requisição caiu para cerca de 16K tokens e a latência mediana foi de 59 s para 1,6 s. A acurácia caiu um pouco em 25 e 50 perguntas, então descrições curtas são um meio-termo melhor do que nenhuma, principalmente para intenções semelhantes.
O schema em lista não ajudou o modelo Flash-Lite. Ele funcionou com 25 perguntas, mas continuou falhando em 50 e 100.
Etapa 8: comparar custos
Por fim, calculamos o custo a partir das contagens de tokens que cada API retorna, usando preços do tier pago:
A função cost_per_request() multiplica cada contagem de tokens pelo preço por 1M de tokens. Para o Decision 1, só tokens de entrada contam. Para o Flash-Lite, thinking tokens são cobrados como tokens de saída, então somamos aos de saída.
Aqui está o custo por 1.000 requisições em cada setup:
Setup
Gemini Decision 1
Gemini 3.5 Flash-Lite
Flash-Lite / Decision 1
1 mensagem por requisição
US$ 0,034
US$ 0,147
4,3x
5 perguntas por requisição
US$ 0,155
US$ 0,271
1,7x
10 perguntas por requisição
US$ 0,306
US$ 0,459
1,5x
25 perguntas por requisição
US$ 0,757
US$ 1,088
1,4x
25 perguntas, setups enxutos (Etapa 7)
US$ 0,400
US$ 0,831
2,1x
50 perguntas por requisição
US$ 1,510
Falhou
n/d
100 perguntas, descrições vazias
US$ 1,601
Falhou
n/d
Em mensagens únicas, o Decision 1 foi 4,3x mais barato, mas a diferença diminui conforme você agrupa mais perguntas na mesma requisição. O input compartilhado é cobrado uma vez em ambas as APIs. Porém, cada pergunta no Decision 1 carrega sua própria instrução e todas as 12 descrições de opção, enquanto o Flash-Lite vê a lista de labels apenas uma vez e paga por uma saída curta por resposta. Em 25 perguntas, o Decision 1 usou 7.570 tokens de entrada contra 710 de entrada e 350 de saída do Flash-Lite.
Observação: a Decisions API não suporta cache de contexto nem a Batch API. Se você enviar o mesmo input em várias requisições, ele será cobrado integralmente em cada uma. Portanto, quando tiver muitas perguntas sobre o mesmo input, faça todas em uma única chamada em vez de espalhá-las.
Quando usar cada abordagem
Com base nas execuções acima, um modelo de decisão é a melhor opção quando:
A resposta vem de um conjunto fixo de opções, como intenções, rotas, ferramentas ou rótulos de política
A decisão está no caminho da requisição, onde todo usuário espera por ela
Você quer agir com base na confiança, por exemplo, enviando casos incertos para fallback ou para um humano
Você precisa fazer muitas perguntas independentes sobre o mesmo input em uma requisição
Um modelo generativo ainda é a melhor opção quando:
Você precisa de uma explicação, de extrair um valor ou de qualquer texto livre
O conjunto de respostas possíveis é aberto ou muda por requisição
Você já fez uma chamada generativa para aquele input e pode incluir a classificação nela
Use a Decisions API quando precisar de
Use a Interactions API quando precisar de
Uma probabilidade sim/não, uma opção de um conjunto fixo ou uma nota em escala fixa
Texto gerado, resumos ou explicações
Probabilidades calibradas que você pode limiar
Valores extraídos ou objetos que seguem seu próprio schema JSON
Muitas verificações independentes sobre o mesmo input em uma chamada
Chamadas de ferramenta com argumentos
Baixa latência e custo zero de tokens de saída
Raciocínio em múltiplas etapas
Considerações finais
Neste tutorial, construímos um classificador de intenção bancária com o Gemini Decision 1 e o Gemini 3.5 Flash-Lite, e então calculamos acurácia, latência, calibração e custo para comparar os dois modelos. Quatro conclusões:
Acurácia empatou: 84,4% para o Decision 1 e 83,9% para o Flash-Lite, com o mesmo veredito em 163 de 180 mensagens.
O Decision 1 foi mais rápido e previsível: sua latência mediana foi 325 ms contra 1.068 ms, e sua requisição mais lenta levou 1,0 s contra 101,6 s.
A confiança do Decision 1 foi utilizável: seu ECE foi 0,050 contra 0,124, e elevar o limite para 0,9 aumentou a acurácia nas respostas mantidas de 84,4% para 95,6%. A confiança auto-relatada do Flash-Lite mal separou acertos de erros.
Custo e escala dependem de como você escreve as perguntas: o Decision 1 foi 4,3x mais barato em mensagens únicas, mas cada pergunta paga por suas descrições de opções. Então, mantenha o total de input abaixo de ~16K tokens e deixe as descrições curtas.
Estes resultados vêm de uma tarefa, um dataset e poucas execuções em um notebook do Colab. Trate-os como observações de um demo, não como afirmações gerais de performance.
Sou Especialista Google Developers em ML (Gen AI), tricampeã no Kaggle e Embaixadora Women Techmakers, com mais de três anos de experiência na área de tecnologia. Cofundei uma startup de saúde em 2020 e atualmente faço um mestrado em ciência da computação na Georgia Tech, com foco em aprendizado de máquina.
FAQs
Qual a diferença entre a Decisions API e uma API generativa?⌄
Uma API generativa escreve sua resposta token por token e cobra cada token de saída. A Decisions API pontua um conjunto fixo de opções em um único forward pass e retorna uma probabilidade para cada uma. Ela não gera tokens de saída, então você paga só pelo input.
O Gemini Decision 1 é mais preciso que o Gemini 3.5 Flash-Lite?⌄
Não no nosso teste. Em 180 mensagens bancárias, a acurácia foi 84,4% para o Decision 1 e 83,9% para o Flash-Lite. As diferenças medidas foram em latência, calibração e custo.
Por que o Decision 1 usa mais tokens de entrada do que o Flash-Lite?⌄
A instrução de cada pergunta e as descrições das opções contam como input. Com 12 opções descritas, isso adicionou cerca de 300 tokens por pergunta no nosso teste. Descrições curtas ou vazias reduzem isso.
A latência se mantém estável conforme adiciono mais perguntas?⌄
Nos nossos testes, a mediana ficou abaixo de 650 ms até 50 perguntas. Em 100 perguntas com descrições completas das opções, a requisição chegou a ~30K tokens e levou de 48 a 59 s. Com descrições vazias, as mesmas 100 perguntas caberam em ~16K tokens e levaram 1,6 s.
Quais tipos de pergunta a Decisions API suporta?⌄
A Decisions API suporta três tipos de pergunta, incluindo noul para verificações sim/não, choice para escolher uma opção entre 2 e 255, e score para atribuir nota em uma rubrica ordenada. Você pode misturar os três em uma única requisição.
GPT-4 alternativas de código aberto que podem oferecer desempenho semelhante e exigem menos recursos computacionais para serem executadas. Esses projetos vêm com instruções, fontes de código, pesos de modelos, conjuntos de dados e interface de usuário do chatbot.
Descubra a atualização mais recente da OpenAI, GPT-4 Turbo com visão, e seus principais recursos, incluindo o corte de conhecimento aprimorado, uma janela de contexto expandida, preço acessível e muito mais.
Explore o GPT-3.5 Turbo e descubra o potencial transformador do ajuste fino. Saiba como personalizar esse modelo de linguagem avançado para aplicativos de nicho, aprimorar seu desempenho e entender os custos associados, a segurança e as considerações de privacidade.
O DeepSeek-Coder-V2 é um modelo de linguagem de código de código aberto que rivaliza com o desempenho do GPT-4, Gemini 1.5 Pro, Claude 3 Opus, Llama 3 70B ou Codestral.
Domine o Gemini e o NotebookLM para automatizar tarefas, aumentar a produtividade e trabalhar de forma mais inteligente em todo o ecossistema de IA do Google.
Analyze data smarter with Gemini in Google Sheets. Use AI-powered insights, formula suggestions, and automation to simplify spreadsheets and boost productivity.
A maioria dos apps com LLMs é cheia de pequenas decisões: qual ferramenta o agente deve chamar? Qual modelo deve atender esta consulta? Esta mensagem viola alguma política?
Hoje, muitos times respondem a essas perguntas pedindo para um modelo generativo escrever a resposta em texto e depois fazem o parsing desse texto para tomar a decisão.
A Gemini Decisions API do Google propõe outra abordagem. Ela usa o modelo Gemini Decision 1 para pontuar um conjunto fixo de opções em um único forward pass e retorna uma probabilidade para cada opção, com zero tokens de saída cobrados.
Neste tutorial, vamos rodar a mesma tarefa de classificação de intenção em duas configurações:
Vamos compará-los em acurácia, latência, uso de tokens, custo e calibração, e depois aumentar de 1 para 100 perguntas em uma única requisição.
Ao final deste tutorial, você vai saber como:
Chamar a Decisions API com perguntas
choicee ler suas probabilidades e escores de confiançaConstruir uma baseline generativa com a Interactions API e um schema JSON
Medir latência, uso de tokens e custo nas duas abordagens
Verificar se a confiança de um modelo é confiável usando um diagrama de confiabilidade e o erro de calibração esperado (ECE)
Decidir quando um modelo de decisão se encaixa melhor no seu app do que um generativo
Você pode rodar o código completo neste Google Colab.
Modelos de decisão vs. modelos generativos
Antes de ver como cada um funciona, vamos definir os dois termos.
Veja um exemplo.
Um cliente escreve para um banco: "Meu cartão ainda não chegou. Quando vai chegar?"
Se você perguntar a um modelo generativo, "O que este cliente quer?", ele pode responder:
“O cliente está aguardando um novo cartão e quer saber quando ele vai chegar.”
É uma boa resposta para um humano ler. Mas se seu app precisa rotear a mensagem para o time certo, seu código agora tem que transformar essa frase em um rótulo. Você pode forçar um rótulo com um schema JSON, mas o modelo ainda escreve a resposta token por token.
Já se você perguntar a um modelo de decisão a mesma coisa, primeiro você passa as opções, como
card_arrival,lost_or_stolen_cardeexchange_rate. Ele retorna uma probabilidade para cada uma:Seu código pode agir diretamente sobre essa probabilidade, roteando para o time de cartões se
card_arrivalestiver acima de um limite e mandando para um humano caso contrário. Em resumo:Modelo generativo
Modelo de decisão
Retorna
Texto que ele escreve
Uma probabilidade para cada opção que você define
Respostas possíveis
Abertas
Conjunto fixo
Bom para
Respostas, resumos, explicações e extração
Roteamento, seleção de ferramentas, checagens de política e correção
Na prática, muitos apps usam um modelo generativo para as duas funções. É isso que vamos testar a seguir: se um modelo de decisão faz a parte de classificação melhor do que um modelo generativo.
Quando você usa um generativo como classificador, ele escreve a resposta token por token. Para uma resposta JSON como a nossa, a saída fica assim enquanto é gerada:
Cada token é um passo de decodificação separado, e cada token de saída é cobrado. Se você quiser um escore de confiança, o modelo também precisa escrever esse número. Esse número é o próprio palpite do modelo sobre si mesmo, não uma probabilidade medida de seus internos.
Um modelo de decisão, por sua vez, pula essa etapa de escrita. Você passa as opções de antemão e ele pontua todas contra o input em um único forward pass. O resultado é uma probabilidade para cada opção:
Isso muda três coisas que você pode medir:
A troca é que você só pode fazer perguntas de conjunto fechado. Um modelo de decisão não explica sua resposta, não extrai valores nem escreve texto livre.
Demo: construindo um classificador de intenção bancária
Neste demo, vamos construir um classificador de intenção bancária. Usaremos a partição de teste do Banking77, um dataset público de mensagens de clientes rotuladas com 77 intenções, e manteremos 12 intenções que são fáceis de confundir entre si:
card_arrivalecard_delivery_estimatepending_card_payment,declined_card_paymentecard_payment_fee_chargedpending_transfer,transfer_not_received_by_recipientebalance_not_updated_after_bank_transferlost_or_stolen_card,card_not_working,exchange_rateetop_up_failedIntenções parecidas deixam a tarefa mais difícil, o que torna os escores de confiança mais interessantes de estudar.
Vamos rodar o classificador com ambos os modelos de duas formas:
Aqui estão as configurações que mantemos iguais em ambos os modelos:
Configuração
Valor usado
Por quê
Modelo de decisão
gemini-decision-1O modelo em teste
Modelo generativo
gemini-3.5-flash-liteA baseline generativa econômica usada na comparação do post de lançamento
Temperatura do Flash-Lite
0.0
Remove ruído de amostragem da baseline
Nível de thinking do Flash-Lite
minimalMantém a comparação sobre decodificação, não raciocínio
Formato de saída
Schema JSON com um
enumdas 12 labelsO Flash-Lite só pode retornar um rótulo válido
Descrições das opções
Uma frase curta por intenção
Ambos os modelos veem as mesmas definições de rótulo
Chamadas de aquecimento
2 por modelo
Tira a configuração de conexão das medições
Repetições (muitas perguntas por requisição)
3 por configuração
Relatamos a mediana, não uma única execução
Observação: estas são configurações funcionais para este demo, não configurações otimizadas para nenhum dos modelos.
Etapa 1: pré-requisitos e setup
Para acompanhar, você precisa de:
Uma chave da Gemini API do Google AI Studio
Um notebook Colab (ou qualquer ambiente Python 3)
google-genaiversão 3.2 ou superiorA Decisions API tem uma camada sem custo no Google AI Studio para prototipagem, então você pode testar antes de pagar. Eu rodei este demo no Colab, mas use qualquer ambiente Python 3 à vontade.
Vamos começar instalando os pacotes:
Aqui,
google-genaié o SDK Python do Google para a Gemini API. Ele fornece os métodosclient.decisions.createeclient.interactions.create, que enviam requisições para a Decisions API e a Interactions API. Usamospandaspara carregar o dataset e organizar resultados, ematplotlibpara gerar gráficos.Em seguida, criamos o client. A Decisions API requer a versão v1beta da API:
Aqui,
genai.Client()lê a chave de API deGEMINI_API_KEYdefinida nos segredos do Colab ou como variável de ambiente, ehttp_optionsaponta para a API v1beta, onde está a Decisions API.Depois, vamos carregar o dataset Banking77 e definir nossas 12 intenções. Cada intenção recebe uma descrição de uma sentença que ambos os modelos verão:
O trecho acima faz o download da partição de teste do Banking77 em CSV e mantém apenas as linhas rotuladas com uma das nossas 12 intenções. Em seguida, amostra 15 mensagens por intenção com semente fixa, para você obter a mesma amostra em toda execução. O
.sample(frac=1)final embaralha as linhas para misturar as intenções.Isso nos dá 180 mensagens, 15 por intenção.
Etapa 2: classificar com a Decisions API
Uma pergunta
choicerecebe um dicionário que mapeia cada ID de opção para uma descrição. Passamos a mensagem comoinpute fazemos uma pergunta, com chaveintent:A função
decide_intent()envia uma mensagem comoinpute uma perguntachoicecom nossas 12 intenções como opções. Medimos o tempo comtime.perf_counter()e lemos da resposta a opção escolhida, a confiança, as probabilidades de todas as opções e a contagem de tokens.Cada resposta traz três campos:
choice: a opção com maior probabilidadeprobabilities: uma probabilidade por opção, somando 1confidence: a probabilidade estimada de que a resposta principal esteja corretaO objeto
usagerelata tokens de entrada, etotal_output_tokensé sempre 0.Veja o resultado para a primeira mensagem da nossa amostra:
O modelo confundiu duas intenções parecidas, mas a confiança de 0,846 indica alguma incerteza. A boa notícia é que a intenção correta,
card_arrival, veio em segundo lugar com quase toda a probabilidade restante (cerca de 0,15). As demais opções ficaram perto de zero.Etapa 3: classificar com o Flash-Lite
Para a baseline generativa, usamos saída estruturada com um
enumdas mesmas 12 labels, para que o Flash-Lite só consiga retornar um rótulo válido. Também pedimos uma confiança entre 0 e 1, que é como a maioria dos apps obtém um escore de confiança de um modelo generativo:A função
generate_intent()monta um prompt com as 12 intenções e suas descrições. Ela chama o Flash-Lite comresponse_formatdefinido para o nosso schema JSON, então a saída deve ser um JSON válido com uma das 12 labels. A temperatura é0com nível de thinkingminimalpara manter a resposta estável e curta. Depois fazemos o parse deinteraction.output_textcomjson.loads()e lemos as contagens de tokens eminteraction.usage.Testei a mesma mensagem da etapa anterior no Flash-Lite e ele cometeu o mesmo erro com confiança mais alta:
Os thinking tokens são 0, o que confirma que o
minimalmanteve o Flash-Lite apenas escrevendo a resposta. O Flash-Lite usou menos tokens de entrada do que o Decision 1 (277 vs. 337) porque a Decisions API conta as descrições das opções dentro da pergunta como input.Etapa 4: classificar uma mensagem por requisição
Agora, vamos enviar as 180 mensagens para ambos os modelos, uma requisição por vez, após duas chamadas de aquecimento para cada um:
Esse loop envia cada mensagem para as duas funções e salva a predição, a confiança, a latência e as contagens de tokens em uma linha. Depois transformamos as linhas em um DataFrame e adicionamos a coluna
correctque marca se a predição bate com o rótulo verdadeiro.Aqui estão os resultados:
Métrica
Gemini Decision 1
Gemini 3.5 Flash-Lite
Acurácia
84,4%
83,9%
Latência mediana
325 ms
1.068 ms
Latência p90
412 ms
6.483 ms
Requisição mais lenta
1,0 s
101,6 s
Requisições acima de 5 s
0 de 180
33 de 180
Média de tokens de entrada
339
279
Média de tokens de saída
0
25
Três aprendizados a partir dessas métricas:
Observação: nosso tempo inclui a ida e volta de rede do Colab, então trate essa diferença como dependente do setup.
Etapa 5: verificar a calibração
Acurácia diz com que frequência um modelo acerta, mas calibração diz se a confiança dele significa algo ou não. Um modelo está bem calibrado quando sua confiança bate com sua acurácia; ou seja, se ele diz 0,8 em um grupo de respostas, cerca de 80% delas devem estar corretas.
Para medir isso, agrupamos as predições em 10 faixas de confiança e comparamos a confiança média de cada faixa com sua acurácia. O erro de calibração esperado (ECE) é o gap médio ponderado pela quantidade de predições em cada faixa. Quanto menor, melhor.
A função
ece()coloca cada predição em uma de 10 faixas por confiança (0 a 0,1; 0,1 a 0,2; e assim por diante). Para cada faixa, calcula o gap entre a confiança média e a acurácia, pondera pela participação de predições naquela faixa e soma os resultados.Veja como os dois modelos se comparam:
Métrica
Gemini Decision 1
Gemini 3.5 Flash-Lite
Acurácia
84,4%
83,9%
Confiança média
0,867
0,957
ECE
0,050
0,124
Confiança média quando acerta
0,901
0,966
Confiança média quando erra
0,686
0,912
Figura: diagramas de confiabilidade para ambos os modelos
A confiança do Decision 1 fica próxima da sua acurácia, com ECE de 0,050. Ela também é visivelmente menor quando o modelo erra (0,686) do que quando acerta (0,901).
O Flash-Lite é superconfiante. Reporta em média 0,957 enquanto acerta 83,9% das vezes. Ele usou apenas 9 valores distintos de confiança em 180 respostas, e 158 delas foram 0,95 ou mais. Mesmo as respostas erradas ficaram em média 0,912. O número parece uma probabilidade, mas é a própria estimativa do modelo escrita em texto.
Calibração importa quando você age com base no escore. Um padrão comum é aceitar respostas acima de um limite de confiança e enviar o restante para um modelo de fallback ou um humano:
Limite
Decision 1: % mantida
Decision 1: acurácia nas mantidas
Flash-Lite: % mantida
Flash-Lite: acurácia nas mantidas
0,50
94,4%
85,9%
99,4%
84,4%
0,70
78,3%
92,2%
98,9%
84,3%
0,80
74,4%
93,3%
98,9%
84,3%
0,90
63,3%
95,6%
88,9%
87,5%
0,95
53,9%
96,9%
87,8%
87,3%
Com o Decision 1, um limite mais alto funciona como esperado. Em 0,9, ele mantém 63% das mensagens com 95,6% de acurácia. Com o Flash-Lite, o limite quase não ajuda, porque a maioria das respostas erradas também tem confiança alta. A documentação oficial recomenda escolher um limite a partir de exemplos rotulados do seu próprio tráfego.
Etapa 6: classificar 100 mensagens em uma requisição
A Decisions API pode responder até 1.000 perguntas sobre um input compartilhado em uma única requisição. Para testar isso, colocamos N mensagens de clientes em um input e fazemos uma pergunta por mensagem.
Para o Decision 1, isso significa N perguntas
choicecom as chaves dem1amN:Aqui, a função
build_batch()numera as primeiras N mensagens e as junta em um input compartilhado. Depois,decide_batch()cria uma perguntachoicepor mensagem, com chave dem1amN, envia tudo em uma única requisição e lê uma resposta por chave.Para o Flash-Lite, enviamos o mesmo input compartilhado com um schema JSON que tem N campos, cada um limitado às 12 labels. Cada N usa as mesmas mensagens para ambos os modelos, e cada configuração roda três vezes.
Perguntas por requisição
Decision 1: latência mediana
Flash-Lite: latência mediana
Decision 1: tokens de entrada
Flash-Lite: tokens de entrada / saída
1
318 ms
888 ms
344
291 / 14
5
353 ms
858 ms
1.554
369 / 64
10
398 ms
1.063 ms
3.056
456 / 129
25
546 ms
2.753 ms
7.570
710 / 350
50
592 ms
Falhou
15.100
Falhou
100
59.095 ms
Falhou
30.309
Falhou
Até 25 perguntas, a latência mediana do Decision 1 ficou abaixo de 550 ms. A mediana do Flash-Lite cresceu com N, de menos de 1 s em 1 a 5 perguntas para 2,75 s em 25, porque ele precisa escrever cada resposta como tokens de saída. Mesmo com 50 perguntas, a mediana do Decision 1 foi 592 ms, embora uma das três execuções tenha levado 70 s.
Dois pontos para refletir:
Etapa 7: enxugar as requisições
Agora surge a pergunta óbvia: dá para corrigir a lentidão e as falhas? Para o Decision 1, usamos descrições vazias (""). Para o Flash-Lite, pedimos uma única lista de N rótulos em vez de N campos separados:
Veja como o Decision 1 se saiu com descrições vazias:
Perguntas por requisição
Latência mediana
Acurácia
Tokens de entrada
25
357 ms
84,0%
3.995
50
649 ms
78,0%
7.950
100
1.603 ms
83,0%
16.009
Remover as descrições praticamente cortou pela metade os tokens de entrada. Em 100 perguntas, a requisição caiu para cerca de 16K tokens e a latência mediana foi de 59 s para 1,6 s. A acurácia caiu um pouco em 25 e 50 perguntas, então descrições curtas são um meio-termo melhor do que nenhuma, principalmente para intenções semelhantes.
O schema em lista não ajudou o modelo Flash-Lite. Ele funcionou com 25 perguntas, mas continuou falhando em 50 e 100.
Etapa 8: comparar custos
Por fim, calculamos o custo a partir das contagens de tokens que cada API retorna, usando preços do tier pago:
Modelo
Preço por 1M tokens de entrada
Preço por 1M tokens de saída
Gemini Decision 1
US$ 0,10
US$ 0
Gemini 3.5 Flash-Lite
US$ 0,30
US$ 2,50 (incluindo thinking tokens)
A função
cost_per_request()multiplica cada contagem de tokens pelo preço por 1M de tokens. Para o Decision 1, só tokens de entrada contam. Para o Flash-Lite, thinking tokens são cobrados como tokens de saída, então somamos aos de saída.Aqui está o custo por 1.000 requisições em cada setup:
Setup
Gemini Decision 1
Gemini 3.5 Flash-Lite
Flash-Lite / Decision 1
1 mensagem por requisição
US$ 0,034
US$ 0,147
4,3x
5 perguntas por requisição
US$ 0,155
US$ 0,271
1,7x
10 perguntas por requisição
US$ 0,306
US$ 0,459
1,5x
25 perguntas por requisição
US$ 0,757
US$ 1,088
1,4x
25 perguntas, setups enxutos (Etapa 7)
US$ 0,400
US$ 0,831
2,1x
50 perguntas por requisição
US$ 1,510
Falhou
n/d
100 perguntas, descrições vazias
US$ 1,601
Falhou
n/d
Em mensagens únicas, o Decision 1 foi 4,3x mais barato, mas a diferença diminui conforme você agrupa mais perguntas na mesma requisição. O input compartilhado é cobrado uma vez em ambas as APIs. Porém, cada pergunta no Decision 1 carrega sua própria instrução e todas as 12 descrições de opção, enquanto o Flash-Lite vê a lista de labels apenas uma vez e paga por uma saída curta por resposta. Em 25 perguntas, o Decision 1 usou 7.570 tokens de entrada contra 710 de entrada e 350 de saída do Flash-Lite.
Observação: a Decisions API não suporta cache de contexto nem a Batch API. Se você enviar o mesmo input em várias requisições, ele será cobrado integralmente em cada uma. Portanto, quando tiver muitas perguntas sobre o mesmo input, faça todas em uma única chamada em vez de espalhá-las.
Quando usar cada abordagem
Com base nas execuções acima, um modelo de decisão é a melhor opção quando:
Um modelo generativo ainda é a melhor opção quando:
Use a Decisions API quando precisar de
Use a Interactions API quando precisar de
Uma probabilidade sim/não, uma opção de um conjunto fixo ou uma nota em escala fixa
Texto gerado, resumos ou explicações
Probabilidades calibradas que você pode limiar
Valores extraídos ou objetos que seguem seu próprio schema JSON
Muitas verificações independentes sobre o mesmo input em uma chamada
Chamadas de ferramenta com argumentos
Baixa latência e custo zero de tokens de saída
Raciocínio em múltiplas etapas
Considerações finais
Neste tutorial, construímos um classificador de intenção bancária com o Gemini Decision 1 e o Gemini 3.5 Flash-Lite, e então calculamos acurácia, latência, calibração e custo para comparar os dois modelos. Quatro conclusões:
Estes resultados vêm de uma tarefa, um dataset e poucas execuções em um notebook do Colab. Trate-os como observações de um demo, não como afirmações gerais de performance.