面向大模型开发：在项目中使用 TOON 的实践与流式处理

[面向大模型开发：在项目中使用 TOON 的实践与流式处理](#面向大模型开发：在项目中使用 TOON 的实践与流式处理)

[一、使用 npx 快速体验：将 JSON 转换为 TOON](#一、使用 npx 快速体验：将 JSON 转换为 TOON)

[二、项目中安装 TOON 依赖](#二、项目中安装 TOON 依赖)

[2、使用 encode 将 JSON 转换为 TOON](#2、使用 encode 将 JSON 转换为 TOON)

[3、使用 encodeLines 进行流式处理](#3、使用 encodeLines 进行流式处理)

[4、使用 replacer 在编码阶段做数据处理](#4、使用 replacer 在编码阶段做数据处理)

作者：watermelo37

CSDN优质创作者、华为云云享专家、阿里云专家博主、腾讯云"创作之星"特邀作者、火山KOL、支付宝合作作者，全平台博客昵称watermelo37。

一个假装是giser的coder，做不只专注于业务逻辑的前端工程师，Java、Docker、Python、LLM均有涉猎。

温柔地对待温柔的人，包容的三观就是最大的温柔。

面向大模型开发：在项目中使用 TOON 的实践与流式处理

TOON 入门到实战三部曲：

基础入门：TOON：一种为大模型设计的JSON压缩型数据结构

价值探究：探究TOON的价值边界：比JSON更优的大模型友好数据格式？

开发实战：面向大模型开发：在项目中使用 TOON 的实践与流式处理

前两篇文章中，我们已经介绍了 TOON 是什么，它的结构、特点和设计目标，也讨论了它的适用边界与实际收益。

这一篇将站在开发工程师的角度，聚焦两个更现实的问题：

在项目中，如何快速使用 TOON
当数据规模变大时，如何通过 TOON 配合流式处理，服务大模型输入

一、使用 npx 快速体验：将 JSON 转换为 TOON

如果只是想快速体验 TOON，而不想在项目中引入依赖，可以直接使用官方提供的 CLI 工具。

bash 复制代码

npx @toon-format/cli input.json -o output.toon

这个命令会读取本地目录内的 input.json，自动推断结构并输出对应的 .toon 文件。

具体操作为：新建一个文件夹，在其中创建一个 JSON 文件，并在地址栏直接输入 cmd 并回车：

输入上述指令，将 input.json 改成你实际的 JSON 文件名称，output.toon 改成你想要生成的文件名：

中途会问你是否继续，输入 y 并回车即可。最后生成了新的数据文件：

是不是很简单？

二、项目中安装 TOON 依赖

当你确认 TOON 确实适合你的数据结构后，就可以在项目中引入官方库。

1、安装命令

安装指令如下，根据自己的包管理工具三选一即可：

javascript 复制代码

# npm
npm install @toon-format/toon

# pnpm
pnpm add @toon-format/toon

# yarn
yarn add @toon-format/toon

2、使用 encode 将 JSON 转换为 TOON

在最常见的场景下，你可以直接在代码中完成转换：

javascript 复制代码

import { encode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Alice', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ]
}

console.log(encode(data))
// users[2]{id,name,role}:
//   1,Alice,admin
//   2,Bob,user

3、使用 encodeLines 进行流式处理

在数据量较大时，一次性 encode 整个对象效率就不够了，这个时候就最好使用流式处理的方式，这正是 encodeLines 的使用场景。

javascript 复制代码

import { encodeLines } from '@toon-format/toon'

const largeData = await fetchThousandsOfRecords()

// Memory-efficient streaming for large data
for (const line of encodeLines(largeData)) {
  process.stdout.write(`${line}\n`)
}

这种方式对内存友好，不会一次性构建完整字符串，并且天然适合流式输出，可直接接 SSE / WebSocket / 流式 Prompt，非常适合 LLM 长上下文拼接。

4、使用 replacer 在编码阶段做数据处理

encode 方法还提供了一个 replacer 替换器，可以在转换的时候加入特殊的规则，比如隐藏特殊字段或者改变大小写等：

javascript 复制代码

import { encode } from '@toon-format/toon'

// Remove sensitive fields
const user = { name: 'Alice', password: 'secret', email: 'alice@example.com' }
const safe = encode(user, {
  replacer: (key, value) => key === 'password' ? undefined : value
})
// name: Alice
// email: alice@example.com

// Transform values
const data = { status: 'active', count: 5 }
const transformed = encode(data, {
  replacer: (key, value) =>
    typeof value === 'string' ? value.toUpperCase() : value
})
// status: ACTIVE
// count: 5