JSON 工具箱

TOON 格式指南:給 LLM 餵資料前,先把 JSON 瘦下來

結論:把同構陣列餵給大模型時,JSON 裡重複的鍵名與括號都在消耗 token。TOON 用縮進物件加表格陣列把結構宣告一次、資料逐行鋪開,官方基準以少約 40% 的 token 換來更高解析準確率。本文講清語法規則、省 token 的適用邊界、何時不該轉,以及 encode 與 decode 的接入方式。

入門約 6 分鐘發佈於 2026-11-10更新於 2026-11-10
TOON 表格陣列語法示意:欄位頭宣告一次,資料行逐行鋪開

JSON 的語法開銷在機器對機器傳輸時無所謂,在按 token 計費的 LLM 輸入端卻成了真金白銀:同一份同構陣列,鍵名重複幾十遍,括號引號各佔一份額度。TOON 的思路不是發明新資料模型,而是把 JSON 資料模型換一種更省 token 的寫法。

TOON 是什麼:JSON 的另一種編碼,不是競爭對手

TOON(Token-Oriented Object Notation,面向 token 的物件表示法)是 2025 年推出的開放格式,官方定位一句話說清:JSON 資料模型的緊湊、無損、人類可讀編碼。它不引入任何新型別——物件、陣列、字串、數字、布林、null 與 JSON 一一對應,decode(encode(x)) 嚴格等於原資料(Date、NaN 這類非 JSON 型別除外,需先規範化)。往返是無損且確定性的:同樣的輸入永遠得到同樣的輸出,這一點對可復現的 prompt 建構很重要。

正因為編碼物件就是 JSON 資料模型,TOON 的正確用法是當邊界格式:程式內部照舊用 JSON 跑業務邏輯,只在把資料放進 prompt 之前轉一次 TOON;模型返回後再轉回 JSON 處理。官方文件的表述是 "translation layer"(翻譯層)。檔案後綴慣例是 .toon,HTTP 傳輸用臨時 media type text/toon,UTF-8 編碼。

檢索時注意一個噪音源:別把它和圖形領域的 Toon Shader(卡通渲染著色器)混淆,兩者毫無關係。中文社群 2026 年的討論裡(比如 Nexius 的《TOON 資料格式》)都特意標注了這一點。

為什麼 JSON 在 LLM 輸入端特別貴

一份訂單列表、用戶名單或日誌摘要,寫成 JSON 陣列後 token 花在三個地方:

  1. 重複的鍵名。50 條訂單記錄,"id"、"amount"、"status" 各寫 50 遍。資料量翻倍,鍵名開銷同步翻倍。
  2. 結構標點。花括號、方括號、冒號、逗號每個都佔 token,嵌套越深越密。
  3. 引號。絕大多數鍵和字串值都要雙引號包裹。

這三項加起來的後果:API 費用按 token 計價直接變高;更長的輸入更容易頂到上下文視窗上限;超長輸入下模型漏欄位、錯欄位的機率也會上升。TOON 官方首頁給的基準是:混合結構測試集上,4 個模型平均 token 少約 40%,解析準確率反而從 JSON 的 70% 升到 74%——省 token 和準確率在這裡不是取捨關係,因為更緊湊的結構讓模型更容易看清邊界。

語法拆解:縮進物件 + 表格陣列

看同一個天氣預報資料的三種形態。JSON 版約 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 }
  ]
}

TOON 版約 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

三種形態各管一攤,序列化器按資料形狀自動選擇:

形態 適用資料 對應 JSON
縮進物件 嵌套物件 { "location": { ... } },縮進替代花括號
內聯陣列 原始值陣列 ["frost","wind"],[2] 宣告長度
表格陣列 同構物件陣列 欄位名只在表頭 {day,temp{min,max},...} 出現一次,每行只放逗號分隔的值

