راهنمای فرمت TOON: سبکسازی JSON پیش از دادن به LLM
جمعبندی: وقتی آرایهای یکنواخت را با فرمت JSON به یک مدل زبانی میدهید، نام کلیدهای تکراری و پرانتزها توکن میبلورند. TOON ساختار را فقط یکبار با اشیای تورفتگیدار و آرایههای جدولی اعلام میکند و دادهها را خط به خط تخلیه میکند. بنچمارک رسمی حدود ۴۰٪ توکن کمتر با دقت پارس بالاتر را نشان میدهد. این راهنما سینتکس، زمانی که صرفهجویی کار میکند، زمانی که تبدیل ارزش ندارد و نحوهٔ اتصال encode و decode را پوشش میدهد.

بار نحوی JSON در انتقال بین ماشینها مهم نیست، اما در ورودیِ یک LLM که بر اساس توکن صورتحساب میدهد، پول واقعی است: همان آرایه یکنواخت نام کلیدها را دهها بار تکرار میکند و هر آکولاد با هر کوتیشن تکهای از بودجه را میبلعد. TOON مدل دادهٔ جدیدی اختراع نمیکند — مدل دادهٔ JSON را با نمادگذاری ارزانتری بازنویسی میکند.
TOON چیست: یک کدگذاری دیگر از JSON، نه رقیب
TOON (Token-Oriented Object Notation) فرمتی متنباز است که در ۲۰۲۵ ظاهر شد و جایگاه رسمیاش در یک جمله میگنجد: یک کدگذاری فشرده، بدون اتلاف و خوانا از مدل دادهٔ JSON. هیچ تایپ جدیدی معرفی نمیکند — اشیا، آرایهها، رشتهها، اعداد، بولینها و null یکبهیک با JSON متناظرند و decode(encode(x)) اکیداً برابر دادهٔ اصلی است (تایپهای خارج از JSON مانند Date یا NaN را باید قبلش نرمالسازی کنید). رفتوبرگشت بدون اتلاف و قطعی است: ورودی یکسان همیشه خروجی یکسان میدهد که برای پرامپتهای تکرارپذیر مهم است.
چون TOON دقیقاً مدل دادهٔ JSON را کدگذاری میکند، روش درست استفاده از آن فرمت مرزی است: برنامه در داخل به کار با JSON ادامه میدهد، درست پیش از گذاشتن دادهها در پرامپت به TOON تبدیل میکند و از پاسخ مدل دوباره برمیگرداند. مستندات رسمی به این «translation layer» میگوید. پسوند مرسوم فایلها .toon است؛ برای ترابری HTTP رسانهٔ موقت text/toon است، در UTF-8.
یک هشدار دربارهٔ نویز جستوجو: با Toon Shader در گرافیک سهبعدی اشتباه نگیرید. فقط کلمه مشترک است.
چرا JSON در ورودی LLM بهخصوص گران است
فهرست سفارشها، لیست کاربران یا خلاصهٔ لاگها را که به شکل آرایهٔ JSON نوشته شده در نظر بگیرید. توکنها در سه جا خرج میشوند:
- نام کلیدهای تکراری. پنجاه رکورد سفارش،
"id"و"amount"و"status"را هرکدام پنجاه بار مینویسد. داده را دوبرابر کن، بار اضافی هم دوبرابر میشود. - علائم ساختاری. آکولاد و براکت، دونقطه و ویرگول — همه توکناند و تودرتویی آنها را متراکمتر بستهبندی میکند.
- کوتیشنها. تقریباً هر کلید و هر مقدار رشتهای در گیومه پیچیده شده است.
جمعش کنید: هزینهٔ API مبتنی بر توکن مستقیماً بالا میرود؛ ورودیهای بلند زودتر به سقف پنجرهٔ کانتکست میخورند؛ و در ورودیهای خیلی بلند مدل بیشتر فیلدها را حذف یا جابهجا میکند. بنچمارک صفحهٔ رسمی: روی مجموعهٔ تست با ساختارهای ترکیبی و چهار مدل، حدود ۴۰٪ توکن کمتر همراه با دقت پارسی که از ۷۰٪ (JSON) به ۷۴٪ (TOON) میرسد. صرفهجویی و دقت اینجا ترید-آف نیستند، چون ساختار فشردهتر مرزها را برای مدل واضحتر میکند.
سینتکس: اشیای تورفتگیدار + آرایههای جدولی
همان دادههای پیشبینی آبوهوا در سه شکل. نسخهٔ JSON، حدود ۱۱۷ توکن:
{
"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، حدود ۶۶ توکن:
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» بهطرز تازهکنندهای صریح است. چهار سناریو، همانطور که هست نگهشان دارید:
| سناریو | چرا پرهیز کنیم | انتخاب بهتر |
|---|---|---|
| ساختارهای عمیقاً تودرتو و نایکنواخت | قابلیت جدولی ≈ ۰٪؛ JSON فشرده اغلب میبرد | JSON فشرده |
| آرایههای نیمهیکنواخت | فیلدهای نامنظم، صرفهجویی محو میشود | خط لولهٔ JSON را نگه دارید |
| دادههای صرفاً جدولی | TOON نسبت به CSV ۵ تا ۱۰٪ سربار دارد | CSV |
| حساس به تأخیر (مدلهای محلی/کوانتیزه) | توکن کمتر ≠ استنتاج سریعتر | اول TTFT را بسنجید |
نیمهیکنواختی را با قابلیت جدولی (tabular eligibility) میسنجند: رسماً، با قابلیت ۴۰ تا ۶۰٪ صرفهجویی از قبل حاشیهای است. مهاجرت فرمت هزینهٔ واقعی دارد — پارسرها، اعتبارسنجها و اسکریپتهای پاییندستی همه عوض میشوند — پس اگر سود زیر ده درصد است، هیچچیز را لمس نکنید.
پیادهسازی: 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 هم وجود دارد؛ پیش از پذیرش یکی، با فهرست پیادهسازیها در مخزن رسمی مشخصات تطبیق دهید و مطمئن شوید ویژگیهای نحوی مورد استفادهتان را پوشش میدهد. قبل از پروداکشن یک ادعای رفتوبرگشت اجرا کنید: 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 را قبلش نرمالسازی کنید؛ وگرنه برابری فقط بعد از رفتوبرگشت برقرار است.
چگونه صحت TOON تبدیلشده را بررسی کنم؟
دو بررسی: ادعای رفتوبرگشت (encode و سپس decode، برابری عمیق با اصلی) و بازبینی چشمی هدر — عدد [N] باید برابر تعداد خطوط باشد و فیلدهای {fields} باید یکبهیک با مقادیر جداشده با ویرگول هر خط تراز شوند. در سمت مدل میتوانید پیش از پاسخ، از او بخواهید طول آرایه را گزارش کند.