מדריך פורמט 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 צריך לנרמל מראש). הסבב ללא אובדן ודטרמיניסטי: קלט זהה תמיד מניב פלט זהה, דבר חשוב לבניית פרומפטים שניתנים לשחזור.
מכיוון ש-TOON מקודד בדיוק את מודל הנתונים של JSON, הדרך הנכונה להשתמש בו היא פורמט גבול: היישומון ממשיך לעבוד ב-JSON בפנים, ממיר ל-TOON ממש לפני הכנסת הנתונים לפרומפט, וממיר חזרה מתשובת המודל. התיעוד הרשמי קורא לזה "translation layer". סיומת הקבצים המקובלת היא .toon; להעברה ב-HTTP סוג המדיה הזמני הוא text/toon, ב-UTF-8.
אזהרה אחת לגבי רעש חיפוש: אל תבלבלו עם Toon Shader בגרפיקת תלת-ממד. המשותף רק המילה.
למה 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; לפני שבוחרים אחד, השוו עם רשימת המימושים במאגר הרשמי של המפרט ווודאו שהוא מכסה את יכולות התחביר שאתם משתמשים בהן. לפני פרודקשן הריצו טענת סבב: 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} חייבים להיות מיושרים אחד לאחד עם הערכים מופרדים בפסיקים בכל שורה. בצד המודל אפשר גם לבקש ממנו לדווח על אורך המערך לפני שהוא עונה.