99中文字幕精品国产,国产不卡精品视频男人的天堂,在线高清免费不卡全码

TOON 協議與 AIDotNet.Toon 實踐指南

一、TOON 是什么

官方定義要點摘錄（來源：toon-format/toon 倉庫 README）：

Token-efficient：通常比 JSON 少 30–60% 的 tokens（Key Features 列表）
LLM-friendly guardrails：顯式長度與字段，便于驗證
Minimal syntax：移除冗余標點（大括號、方括號、許多引號）
Indentation-based structure：類似 YAML，以空白縮進代替大括號
Tabular arrays：一次聲明列頭，數據按行流式書寫

官方基準與工具：

README 的 Benchmarks 表格展示了多個數據集下的 token 節省比例；此外提供“Format Tokenization Playground”可交互比較不同格式的 token 用量
當前規范版本：v1.3（README 徽章與 SPEC.md 指向的專用倉庫）

規范入口與一致性：

規范遷移至獨立倉庫：https://github.com/toon-format/spec（SPEC.md 明確“moved to a dedicated repository”）
跨語言一致性依賴 conformance tests（README 的 Other Implementations 區塊提供說明）

二、為什么 TOON 相比 JSON 更省 tokens

本質原因是“以結構換冗余”：在 LLM 語境下，重復的鍵名和標點都會占用 tokens。TOON 通過以下策略顯著減少冗余（均可在 README 與語法速查中找到實例）：

表格數組：為均勻對象數組聲明一次列頭，如 users[2]{id,name}: 后續行直接寫 1,Alice
行內原子數組：tags[3]: a,b,c，避免多余方括號與引號
鍵名可不加引號：安全鍵裸寫，減少引號數量
縮進代替大括號：以空白表達層級

同時，官方 README 也清晰指出邊界：對于深度嵌套或非均勻結構的數據，JSON 可能更高效。這意味著在“樹深且分支不規則”的任務上應優先評估 JSON。

三、語法速查與對照示例

下列示例與含義對應自 README 的 Syntax Cheatsheet 與“Why TOON”示例（術語與格式請以規范 v1.3 為準）：

對象
{ id: 1, name: 'Ada' } → id: 1 換行 name: Ada
嵌套對象
{ user: { id: 1 } } → user: 換行縮進 id: 1
行內原子數組
{ tags: ['foo', 'bar'] } → tags[2]: foo,bar
表格數組（均勻對象）
{ items: [ { id: 1, qty: 5 }, { id: 2, qty: 3 } ] }
→ items[2]{id,qty}: 換行縮進 1,5 換行縮進 2,3
混合或非均勻數組
{ items: [ 1, { a: 1 }, 'x' ] } → items[3]: 換行縮進 - 1 換行縮進 - a: 1 換行縮進 - x

四、AIDotNet.Toon：.NET 實現概覽

AIDotNet.Toon 對齊 upstream 規范與設計，面向 .NET 提供與 System.Text.Json 風格一致的 API。關鍵入口如下：

序列化： C#.ToonSerializer.Serialize() · C#.ToonSerializer.Serialize()
反序列化： C#.ToonSerializer.Deserialize() · C#.ToonSerializer.Deserialize()
編碼實現： C#.ToonEncoder.Encode()
解碼實現： C#.ToonDecoder.DecodeToJsonString()
選項模型： C#.ToonSerializerOptions · 分隔符枚舉 C#.ToonDelimiter · 默認實例 C#.ToonSerializerOptions.Default
錯誤模型： C#.ToonFormatException

實現思路（節選自源碼注釋與 README）：

Encode 路徑：.NET 對象 → JsonElement → Encoders 結構化寫出（對象、行內原子數組、表格數組、列表回退等）
Decode 路徑：TOON → 規范化 JSON 字符串 → System.Text.Json 反序列化為目標類型
數值與特殊值：允許命名浮點字面量，經編碼階段將 NaN 與 ±Infinity 規范化為 null，-0 規范化為 0（細節見編碼器與選項）

五、安裝與快速開始

通過 NuGet（發布后）或源碼引入本庫：

dotnet add package AIDotNet.Toon

using AIDotNet.Toon;

var options = new ToonSerializerOptions
{
    Indent = 2,
    Delimiter = ToonDelimiter.Comma,
    Strict = true,
    LengthMarker = null
};

var data = new
{
    users = new[] { new { id = 1, name = "Alice" }, new { id = 2, name = "Bob" } },
    tags = new[] { "a", "b", "c" },
    numbers = new[] { 1, 2, 3 }
};

var text = ToonSerializer.Serialize(data, options);
// users[2]{id,name}:
//   1,Alice
//   2,Bob
// tags[3]: a,b,c
// numbers[3]: 1,2,3

讀取原子值：

var s = ToonSerializer.Deserialize<string>("hello", options);   // "hello"
var n = ToonSerializer.Deserialize<double>("3.1415", options);  // 3.1415

互操作：TOON ? JSON ? .NET

// 將 TOON 文本轉為目標類型，內部先經 [C#.ToonDecoder.DecodeToJsonString()](src/AIDotNet.Toon/ToonDecoder.cs:15)
var user = ToonSerializer.Deserialize<Dictionary<string, object>>("id: 1", options);

// 將 .NET 對象經 JSON DOM 編碼為 TOON
var t = ToonSerializer.Serialize(new { id = 1, name = "Ada" }, options);

六、選項與行為

統一選項入口 C#.ToonSerializerOptions 與默認預設 C#.ToonSerializerOptions.Default：

