Cada token que você envia para uma API de LLM custa dinheiro. Não muito por token — mas quando seu prompt inclui um dataset com 50 linhas de dados de usuário formatados como JSON, você está pagando por cada chave, cada nome de chave repetido, cada marca de aspas. Em um dataset com 10 campos e 100 linhas, JSON queima aproximadamente 60–70% de seus tokens em ruído estrutural. TOON foi construído para corrigir exatamente isso. Este artigo mostra como usar @toon-format/toon para cortar suas contagens de tokens de prompt — às vezes em mais da metade — sem perder nenhuma estrutura que o modelo precisa.

Como funciona o preço de tokens de LLM

Modelos como GPT-4o e Claude cobram por token de entrada e por token de saída. A ferramenta OpenAI Tokenizer permite que você cole qualquer texto e veja exatamente quantos tokens custa. Grosso modo, 1 token ≈ 4 caracteres de texto em inglês — mas os caracteres estruturais do JSON (aspas, dois-pontos, chaves) são frequentemente tokenizados individualmente, então prompts cheios de JSON tokenizam pior do que prosa simples com a mesma contagem de caracteres. Você está pagando um imposto estrutural em cada requisição.

Para um aplicativo SaaS típico rodando milhares de requisições por dia com dados estruturados em cada prompt, esse imposto se acumula rapidamente. A arquitetura dos modelos de linguagem grandes significa que o modelo genuinamente não precisa de todo esse ruído de formatação — ele pode ler dados estruturados muito bem sem a verbosidade do JSON, desde que o formato seja inequívoco e bem explicado.

JSON vs TOON — Uma comparação concreta de tokens

Vamos tornar isso concreto. Aqui está um dataset de 10 linhas de usuários em JSON:

json
[
  { "id": 1, "username": "alice_dev", "email": "[email protected]", "plan": "pro", "active": true },
  { "id": 2, "username": "bob_writer", "email": "[email protected]", "plan": "free", "active": true },
  { "id": 3, "username": "carol_ops", "email": "[email protected]", "plan": "pro", "active": false },
  { "id": 4, "username": "dan_qa", "email": "[email protected]", "plan": "team", "active": true },
  { "id": 5, "username": "eve_design", "email": "[email protected]", "plan": "pro", "active": true },
  { "id": 6, "username": "frank_sec", "email": "[email protected]", "plan": "team", "active": true },
  { "id": 7, "username": "grace_ml", "email": "[email protected]", "plan": "pro", "active": false },
  { "id": 8, "username": "henry_be", "email": "[email protected]", "plan": "free", "active": true },
  { "id": 9, "username": "iris_fe", "email": "[email protected]", "plan": "pro", "active": true },
  { "id": 10, "username": "jack_devrel", "email": "[email protected]", "plan": "team", "active": true }
]

Esse bloco JSON tokeniza para aproximadamente 310–330 tokens. Aqui estão os mesmos dados exatos em notação tabular TOON:

text
users[10]{id,username,email,plan,active}:
  1,alice_dev,[email protected],pro,true
  2,bob_writer,[email protected],free,true
  3,carol_ops,[email protected],pro,false
  4,dan_qa,[email protected],team,true
  5,eve_design,[email protected],pro,true
  6,frank_sec,[email protected],team,true
  7,grace_ml,[email protected],pro,false
  8,henry_be,[email protected],free,true
  9,iris_fe,[email protected],pro,true
  10,jack_devrel,[email protected],team,true

A versão TOON tokeniza para aproximadamente 135–150 tokens — cerca de 55% menos. Em escala, isso não é um erro de arredondamento. Se você está rodando 10.000 dessas consultas por dia no preço do GPT-4o, a diferença entre JSON e TOON apenas em seu prompt é significativa.

A economia de tokens escala com linhas, não colunas. Quanto mais linhas seu dataset tiver, maior o ganho — porque o TOON paga o custo de cabeçalho de coluna uma vez, enquanto o JSON paga o custo de nome de chave em cada linha única. Uma tabela de 100 linhas em TOON economiza aproximadamente o mesmo percentual que este exemplo de 10 linhas.

Instalando e convertendo dados no Node.js

Instale o pacote do npm. Funciona no Node.js 18+ e navegadores modernos:

bash
npm install @toon-format/toon

O import é uma única desestruturação:

js
import { encode, decode } from '@toon-format/toon';

// Convert a JS array/object to TOON before sending to an LLM
const users = [
  { id: 1, username: 'alice_dev', email: '[email protected]', plan: 'pro', active: true },
  { id: 2, username: 'bob_writer', email: '[email protected]', plan: 'free', active: true },
  // ... more rows
];

const toonData = encode(users, { indent: 2 });
console.log(toonData);
// users[2]{id,username,email,plan,active}:
//   1,alice_dev,[email protected],pro,true
//   2,bob_writer,[email protected],free,true

Padrão prático: Fetch → Encode → Prompt → Decode