嵌套的同構物件(temp{min,max})會摺疊進表頭成為嵌套欄位組,資料行保持扁平。引號規則是最小引號化:只在字串含分隔符、特殊字元或會被誤讀成數字時才加引號——這正是它比「壓縮 JSON」更省的原因之一。與 YAML 的關鍵區別是 TOON 有顯式長度宣告與欄位頭,機器可校驗;與 CSV 的區別是它還保留嵌套與型別。

[N] 與 {fields}:給模型的結構護欄

[3] 和 {day,...} 不只是省 token 的手段,更是餵給模型的可校驗契約:

  • 陣列長度讓模型可以直接回答「資料集有幾條」這類問題,也能在輸出或讀取時發現行數對不上——截斷立刻暴露。
  • 欄位頭把欄位名宣告一次,模型按位置對齊取值,減少了在每行裡重新猜鍵名對應關係的出錯面。

這一點和事後救火是兩個思路。JSON 修復器(比如昨天講的修復管線)是在模型吐出壞 JSON 之後救回資料;TOON 的長度與欄位宣告是在輸入側降低出壞資料的機率。兩頭都做,中間的解析失敗率才壓得下來。

什麼時候別用 TOON

官方「何時不適用」一節寫得非常直白,四個場景照抄不虧:

場景 為什麼別轉 更好的選擇
深層嵌套、結構不齊 表格化資格≈0%,緊湊 JSON 往往更省 緊湊 JSON
半同構陣列 欄位參差,收益縮水到幾無 維持 JSON 管線
純扁平表格 TOON 比 CSV 多 5–10% 結構開銷 CSV
延遲敏感(本地/量化模型) token 少不等於推理快 實測 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 等實作以官方 spec 儲存庫的實作列表為準,接入前先確認目標語言實作已覆蓋你要用的語法特性。上生產前做一次往返斷言:decode(encode(原資料)) 與原資料深度相等,不等就說明實作或資料有坑。

與現有 JSON 工具鏈怎麼配合

TOON 不改變你現有的任何 JSON 環節,只是加一道邊界轉換。順序建議:

  1. 先保證 JSON 本身乾淨。壞 JSON 轉出來的 TOON 一樣是壞的。語法校驗或修復交給 JSON 修復指南裡的解析鏈。
  2. 確認資料形態。陣列裡的物件欄位是否齊整?不齊整先歸一化,或者判斷根本不值得轉。
  3. 轉換並核對。轉出 TOON 後抽一條資料行與原 JSON 比對,確認欄位對齊沒有漂移。
  4. 估算收益。同構列表可參照 JSONL 檔案手冊的逐行思路做流式轉換;體積與 token 的關係可類比 JSON Minify 與 Gzip 的真實關係——兩者都說明「先量再轉」比「先轉再說」便宜得多。

TOON 會取代 JSON 嗎?

不會。TOON 編碼的就是 JSON 資料模型,定位是 prompt 邊界的表示層,程式間的儲存與交換仍是 JSON 的地盤。把 TOON 用在「餵給模型」這一段,其餘鏈路不動。

TOON 和 YAML、CSV 什麼關係?

物件部分像 YAML(縮進替代括號),同構陣列像 CSV(表頭宣告一次、每行流式鋪值)。但 TOON 有 YAML 沒有的顯式長度宣告,也有 CSV 沒有的嵌套與型別保留——它取的是兩者的中間態,並加了機器可校驗的結構護欄。

TOON 轉 JSON 會不會丟資料?

無損:物件、陣列、字串、數字、布林、null 全部一一對應,decode(encode(x)) 嚴格相等。唯一要注意的是 Date、NaN 這類非 JSON 型別要先規範化,否則往返後才相等。

怎麼驗證轉出來的 TOON 是對的?

兩條:一是往返斷言,encode 再 decode 與原資料深度相等;二是人工抽查表頭與欄位組——[N] 的數字要等於資料行數,{fields} 的欄位要與每行的逗號分隔值一一對齊。模型端還可以在 prompt 裡要求它先報出陣列長度再作答。