Indent：每級縮進空格數，默認 2
Delimiter：分隔符，枚舉 C#.ToonDelimiter，用于行內與表格；底層轉換為具體字符見 C#.ToonSerializerOptions.GetDelimiterChar()
Strict：嚴格模式，校驗縮進、空行、計數一致性等
LengthMarker：數組長度標記，僅支持 # 或 null
JsonOptions：直通 System.Text.Json；默認啟用 AllowNamedFloatingPointLiterals，并注冊轉換器以將 NaN 與 ±Infinity 寫出為 null

七、錯誤模型與定位

解碼錯誤統一拋出 C#.ToonFormatException 并包含錯誤分類與位置信息：

工廠方法：Syntax C#.ToonFormatException.Syntax() · Range C#.ToonFormatException.Range() · Validation C#.ToonFormatException.Validation() · Indentation C#.ToonFormatException.Indentation() · Delimiter C#.ToonFormatException.Delimiter()

八、進階示例

表格數組寫出

var rows = new[] { new { id = 1, name = "alice" }, new { id = 2, name = "bob" } };
var toon = ToonSerializer.Serialize(rows, options);
// [2]{id,name}:
//   1,alice
//   2,bob

行內原子數組

var arr = new[] { 1, 2, 3 };
var t2 = ToonSerializer.Serialize(arr, options); // "[3]: 1,2,3"

混合數組回退為列表

var mixed = new object[] { 1, new { a = 1 }, "x" };
var t3 = ToonSerializer.Serialize(mixed, options);
// [3]:
//   - 1
//   - a: 1
//   - x

九、何時使用 TOON，何時選 JSON

基于官方 README 的定位：當你的數據是“均勻對象數組、字段重復較多、需要給 LLM 更大輸入上下文”時，TOON 通常更省 tokens 且更易校驗驗證；當數據“深度嵌套、非均勻或樹形變化大”時，JSON 可能更高效更直接。

十、數據流與實現關系圖

十一、來源與參考

官方倉庫與 README：https://github.com/toon-format/toon
規范倉庫 v1.3：https://github.com/toon-format/spec
README“Key Features”“Benchmarks”“Syntax Cheatsheet”“Other Implementations”板塊提供了本文引用的特性描述、節省比例與示例
本文 .NET 實現地址：https://github.com/AIDotNet/Toon.NET

十二、結語

TOON 讓 LLM 輸入里的結構化數據更加緊湊、可校驗、可讀；AIDotNet.Toon 則在 .NET 世界提供熟悉的 API 體驗與選項模型。建議從表格數組與行內原子數組的典型場景開始落地，并結合規范 v1.3 與測試數據持續驗證。

Special thanks to the upstream project toon-format.

附：官方 Benchmarks 數據集節選

以下數字直接摘錄自官方 README 的 Benchmarks「Token Efficiency」小節，原文與上下文見：https://github.com/toon-format/toon#benchmarks（其中提示這些數據集偏向 TOON 的優勢場景：均勻表格化數據，真實效果取決于數據結構）。交互式對比工具：

Token 效率

? GitHub Repositories ██████████████??????????? 8,745 tokens
vs JSON (-42.3%) 15,145
vs JSON compact (-23.7%) 11,455
vs YAML (-33.4%) 13,129
vs XML (-48.8%) 17,095

?? Daily Analytics ██████████??????????????? 4,507 tokens
vs JSON (-58.9%) 10,977
vs JSON compact (-35.7%) 7,013
vs YAML (-48.8%) 8,810
vs XML (-65.7%) 13,128

?? E-Commerce Order ████████████████????????? 166 tokens
vs JSON (-35.4%) 257
vs JSON compact (-2.9%) 171
vs YAML (-15.7%) 197
vs XML (-38.7%) 271

─────────────────────────────────────────────────────────────────────
Total ██████████████??????????? 13,418 tokens
vs JSON (-49.1%) 26,379
vs JSON compact (-28.0%) 18,639
vs YAML (-39.4%) 22,136
vs XML (-56.0%) 30,494

檢索準確率

4 種大型語言模型在 154 個數據檢索問題上的準確率：

gpt-5-nano
→ TOON ███████████████████? 96.1% (148/154)
CSV ██████████████████?? 91.6% (141/154)
YAML ██████████████████?? 91.6% (141/154)
JSON compact ██████████████████?? 91.6% (141/154)
XML █████████████████??? 87.0% (134/154)
JSON █████████████████??? 86.4% (133/154)

claude-haiku-4-5-20251001
JSON ██████████?????????? 50.0% (77/154)
YAML ██████████?????????? 49.4% (76/154)
→ TOON ██████████?????????? 48.7% (75/154)
XML ██████████?????????? 48.1% (74/154)
CSV █████████??????????? 47.4% (73/154)
JSON compact █████████??????????? 44.2% (68/154)

gemini-2.5-flash
CSV ██████████████████?? 87.7% (135/154)
XML ██████████████████?? 87.7% (135/154)
→ TOON █████████████████??? 86.4% (133/154)
YAML ████████████████???? 79.9% (123/154)
JSON compact ████████████████???? 79.9% (123/154)
JSON ███████████████????? 76.6% (118/154)

grok-4-fast-non-reasoning
→ TOON ██████████?????????? 49.4% (76/154)
JSON ██████████?????????? 48.7% (75/154)
XML █████████??????????? 46.1% (71/154)
YAML █████████??????????? 46.1% (71/154)
JSON compact █████████??????????? 45.5% (70/154)
CSV █████████??????????? 44.2% (68/154)

注意：上述樣本強調 TOON 在“均勻對象數組/表格化數據”場景的節省效果；對于深度嵌套或非均勻數據，官方 README 指出 JSON 可能更高效。建議在落地前結合自身數據結構評估與小規模驗證。

posted on 2025-11-04 12:52 239573049 閱讀(167) 評論(0) 收藏舉報

刷新頁面返回頂部

檢索準確率

公告