Руководство по формату 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} должны выравниваться один к одному со значениями через запятую в каждой строке. На стороне модели можно также попросить её сначала сообщить длину массива, прежде чем отвечать.