Como usar o Jev para map-reduce em grandes volumes de dados?

Rodar uma decisão simples em milhões de linhas usando um LLM de texto é aquele tipo de plano que parece ótimo até você olhar a fatura e a latência

Fala aí, beleza? O Jev é o modelo da TypeSafe AI classificado como System One: em vez de gerar texto, ele recebe um estado não estruturado e devolve decisões tipadas com probabilidades calibradas

E olha que interessante: a própria TypeSafe cita o processamento de datasets gigantes como caso de uso do modelo, buscar informação relevante em corpora enormes, classificar traces de agentes em massa e extrair features pra fazer previsões

Ou seja, o padrão clássico de map-reduce, decisão linha a linha no map e agregação depois, não é gambiarra nossa, é o uso pensado pro modelo

Bora montar isso?

O que você precisa antes de começar

Antes de sair disparando requisição, arruma essas quatro coisas:

• Uma API key, que vai no header Authorization: Bearer <API_KEY>
• O identificador do modelo que você vai usar no campo model: jev-latest, jev-1.13.0 ou jev-preview. Se preferir consumir por um agregador, o Jev 1.13 também está disponível no OpenRouter sob o identificador typesafe/jev-1.13
• Um dataset com uma unidade clara por registro: uma linha, um ticket, um trace, um documento. Se você não consegue dizer em uma frase "o que é um registro aqui", o map vai sair torto
• Ciência dos rate limits, que são medidos em tokens por segundo e em requisições por minuto. Estourou qualquer um dos dois, a API devolve HTTP 429 Too Many Requests

Esse último ponto é o que separa o script que roda de madrugada inteirinho do script que morre no registro 3.000 😀

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Passo a passo: montando o map-reduce com o Jev

A lógica aqui é velha conhecida de quem já mexeu com processamento distribuído: se você conhece o map-reduce de dados, é exatamente isso, só que a função de map é uma chamada de modelo em vez de uma função pura

A diferença é que o modelo custa dinheiro e tem limite de vazão, então o desenho importa

1. Defina a unidade de map

Um registro vira um state. O campo aceita string, objeto ou array, então você pode mandar o texto cru, um JSON com os campos relevantes ou uma lista de eventos

Escolha o menor recorte que ainda responde a pergunta. Se a decisão é sobre um comentário, manda o comentário, não a thread inteira

Erro comum deste passo: jogar o registro inteiro do banco no state "por garantia". Cada token de entrada é cobrado, e você paga por lixo que não muda a decisão

2. Modele a pergunta escolhendo o tipo certo

A API expõe três tipos: choice, que escolhe uma opção de um conjunto definido e aceita até 255 opções, score, que dá uma nota contra níveis ordenados e descritivos numa escala de 2 a 10 níveis, e a pergunta de sim/não, que devolve a probabilidade de "sim"

Pensa assim: rótulo é choice, intensidade é score, filtro é sim/não

Erro comum deste passo: escrever pergunta aberta, do jeito que a gente escreve prompt pra chat. Aqui não tem texto livre de saída, a pergunta tem que caber num dos três formatos ou ela simplesmente não é uma pergunta pro Jev

3. Agrupe várias perguntas na mesma requisição

Essa é a parte que muita gente deixa passar e é justamente onde mora a economia

Todas as perguntas de uma mesma requisição rodam em paralelo contra o mesmo state, e cada pergunta adicional custa apenas os próprios tokens. O estado não é recobrado a cada pergunta

Então se você precisa de categoria, nível de risco e um filtro de relevância sobre o mesmo documento, isso é UMA requisição com três perguntas, não três requisições

Erro comum deste passo: um loop por pergunta. Você multiplica o custo do state por nada

4. Monte o body e dispare o POST

As requisições vão para https://api.typesafe.ai/v1/systemone, com Content-Type: application/json. O corpo tem três campos: state, model e questions, sendo questions um mapa de IDs de pergunta para objetos Question

   curl -X POST https://api.typesafe.ai/v1/systemone \
     -H "Authorization: Bearer $TYPESAFE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "state": {
         "id": "tk-10482",
         "texto": "cliente relatou cobrança duplicada no cartão"
       },
       "model": "jev-latest",
       "questions": {
         "categoria": { },
         "risco": { },
         "precisa_humano": { }
       }
     }'

Cada valor dentro de questions é um objeto Question de um dos três tipos, e o ID que você escolher (categoria, risco, precisa_humano) é o que vai te ajudar a casar resposta com coluna lá no reduce. Os formatos exatos de cada objeto estão na documentação da API

Erro comum deste passo: esquecer o Content-Type: application/json e ficar caçando bug no payload que está perfeito

5. Guarde a saída tipada do jeito que o reduce vai querer ler

Respostas de choice e de score trazem um campo confidence entre 0 e 1, derivado da distribuição de probabilidade da própria resposta. E as probabilidades e scores retornados vêm arredondados para duas casas decimais, com o campo result.rounding reportando essa precisão

Persista a decisão E a confidence, sempre. Guardar só o rótulo é jogar fora a informação mais útil que o modelo te deu

Erro comum deste passo: tratar a saída como verdade absoluta e ignorar a confidence. Aí você monta um relatório onde um registro de confidence baixa pesa igual a um de confidence alta

