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 里要求它先报出数组长度再作答。