Utiliser TOON avec les LLMs — Réduire les coûts de tokens sans perdre la structure

Chaque token que vous envoyez à une API LLM coûte de l'argent. Pas grand-chose par token — mais quand votre prompt inclut un dataset de 50 lignes de données utilisateur formatées en JSON, vous payez pour chaque accolade, chaque nom de clé répété, chaque guillemet. Sur un dataset de 10 champs et 100 lignes, JSON brûle environ 60 à 70% de ses tokens sur du bruit structurel. TOON a été conçu pour résoudre exactement cela. Cet article vous montre comment utiliser @toon-format/toon pour réduire le nombre de tokens de vos prompts — parfois de plus de la moitié — sans perdre aucune structure dont le modèle a besoin.

Comment fonctionne la tarification des tokens LLM

Les modèles comme GPT-4o et Claude facturent par token d'entrée et par token de sortie. L'outil OpenAI Tokenizer vous permet de coller n'importe quel texte et de voir exactement combien de tokens il coûte. En gros, 1 token ≈ 4 caractères de texte anglais — mais les caractères structurels de JSON (guillemets, deux-points, accolades) sont souvent tokenisés individuellement, donc les prompts lourds en JSON tokenisent moins bien que la prose ordinaire au même nombre de caractères. Vous payez une taxe structurelle sur chaque requête.

Pour une application SaaS typique exécutant des milliers de requêtes par jour avec des données structurées dans chaque prompt, cette taxe s'accumule rapidement. L'architecture des grands modèles de langage signifie que le modèle n'a pas vraiment besoin de tout ce bruit de formatage — il peut lire des données structurées très bien sans la verbosité de JSON, à condition que le format soit non ambigu et bien expliqué.

JSON vs TOON — une comparaison concrète de tokens

Rendons cela concret. Voici un dataset de 10 utilisateurs en 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 }
]

Ce bloc JSON se tokenise à environ 310 à 330 tokens. Voici exactement les mêmes données en notation tabulaire TOON :

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

La version TOON se tokenise à environ 135 à 150 tokens — environ 55% de moins. À l'échelle, ce n'est pas une erreur d'arrondi. Si vous exécutez 10 000 de ces requêtes par jour au tarif GPT-4o, la différence entre JSON et TOON dans votre prompt seul est significative.

Installation et conversion des données dans Node.js

Installez le package depuis npm. Il fonctionne dans Node.js 18+ et les navigateurs modernes :

npm install @toon-format/toon

L'import est une seule déstructuration :

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

Pattern pratique : Fetch → Encode → Prompt → Decode

Le flux de travail pour utiliser TOON avec une API LLM est en quatre étapes. Récupérez vos données depuis n'importe quelle source (base de données, API REST, fichier CSV), encodez-les en TOON, construisez votre prompt et décodez optionnellement tout TOON structuré de la réponse du modèle.

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);
}

Le même pattern fonctionne pour l'API Anthropic Claude — changez juste le client. La structure du prompt et l'encodage TOON sont identiques quel que soit le fournisseur. Vous pouvez consulter les docs API OpenAI complètes pour les détails de configuration de l'authentification et de sélection de modèle.

Quand c'est le plus important

TOON est le plus rentable dans ces scénarios :

• Grands datasets en contexte. Chaque fois que vous mettez plus de ~20 lignes de données structurées dans un prompt, la notation tabulaire TOON vous fera économiser des tokens significatifs par rapport aux tableaux JSON d'objets.
• Requêtes structurées répétées. Si votre application fait le même type de requête des milliers de fois par jour (pensez : "analyse l'activité de cet utilisateur" avec un enregistrement utilisateur dans chaque prompt), les économies cumulées sont substantielles.
• Travaux de traitement par lots. Les scripts qui traitent des milliers d'enregistrements via un LLM — classification, étiquetage, enrichissement, résumé — bénéficient énormément. Moins de tokens par appel signifie un débit plus rapide et un coût moindre.
• Tâches contraintes par la fenêtre de contexte. Quand vous essayez de faire rentrer un grand dataset dans une fenêtre de contexte de 128k à côté d'un long prompt système et d'exemples few-shot, chaque token compte. TOON vous permet de faire rentrer plus de lignes dans la même fenêtre.
• APIs de production sensibles aux coûts. Les projets hobby en tier gratuit ne le remarqueront pas. Les applications de production servant des utilisateurs payants à grande échelle, si.

La mise en garde : les LLMs doivent connaître le format

TOON n'est dans les données d'entraînement d'aucun LLM comme JSON l'est. Le modèle n'a jamais vu de fichier .toon. Cela signifie que vous devez inclure une brève description du format dans votre prompt système — sinon le modèle soit refusera l'entrée soit la mal-parsera. La bonne nouvelle est que la description est courte, et vous ne la payez qu'une fois par conversation ou requête.

Un ajout minimal au prompt système qui fonctionne de manière fiable :

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.

Ce bloc ajoute environ 60 tokens à votre prompt système — un coût unique qui est rapidement récupéré sur tout dataset de plus de 5 à 6 lignes. Pour les applications faisant de nombreux appels API avec des données TOON, les tokens de description du format sont amortis à quasi zéro. Utilisez JSON vers TOON pour convertir vos données avant de construire le prompt, et le formateur TOON pour vérifier qu'il est correct.

En résumé

L'argument en faveur de TOON dans les flux de travail LLM est simple : vous payez par token, les données structurées en JSON sont peu efficaces en tokens, et TOON est un correctif direct. La notation tabulaire seule réduit l'utilisation des tokens de 50 à 60% sur les datasets typiques à base de lignes. Le package npm — @toon-format/toon — est tiny, l'API est deux fonctions, et l'intégration dans un appel API existant est un travail de cinq minutes. La seule chose à retenir est la description du format dans votre prompt système — sans elle, le modèle est en train de deviner. Avec elle, vous obtenez un modèle qui lit correctement vos données à la moitié du coût en tokens. Commencez avec JSON vers TOON pour convertir vos données existantes, validez-les avec le validateur TOON, et utilisez TOON vers JSON ou decode() pour convertir les réponses structurées en retour si nécessaire.