Гід з формату TOON: полегшіть JSON перед передачею LLM
Головне: Коли ви передаєте однорідний масив мовній моделі у форматі JSON, повторювані назви ключів і дужки з'їдають токени. TOON оголошує структуру лише один раз через індексовані об'єкти та табличні масиви, а дані вивантажує рядок за рядком. Офіційні бенчмарки показують близько 40% менше токенів із вищою точністю парсингу. Цей гід охоплює синтаксис, коли економія працює, коли конвертувати не варто та як з'єднати encode і decode.

Синтаксичний надлишок JSON не має значення при передачі між машинами, але на вході LLM, який тарифікується за токенами, це реальні гроші: той самий однорідний масив повторює назви ключів десятки разів, і кожна фігурна дужка з кожними лапками відкушує шматок бюджету. TOON не вигадує нову модель даних — він переписує модель даних JSON дешевшою нотацією.
Що таке TOON: ще одне кодування JSON, а не конкурент
TOON (Token-Oriented Object Notation) — відкритий формат, що з'явився 2025 року, і його офіційне позиціонування вкладається в одне речення: компактне, без втрат і читабельне кодування моделі даних JSON. Він не вводить нових типів — об'єкти, масиви, рядки, числа, булеві значення та null відповідають JSON один до одного, а decode(encode(x)) строго дорівнює вихідним даним (типи поза JSON, як-от Date чи NaN, треба нормалізувати заздалегідь). Round-trip є втратоменого та детермінованим: той самий вхід завжди дає той самий вихід, що важливо для відтворюваних промптів.
Оскільки TOON кодує точно модель даних JSON, правильний спосіб його застосування — це формат кордону: застосунок продовжує працювати в JSON усередині, конвертує в TOON безпосередньо перед передачею даних у промпт і конвертує назад із відповіді моделі. Офіційна документація називає це «translation layer». Умовне розширення файлів — .toon; для HTTP-транспорту попередній media type — text/toon, у UTF-8.
Одне застереження щодо пошукового шуму: не плутайте з Toon Shader у 3D-графіці. Спільне лише слово.
Чому JSON особливо дорогий на вході LLM
Візьміть список замовлень, перелік користувачів чи зведення логів, записані як JSON-масив. Токени витрачаються у трьох місцях:
- Повторювані назви ключів. П'ятдесят записів замовлень пишуть
"id","amount"і"status"по п'ятдесят разів кожне. Подвойте дані — подвойте надлишок. - Структурна пунктуація. Фігурні та квадратні дужки, двокрапки й коми — усе це токени, а вкладеність пакує їх ще щільніше.
- Лапки. Майже кожен ключ і кожне рядкове значення загорнуті у подвійні лапки.
Разом: вартість API, що тарифікується за токенами, зростає напряму; довгі входи раніше упираються в стелю контекстного вікна; а на дуже довгих входах модель частіше пропускає чи зміщує поля. Бенчмарк офіційної сторінки: на тестовому наборі зі змішаними структурами та чотирма моделями близько 40% менше токенів, а точність парсингу зростає з 70% (JSON) до 74% (TOON). Економія й точність тут не є трейд-оффом, бо компактніша структура робить межі помітнішими для моделі.
Синтаксис: індексовані об'єкти + табличні масиви
Ті самі дані прогнозу погоди у трьох формах. Версія JSON, приблизно 117 токенів:
{
"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 }
]
}
Версія TOON, приблизно 66 токенів:
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
Три форми покривають усе, і серіалізатор обирає їх автоматично за формою даних:
| Форма | Підходить для | Еквівалент у JSON |
|---|---|---|
| Індексований об'єкт | Вкладені об'єкти | { "location": { ... } }, індентація замінює фігурні дужки |
| Вбудований масив | Масиви примітивів | ["frost","wind"], [2] оголошує довжину |
| Табличний масив | Масиви однорідних об'єктів | Назви полів з'являються лише раз у заголовку {day,temp{min,max},...}; кожен рядок містить лише значення через кому |
Однорідні вкладені об'єкти (temp{min,max}) згортаються в заголовок як група вкладених полів, а рядки даних залишаються плоскими. Правило лапок — мінімальне: рядки беруть лапки лише якщо містять роздільники, спеціальні символи або ризикують бути прочитаними як числа — одна з причин, чому TOON перемагає «компактний JSON» у підрахунку токенів. Ключова різниця з YAML: TOON має явні оголошення довжини та заголовки полів, які можна перевірити машиною; з CSV — зберігає вкладеність і типи.
[N] і {fields}: структурні поручні для моделі
[3] і {day,...} потрібні не лише для економії токенів — це ще й перевірюваний контракт, який ви передаєте моделі:
- Довжина масиву дозволяє моделі одразу відповісти на «скільки записів у наборі даних» і миттєво викриває обрізання, коли кількість рядків не збігається.
- Заголовок полів оголошує назви один раз; модель вирівнює значення за позицією замість того, щоб щоразу вгадувати відповідність ключів у кожному рядку.
Це профілактика, протилежність постфактум-відновленню. JSON-репаратор (див. гід із відновлення) відновлює дані після того, як модель видала зламаний JSON; оголошення довжини та полів у TOON знижують на вході ймовірність зіпсованих даних. Робіть і те, й те — частота збоїв парсингу посеред конвеєра падає.
Коли не варто використовувати TOON
Офіційний розділ «When Not to Use TOON» вражаюче прямолінійний. Чотири сценарії, варто тримати їх такими, як є:
| Сценарій | Чому варто уникати | Кращий вибір |
|---|---|---|
| Глибоко вкладені, неоднорідні структури | Таблична придатність ≈ 0%; компактний JSON часто виграє | Компактний JSON |
| Напіводнорідні масиви | Нерегулярні поля, економія зникає | Тримайте JSON-конвеєр |
| Суто табличні дані | TOON коштує 5–10% надлишку проти CSV | CSV |
| Чутливі до затримки (локальні/квантизовані моделі) | Менше токенів ≠ швидший інференс | Спершу виміряйте TTFT |
Напіводнорідність оцінюють за табличною придатністю (tabular eligibility): офіційно, із придатністю 40–60% економія вже маргінальна. Міграція формату має реальну ціну — парсери, валідатори та скрипти нижче за течією змінюються всі — тож якщо виграш менший за десять відсотків, не чіпайте нічого.
Впровадження: encode / decode та CLI
Офіційна TypeScript-бібліотека, в обидва боки:
npm install @toon-format/toon
# Пакетна конвертація також іде через 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) // строго дорівнює вихідним даним
Існують реалізації Python, Go, Rust та .NET; перед тим як брати одну з них, звірте зі списком реалізацій в офіційному репозиторії специфікації та переконайтеся, що вона покриває синтаксичні можливості, якими ви користуєтесь. Перед продакшеном зробіть перевірку round-trip: decode(encode(оригінал)) має бути глибоко рівним оригіналу; якщо ні — проблема в реалізації або в даних.
Як це вписується у ваш наявний JSON-конвеєр
TOON нічого не змінює у вашому JSON-конвеєрі; він додає конвертацію на кордоні. Рекомендований порядок:
- Спершу переконайтеся, що JSON чистий. Зламаний JSON дає зламаний TOON. Синтаксичну перевірку й відновлення описано у Гіді з відновлення JSON.
- Перевірте форму даних. Усі об'єкти масиву мають однакові поля? Нормалізуйте спершу — або визнайте, що конвертація не варта зусиль.
- Конвертуйте й перевірте вибірково. Після конвертації звірте кілька рядків із оригінальним JSON, щоб пересвідчитися, що вирівнювання полів не зсунулося.
- Оцініть вигоду. Для однорідних списків рядкова логіка довідника JSONL застосовна до потокової конвертації; щодо співвідношення розміру й вартості — справжній зв'язок між JSON minify і gzip дає той самий урок: спершу міряти, потім конвертувати.
Чи замінить TOON JSON?
Ні. TOON кодує модель даних JSON; його місце — кордон промпту, тоді як зберігання й обмін між програмами лишаються територією JSON. Використовуйте TOON для сегмента «передати моделі» й залишайте решту ланцюга недоторканою.
Які стосунки в TOON із YAML та CSV?
Об'єкти схожі на YAML (індентація замість фігурних дужок); однорідні масиви схожі на CSV (заголовок оголошено раз, рядки потоково). Але TOON має явні оголошення довжини, яких немає в YAML, і зберігає вкладеність і типи, яких немає в CSV — він стоїть між ними, з перевірюваними машиною поручнями.
Чи втрачає дані конвертація TOON у JSON?
Ні: об'єкти, масиви, рядки, числа, булеві значення та null відповідають один до одного, а decode(encode(x)) строго дорівнює оригіналу. Єдине застереження — нормалізувати заздалегідь типи поза JSON, як-от Date і NaN; інакше рівність справедлива лише після round-trip.
Як перевірити, що конвертований TOON правильний?
Дві перевірки: перевірка round-trip (encode, потім decode, глибока рівність з оригіналом) і візуальний контроль заголовка — число [N] має дорівнювати кількості рядків, а поля {fields} мають вирівнюватися один до одного зі значеннями через кому в кожному рядку. На боці моделі можна також попросити її спершу повідомити довжину масиву, перш ніж відповідати.