Panduan Format TOON: Ringankan JSON Sebelum Memberikannya kepada LLM
Inti pati: Apabila anda menghantar tatasusunan seragam kepada model bahasa dalam format JSON, nama kunci berulang dan kurungan memakan token. TOON mengisytiharkan struktur sekali sahaja melalui objek berindenks dan tatasusunan berbentuk jadual, lalu mengetepikan data baris demi baris. Benchmark rasmi menunjukkan kira-kira 40% lebih sedikit token dengan ketepatan penghuraian lebih tinggi. Panduan ini meliputi sintaks, bila penjimatan berfungsi, bila penukaran tidak berbaloi, dan cara menyambungkan encode dengan decode.

Beban sintaks JSON tidak penting semasa pemindahan antara mesin, tetapi di sisi input LLM yang dibilkan mengikut token, ia wang sebenar: tatasusunan seragam yang sama mengulang nama kunci puluhan kali, dan setiap kurungan keriting berserta setiap petikan mengunyah sebahagian bajet. TOON tidak mencipta model data baharu — ia menulis semula model data JSON dengan notasi yang lebih murah.
Apakah TOON: satu lagi pengekodan JSON, bukan pesaing
TOON (Token-Oriented Object Notation) ialah format terbuka yang muncul pada 2025, dan kedudukan rasminya muat dalam satu ayat: pengekodan padat, tanpa kehilangan dan mudah dibaca bagi model data JSON. Ia tidak memperkenalkan jenis baharu — objek, tatasusunan, rentetan, nombor, boolean dan null sepadan satu-satu dengan JSON, dan decode(encode(x)) sama dengan data asal secara ketat (jenis di luar JSON seperti Date atau NaN perlu dinormalkan dahulu). Round-trip adalah tanpa kehilangan dan deterministik: input yang sama sentiasa menghasilkan output yang sama, penting untuk prompt yang boleh dihasilkan semula.
Memandangkan TOON mengekod tepat model data JSON, cara penggunaan yang betul ialah sebagai format sempadan: aplikasi terus bekerja dalam JSON di dalaman, bertukar ke TOON tepat sebelum meletakkan data ke dalam prompt, dan bertukar balik daripada jawapan model. Dokumentasi rasmi menamakannya "translation layer". Sambungan fail lazim ialah .toon; untuk pengangkutan HTTP, media type sementara ialah text/toon, dalam UTF-8.
Satu amaran tentang hingar carian: jangan kelirukan dengan Toon Shader dalam grafik 3D. Hanya perkataan yang sama.
Mengapa JSON terutamanya mahal di sisi input LLM
Ambil senarai pesanan, senarai pengguna atau ringkasan log yang ditulis sebagai tatasusunan JSON. Token dibelanjakan di tiga tempat:
- Nama kunci berulang. Lima puluh rekod pesanan menulis
"id","amount"dan"status"lima puluh kali setiap satu. Gandakan data — gandakan beban. - Tanda baca berstruktur. Kurungan keriting dan segi empat, titik bertindih dan koma — semuanya token, dan set cerunnya mengepam lebih padat lagi.
- Petikan. Hampir setiap kunci dan setiap nilai rentetan dibalut petikan berganda.
Jumlahnya: kos API yang dibilkan mengikut token naik terus; input panjang menjuarai siling tetingkap konteks lebih awal; dan pada input yang sangat panjang, model lebih kerap melangkau atau mengalihkan medan. Benchmark halaman rasmi: pada set ujian berstruktur bercampur dengan empat model, kira-kira 40% lebih sedikit token dengan ketepatan penghuraian menaik dari 70% (JSON) ke 74% (TOON). Penjimatan dan ketepatan bukan trade-off di sini, kerana struktur lebih padat menjadikan sempadan lebih jelas kepada model.
Sintaks: objek berindenks + tatasusunan berbentuk jadual
Data ramalan cuaca yang sama dalam tiga bentuk. Versi JSON, kira-kira 117 token:
{
"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 }
]
}
Versi TOON, kira-kira 66 token:
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
Tiga bentuk meliputi semuanya, dan pemerialisasi memilihnya secara automatik mengikut bentuk data:
| Bentuk | Sesuai untuk | Setara JSON |
|---|---|---|
| Objek berindenks | Objek bersarang | { "location": { ... } }, indenks menggantikan kurungan keriting |
| Tatasusunan dalam baris | Tatasusunan primitif | ["frost","wind"], [2] mengisytiharkan panjang |
| Tatasusunan berbentuk jadual | Tatasusunan objek seragam | Nama medan muncul sekali sahaja dalam pengepala {day,temp{min,max},...}; setiap baris hanya mengandungi nilai dipisahkan koma |
Objek bersarang seragam (temp{min,max}) melipat ke dalam pengepala sebagai kumpulan medan bersarang, manakala baris data kekal rata. Peraturan petikan adalah minimum: rentetan hanya mengambil petikan jika mengandungi pemisah, aksara khas atau berisiko dibaca sebagai nombor — satu sebab TOON menewaskan "JSON padat" dalam pengiraan token. Perbezaan utama dengan YAML: TOON mempunyai pengisytiharan panjang yang jelas dan pengepala medan yang boleh disahkan mesin; dengan CSV: mengekalkan cerun dan jenis.
[N] dan {fields}: penghalang berstruktur untuk model
[3] dan {day,...} bukan sekadar penjimatan token — ia juga kontrak yang boleh disahkan yang anda serahkan kepada model:
- Panjang tatasusunan membolehkan model menjawab terus "berapa rekod dalam set data" dan mendedahkan pemotongan serta-merta apabila bilangan baris tidak sepadan.
- Pengepala medan mengisytiharkan nama sekali; model menjajarkan nilai mengikut kedudukan dan bukannya meneka padanan kunci semula di setiap baris.
Ini pencegahan, bertentangan dengan pemulihan selepas fakta. Penyumbat JSON (lihat panduan pembaikan) menyelamatkan data selepas model memuntahkan JSON rosak; pengisytiharan panjang dan medan dalam TOON mengurangkan kebarangkalian data rosak di sisi input. Buat kedua-duanya — kadar kegagalan penghuraian di tengah saluran paip turun.
Bila Jangan Guna TOON
Bahagian rasmi "When Not to Use TOON" mengejutkan telusnya. Empat senario, biarkan ia seperti sedia ada:
| Senario | Mengapa dielakkan | Pilihan terbaik |
|---|---|---|
| Struktur bersarang dalam, tidak seragam | Kelayakan jadual ≈ 0%; JSON padat kerap menang | JSON padat |
| Tatasusunan separa seragam | Medan tidak tetap, penjimatan lenyap | Kekalkan saluran paip JSON |
| Data semata-mata jadual | TOON menanggung 5–10% beban berbanding CSV | CSV |
| Sensitif kependaman (model setempat/terkuantisasi) | Lebih sedikit token ≠ inferens lebih pantas | Ukur TTFT dahulu |
Separa seragam dinilai melalui kelayakan jadual (tabular eligibility): secara rasmi, pada kelayakan 40–60% penjimatan sudah marginal. Migrasi format ada kos sebenar — penghurai, pengesah dan skrip hiliran semuanya bertukar — jadi jika keuntungan di bawah sepuluh peratus, jangan sentuh apa-apa.
Pelaksanaan: encode / decode dan CLI
Pustaka TypeScript rasmi, ke kedua-dua arah:
npm install @toon-format/toon
# Penukaran pukal juga melalui 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) // sama dengan data asal secara ketat
Terdapat pelaksanaan Python, Go, Rust dan .NET; sebelum mengambil mana-mana satu, semak senarai pelaksanaan dalam repositori rasmi spesifikasi dan pastikan ia meliputi ciri sintaks yang anda gunakan. Sebelum ke pengeluaran, jalankan penegasan round-trip: decode(encode(asal)) mesti sama secara mendalam dengan asal; jika tidak, masalahnya pada pelaksanaan atau pada data.
Bagaimana ia muat ke dalam saluran paip JSON sedia ada anda
TOON tidak mengubah apa-apa dalam saluran paip JSON anda; ia menambah penukaran di sempadan. Turutan disyorkan:
- Dahulu pastikan JSON bersih. JSON rosak menghasilkan TOON rosak. Pengesahan sintaks dan pembaikan diliputi dalam Panduan Pembaikan JSON.
- Periksa bentuk data. Semua objek tatasusunan mempunyai medan sama? Normalkan dahulu — atau akui penukaran tidak berbaloi.
- Tukar dan persampelkan. Selepas penukaran, bandingkan beberapa baris dengan JSON asal untuk memastikan penjajaran medan tidak tergeser.
- Anggar manfaatnya. Untuk senarai seragam, penaakulan baris demi baris buku panduan JSONL turut terpakai bagi penukaran aliran; mengenai nisbah saiz dan kos, hubungan sebenar JSON minify dan gzip menyampaikan pelajaran sama: ukur dahulu, tukar kemudian.
Adakah TOON akan menggantikan JSON?
Tidak. TOON mengekod model data JSON; tempatnya ialah sempadan prompt, manakala storan dan pertukaran antara program kekal wilayah JSON. Gunakan TOON untuk segmen "beri kepada model" dan biarkan rantai selebihnya utuh.
Apakah hubungan TOON dengan YAML dan CSV?
Objek menyerupai YAML (indenks ganti kurungan keriting); tatasusunan seragam menyerupai CSV (pengepala diisytiharkan sekali, baris mengalir). Tetapi TOON mempunyai pengisytiharan panjang yang jelas yang tiada pada YAML, dan mengekalkan cerun serta jenis yang tiada pada CSV — ia berdiri di antara keduanya, dengan penghalang yang boleh disahkan mesin.
Adakah penukaran TOON ke JSON kehilangan data?
Tidak: objek, tatasusunan, rentetan, nombor, boolean dan null sepadan satu-satu, dan decode(encode(x)) sama secara ketat dengan asal. Hanya satu langkah berjaga — normalkan dahulu jenis di luar JSON seperti Date dan NaN; jika tidak, kesamaan hanya terpakai selepas round-trip.
Bagaimana saya memastikan TOON yang ditukar betul-betul betul?
Dua pemeriksaan: penegasan round-trip (encode kemudian decode, kesamaan mendalam dengan asal) dan pemeriksaan mata pengepala — nombor [N] mesti sama dengan bilangan baris, dan medan dalam {fields} mesti sejajar satu-satu dengan nilai dipisahkan koma pada setiap baris. Di sisi model, anda boleh meminta ia melaporkan panjang tatasusunan sebelum menjawab.