6. Rode o reduce fora do modelo

Aqui é código seu, puro e barato: contagem, média, corte por limiar, junção com as outras colunas do dataset

   from collections import Counter

   # linhas = [{"id":..., "categoria":..., "confidence":...}, ...]
   confiaveis = [l for l in linhas if l["confidence"] >= 0.8]

   distribuicao = Counter(l["categoria"] for l in confiaveis)
   taxa_revisao = 1 - (len(confiaveis) / len(linhas))

   print(distribuicao.most_common())
   print(f"fila de revisão humana: {taxa_revisao:.1%}")

Repara que o modelo não participa dessa etapa. Ele decide, você agrega. Se a sua agregação começou a virar "pergunta pro modelo o resumão de tudo", você saiu do padrão e voltou pro problema do começo

7. Paralelize o lote no cliente e respeite o 429

O endpoint é síncrono, então o "lote" é paralelismo do seu lado: um pool de workers mandando registros e um backoff quando a API responder 429

   import time, requests
   from concurrent.futures import ThreadPoolExecutor

   URL = "https://api.typesafe.ai/v1/systemone"
   HEADERS = {
       "Authorization": f"Bearer {API_KEY}",
       "Content-Type": "application/json",
   }

   def processa(registro, tentativas=5):
       body = {
           "state": registro,
           "model": "jev-latest",
           "questions": QUESTIONS,
       }
       espera = 1
       for _ in range(tentativas):
           r = requests.post(URL, headers=HEADERS, json=body)
           if r.status_code == 429:
               time.sleep(espera)
               espera *= 2
               continue
           r.raise_for_status()
           return r.json()
       raise RuntimeError("rate limit persistente")

   with ThreadPoolExecutor(max_workers=8) as pool:
       resultados = list(pool.map(processa, registros))

Erro comum deste passo: subir a concorrência no chute até bater no teto e perder registro no meio do caminho. Comece baixo, observe, sobe devagar

Se o seu dataset já vive dentro de um pipeline de orquestração, dá pra encaixar esse map como mais uma etapa. Quem trabalha com automação de ETL para grandes volumes vai reconhecer na hora onde esse nó entra: entre a extração e a carga, como enriquecimento

Onde esse padrão rende mais

A TypeSafe cita algumas frentes como caso de uso do Jev, e cada uma pede um desenho diferente de map e de reduce. Se liga na tabela: a coluna do meio é a pergunta que vai no map, a da direita é o que o seu código faz depois

O caso de busca em corpora é o mais subestimado, na minha opinião

Você não está pedindo pro modelo resumir o corpus, está usando ele como filtro binário linha a linha e deixando o ranking pro seu código. Barato, auditável e você enxerga exatamente por que cada item entrou

E no caso de classificar traces, tem um detalhe legal: como as perguntas rodam em paralelo contra o mesmo estado, você consegue extrair categoria, severidade e um flag de revisão do mesmo trace de uma vez só

Quanto custa rodar em lote e como dimensionar

Agora a parte que decide se o projeto acontece ou fica no slide 🙂

O preço publicado do Jev é de US$ 0,042 por milhão de tokens de entrada, com tokens de saída sem cobrança. Em outra unidade, isso dá US$ 42 por bilhão de tokens de entrada

A conta direta de um lote:

• 100 mil registros de 1.000 tokens cada
• = 100 milhões de tokens de entrada
• = cerca de US$ 4,20 no total, com a saída sem cobrança

E esse preço de lançamento segue valendo, não há registro de reversão ou correção desde o anúncio do acesso antecipado, em 15 de setembro de 2026

Agora liga o ponto 3 do passo a passo com essa conta: o que domina o custo é o state, não a pergunta. Como cada pergunta adicional custa apenas os próprios tokens e o estado não é recobrado, três decisões numa requisição custam bem menos que três requisições com o mesmo estado repetido

A lição prática é: enxugue o state, empilhe as perguntas

Só que custo não é throughput. O tempo que o lote leva vai ser governado pelos rate limits em tokens por segundo e requisições por minuto, e não pelo seu cartão de crédito

Por isso vale instrumentar a rodada desde o piloto: taxa de 429, registros por minuto, distribuição de confidence. Se você já tem o hábito de monitorar pipelines com Prometheus e Grafana, aponta os mesmos painéis pra esse job e você enxerga o teto real antes de escalar

Vídeo: ferramentas de IA no fluxo de desenvolvimento

Pra quem está começando do zero com ferramentas de IA aplicadas a desenvolvimento, este vídeo do canal mostra o novo Google AI Studio montando um app fullstack com banco de dados

Próximo passo

O segredo do Jev map-reduce não é um prompt esperto, é divisão de trabalho

O modelo fica com a decisão tipada, uma por registro, com a probabilidade calibrada junto. A agregação fica no seu código, onde ela é barata, testável e você consegue explicar pra qualquer pessoa como aquele número apareceu

Sugestão de próximo passo: roda um piloto com algumas centenas de registros, olha a distribuição de confidence que voltou, ajusta o recorte do state e a redação das perguntas

Se a confidence estiver espalhada demais, o problema quase sempre é a pergunta, não o modelo

Aí sim você escala o lote, com backoff no lugar e o custo já projetado

Bora testar? até o próximo post!