O fluxo de trabalho para usar TOON com uma API de LLM é de quatro etapas. Busque seus dados de qualquer fonte (banco de dados, API REST, arquivo CSV), codifique para TOON, construa seu prompt, e opcionalmente decodifique qualquer TOON estruturado de volta da resposta do modelo.

js
import { encode, decode } from '@toon-format/toon';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function analyseUsers(users) {
  // Step 1: encode data to TOON
  const toonData = encode(users, { indent: 2 });

  // Step 2: build the prompt
  const systemPrompt = [
    'You analyse user datasets. Data is provided in TOON (Token-Optimised Object Notation).',
    'TOON tabular format: name[count]{col1,col2,...}: followed by comma-separated rows, one per line.',
    'Respond with plain prose unless asked to return data, in which case use TOON format.'
  ].join('\n');

  const userPrompt = `Here is the user dataset:\n\n${toonData}\n\nWhich plan has the most active users?`;

  // Step 3: call the API
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: userPrompt }
    ]
  });

  return response.choices[0].message.content;
}

// Step 4 (optional): if the model returns TOON, decode it back
const rawResponse = await analyseUsers(myUserArray);
try {
  const structured = decode(rawResponse);
  console.log('Structured result:', structured);
} catch {
  console.log('Prose response:', rawResponse);
}

O mesmo padrão funciona para a API Claude da Anthropic — apenas troque o cliente. A estrutura do prompt e a codificação TOON são idênticas independentemente do provedor. Você pode verificar a documentação completa da API da OpenAI para detalhes de configuração de autenticação e seleção de modelo.

Quando importa mais

TOON vale mais nestes cenários:

  • Datasets grandes em contexto. Sempre que você está colocando mais de ~20 linhas de dados estruturados em um prompt, a notação tabular TOON vai economizar tokens significativos em comparação com arrays JSON de objetos.
  • Consultas estruturadas repetidas. Se seu aplicativo faz o mesmo tipo de consulta milhares de vezes por dia (pense em: "analisar a atividade deste usuário" com um registro de usuário em cada prompt), a economia acumulada é substancial.
  • Jobs de processamento em lote. Scripts que processam milhares de registros através de um LLM — classificação, tagging, enriquecimento, sumarização — se beneficiam enormemente. Menos tokens por chamada significa maior throughput e menor custo.
  • Tarefas com restrição de janela de contexto. Quando você está tentando caber um dataset grande em uma janela de contexto de 128k junto com um longo prompt de sistema e exemplos few-shot, cada token conta. TOON permite caber mais linhas na mesma janela.
  • APIs de produção sensíveis a custo. Projetos hobby de tier gratuito não vão notar. Apps de produção servindo usuários pagantes em escala com certeza vão.

A única ressalva: LLMs precisam conhecer o formato

TOON não está em nenhum dado de treinamento de LLM da forma que JSON está. O modelo nunca viu um arquivo .toon. Isso significa que você deve incluir uma breve descrição do formato em seu prompt de sistema — caso contrário, o modelo ou vai recusar a entrada ou vai analisá-la incorretamente. A boa notícia é que a descrição é curta, e você só paga por ela uma vez por conversa ou requisição.

Uma adição mínima ao prompt de sistema que funciona de forma confiável:

text
Data is provided in TOON (Token-Optimised Object Notation).
TOON syntax:
- Objects: {key:value,key2:value2} — keys are never quoted
- Arrays: [val1,val2,val3]
- Tabular: name[rowCount]{col1,col2,...}:
    rowval1,rowval2,...
    rowval1,rowval2,...
Parse each row by matching values to the column headers in order.
Strings containing commas are double-quoted.

Esse bloco adiciona aproximadamente 60 tokens ao seu prompt de sistema — um custo único que é rapidamente recuperado em qualquer dataset maior que 5–6 linhas. Para aplicações onde você está fazendo muitas chamadas de API com dados TOON, os tokens de descrição de formato são amortizados para quase zero. Use JSON para TOON para converter seus dados antes de construir o prompt, e TOON Formatter para verificar se está correto.

Conclusão

O caso para TOON em fluxos de trabalho de LLM é simples: você está pagando por token, dados estruturados em JSON são ineficientes em tokens, e TOON é uma correção direta. A notação tabular sozinha reduz o uso de tokens em 50–60% em datasets típicos baseados em linhas. O pacote npm — @toon-format/toon — é pequeno, a API tem duas funções, e a integração em uma chamada de API existente é um trabalho de cinco minutos. A única coisa a lembrar é a descrição do formato em seu prompt de sistema — sem ela, o modelo está adivinhando. Com ela, você obtém um modelo que lê seus dados corretamente pela metade do custo de tokens. Comece com JSON para TOON para converter seus dados existentes, valide com o TOON Validator, e use TOON para JSON ou decode() para converter respostas estruturadas de volta quando necessário.

← All TOON articles Browse all categories →