Przewodnik po formacie TOON: odchudź JSON przed podaniem go do LLM
Podsumowanie: Gdy przekazujesz jednolitą tablicę do modelu językowego w formacie JSON, powtarzające się nazwy kluczy i nawiasy pożerają tokeny. TOON deklaruje strukturę tylko raz dzięki wciętym obiektom i tabelarycznym tablicom, a dane wylewa wiersz po wierszu. Oficjalne benchmarki pokazują około 40% mniej tokenów przy wyższej dokładności parsowania. Ten przewodnik obejmuje składnię, kiedy oszczędność działa, kiedy konwersja się nie opłaca i jak połączyć encode z decode.

Narzut składniowy JSON nie ma znaczenia przy transferze między maszynami, ale na wejściu LLM rozliczanego za tokeny to realne pieniądze: ta sama jednolita tablica powtarza nazwy kluczy dziesiątki razy, a każda klamra z każdym cudzysłowem ugryzie kawałek budżetu. TOON nie wymyśla nowego modelu danych — przepisuje model danych JSON tańszą notacją.
Czym jest TOON: jeszcze jedno kodowanie JSON, nie konkurent
TOON (Token-Oriented Object Notation) to otwarty format, który pojawił się w 2025 roku, a jego oficjalne pozycjonowanie mieści się w jednym zdaniu: kompaktowe, bezstratne i czytelne kodowanie modelu danych JSON. Nie wprowadza nowych typów — obiekty, tablice, stringi, liczby, booleany i null odpowiadają JSON-owi jeden do jednego, a decode(encode(x)) jest ściśle równe danym oryginalnym (typy spoza JSON jak Date czy NaN trzeba najpierw znormalizować). Round-trip jest bezstratny i deterministyczny: to samo wejście zawsze daje to samo wyjście, co jest ważne dla powtarzalnych promptów.
Ponieważ TOON koduje dokładnie model danych JSON, właściwym sposobem użycia jest format graniczny: aplikacja dalej pracuje w JSON wewnątrz, konwertuje do TOON tuż przed włożeniem danych do promptu i konwertuje z powrotem z odpowiedzi modelu. Oficjalna dokumentacja nazywa to „translation layer“. Zwyczajowe rozszerzenie plików to .toon; dla transportu HTTP tymczasowy media type to text/toon, w UTF-8.
Jedno ostrzeżenie dotyczące szumu wyszukiwania: nie myl z Toon Shaderem w grafice 3D. Wspólne jest tylko słowo.
Dlaczego JSON jest szczególnie drogi na wejściu LLM
Weź listę zamówień, wykaz użytkowników albo podsumowanie logów zapisane jako tablica JSON. Tokeny idą w trzy miejsca:
- Powtarzające się nazwy kluczy. Pięćdziesiąt rekordów zamówień pisze
"id","amount"i"status"po pięćdziesiąt razy każdy. Podwój dane — podwoisz narzut. - Interpunkcja strukturalna. Klamry i nawiasy kwadratowe, dwukropki i przecinki — wszystko to tokeny, a zagnieżdżanie pakuje je jeszcze gęściej.
- Cudzysłowy. Prawie każdy klucz i każda wartość tekstowa są owinięte podwójnymi cudzysłowami.
Razem: koszt API rozliczanego za tokeny rośnie wprost; długie wejścia wcześniej uderzają w sufit okna kontekstu; a przy bardzo długich wejściach model częściej pomija lub przesuwa pola. Benchmark oficjalnej strony: na zestawie testowym o mieszanych strukturach i czterech modelach około 40% mniej tokenów przy dokładności parsowania rosnącej z 70% (JSON) do 74% (TOON). Oszczędność i dokładność to tu nie trade-off, bo bardziej kompaktowa struktura robi granice bardziej widocznymi dla modelu.
Składnia: wcięte obiekty + tabelaryczne tablice
Te same dane prognozy pogody w trzech formach. Wersja JSON, około 117 tokenów:
{
"location": { "city": "Berlin", "country": "DE", "units": "metric" },
"alerts": ["frost", "wind"],
"forecast": [
{ "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
{ "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
{ "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
]
}
Wersja TOON, około 66 tokenów:
location:
city: Berlin
country: DE
units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
Mon,-2,4,snow,80
Tue,1,7,cloudy,20
Wed,3,11,sunny,5
Trzy formy pokrywają wszystko, a serializator wybiera je automatycznie według kształtu danych:
| Forma | Nadaje się do | Odpowiednik JSON |
|---|---|---|
| Wcięty obiekt | Zagnieżdżone obiekty | { "location": { ... } }, wcięcie zastępuje klamry |
| Tablica inline | Tablice prymitywów | ["frost","wind"], [2] deklaruje długość |
| Tablica tabelaryczna | Tablice jednolitych obiektów | Nazwy pól pojawiają się tylko raz w nagłówku {day,temp{min,max},...}; każdy wiersz zawiera tylko wartości rozdzielone przecinkami |
Jednolite zagnieżdżone obiekty (temp{min,max}) składają się w nagłówek jako grupa zagnieżdżonych pól, a wiersze danych pozostają płaskie. Zasada cudzysłowów jest minimalna: stringi biorą cudzysłowy tylko jeśli zawierają separatory, znaki specjalne albo grozą odczytania jako liczby — jedna z przyczyn, dla których TOON wygrywa z „kompaktowym JSON“ w liczeniu tokenów. Kluczowa różnica wobec YAML: TOON ma jawne deklaracje długości i nagłówki pól weryfikowalne maszynowo; wobec CSV: zachowuje zagnieżdżenie i typy.
[N] i {fields}: strukturalne poręcze dla modelu
[3] i {day,...} służą nie tylko do oszczędzania tokenów — to też weryfikowalny kontrakt, który przekazujesz modelowi:
- Długość tablicy pozwala modelowi od razu odpowiedzieć na „ile rekordów zawiera zestaw danych“ i natychmiast zdemaskuje ucięcie, gdy liczba wierszy się nie zgadza.
- Nagłówek pól deklaruje nazwy raz; model wyrównuje wartości według pozycji zamiast w każdym wierszu od nowa zgadywać dopasowanie kluczy.
To profilaktyka, przeciwieństwo naprawiania po fakcie. Naprawiacz JSON (zobacz przewodnik naprawy) ratuje dane po tym, jak model wypluje zepsuty JSON; deklaracje długości i pól w TOON zmniejszają na wejściu prawdopodobieństwo zepsutych danych. Rób i jedno, i drugie — wskaźnik błędów parsowania w połowie pipeline spada.
Kiedy nie używać TOON
Oficjalna sekcja „When Not to Use TOON“ jest orzeźwiająco bezpośrednia. Cztery scenariusze, zostaw je takimi, jakie są:
| Scenariusz | Dlaczego unikać | Najlepszy wybór |
|---|---|---|
| Głęboko zagnieżdżone, niejednolite struktury | Kwalifikacja tabelaryczna ≈ 0%; kompaktowy JSON często wygrywa | Kompaktowy JSON |
| Półjednolite tablice | Nieregularne pola, oszczędność znika | Zostaw pipeline JSON |
| Czysto tabelaryczne dane | TOON kosztuje 5–10% narzutu względem CSV | CSV |
| Wrażliwe na opóźnienia (modele lokalne/kwantyzowane) | Mniej tokenów ≠ szybszy inference | Najpierw zmierz TTFT |
Półjednolitość ocenia się według kwalifikacji tabelarycznej (tabular eligibility): oficjalnie, przy kwalifikacji 40–60% oszczędność jest już marginalna. Migracja formatu ma realny koszt — parsery, walidatory i skrypty w dół strumienia zmieniają się wszystkie — więc jeśli zysk jest poniżej dziesięciu procent, niczego nie ruszaj.
Wdrożenie: encode / decode i CLI
Oficjalna biblioteka TypeScript, w obu kierunkach:
npm install @toon-format/toon
# Konwersja wsadowa też idzie przez CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'
const data = {
users: [
{ id: 1, name: 'Ada', role: 'admin' },
{ id: 2, name: 'Bob', role: 'user' },
],
}
const toon = encode(data)
// users[2]{id,name,role}:
// 1,Ada,admin
// 2,Bob,user
const back = decode(toon) // ściśle równe danym oryginalnym
Istnieją implementacje w Pythonie, Go, Rust i .NET; zanim jakąś wybierzesz, porównaj listę implementacji w oficjalnym repozytorium specyfikacji i upewnij się, że pokrywa składniowe funkcje, których używasz. Przed produkcją zrób asercję round-trip: decode(encode(oryginał)) musi być głęboko równe oryginałowi; jeśli nie — problem leży w implementacji albo w danych.
Jak to się wpisuje w Twój istniejący pipeline JSON
TOON niczego nie zmienia w Twoim pipeline JSON; dodaje konwersję na granicy. Zalecana kolejność:
- Najpierw upewnij się, że JSON jest czysty. Zepsuty JSON da zepsuty TOON. Walidację składni i naprawę opisuje Przewodnik naprawy JSON.
- Sprawdź kształt danych. Wszystkie obiekty tablicy mają te same pola? Najpierw znormalizuj — albo przyznaj, że konwersja nie jest warta zachodu.
- Konwertuj i próbkowo porównuj. Po konwersji porównaj kilka wierszy z oryginalnym JSON, żeby upewnić się, że wyrównanie pól nie zjechało.
- Oceń korzyść. Dla jednolitych list wierszowa logika podręcznika JSONL działa też przy konwersji strumieniowej; co do relacji rozmiaru i kosztu prawdziwy związek JSON minify i gzip daje tę samą lekcję: najpierw mierzyć, potem konwertować.
Czy TOON zastąpi JSON?
Nie. TOON koduje model danych JSON; jego miejsce to granica promptu, podczas gdy przechowywanie i wymiana między programami pozostają terytorium JSON. Użyj TOON do segmentu „dać modelowi“ i zostaw resztę łańcucha nietkniętą.
Jaki stosunek ma TOON do YAML i CSV?
Obiekty wyglądają jak YAML (wcięcia zamiast klamer); jednolite tablice wyglądają jak CSV (nagłówek zadeklarowany raz, wiersze w strumieniu). Ale TOON ma jawne deklaracje długości, których YAML nie ma, i zachowuje zagnieżdżenie i typy, których CSV nie ma — stoi między nimi, z poręczami weryfikowalnymi maszynowo.
Czy konwersja TOON na JSON traci dane?
Nie: obiekty, tablice, stringi, liczby, booleany i null odpowiadają jeden do jednego, a decode(encode(x)) jest ściśle równe oryginałowi. Jedyna ostrożność — wcześniej znormalizuj typy spoza JSON jak Date i NaN; inaczej równość obowiązuje dopiero po round-trip.
Jak sprawdzić, czy skonwertowany TOON jest poprawny?
Dwie kontrole: asercja round-trip (encode, potem decode, głęboka równość z oryginałem) i wzrokowa inspekcja nagłówka — liczba [N] musi równać się liczbie wierszy, a pola {fields} muszą wyrównywać się jeden do jednego z wartościami rozdzielonymi przecinkami w każdym wierszu. Po stronie modelu możesz jeszcze przed odpowiedzią poprosić o podanie długości tablicy.