TOON 格式指南:给 LLM 喂数据前,先把 JSON 瘦下来
结论:把同构数组喂给大模型时,JSON 里重复的键名与括号都在消耗 token。TOON 用缩进对象加表格数组把结构声明一次、数据逐行铺开,官方基准以少约 40% 的 token 换来更高解析准确率。本文讲清语法规则、省 token 的适用边界、何时不该转,以及 encode 与 decode 的接入方式。

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 花在三个地方:
- 重复的键名。50 条订单记录,
"id"、"amount"、"status"各写 50 遍。数据量翻倍,键名开销同步翻倍。 - 结构标点。花括号、方括号、冒号、逗号每个都占 token,嵌套越深越密。
- 引号。绝大多数键和字符串值都要双引号包裹。
这三项加起来的后果: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 环节,只是加一道边界转换。顺序建议:
- 先保证 JSON 本身干净。坏 JSON 转出来的 TOON 一样是坏的。语法校验或修复交给 JSON 修复指南里的解析链。
- 确认数据形态。数组里的对象字段是否齐整?不齐整先归一化,或者判断根本不值得转。
- 转换并核对。转出 TOON 后抽一条数据行与原 JSON 比对,确认字段对齐没有漂移。
- 估算收益。同构列表可参照 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 里要求它先报出数组长度再作答。