gpt-tokenizer

gpt-tokenizer 是一个支持所有 OpenAI 模型（包括 GPT-5、GPT-4o、o1、o3、o4、GPT-4.1 以及更早的 GPT-3.5 和 GPT-4 等）的字节对编码器/解码器。它是适用于所有 JavaScript 环境的 [最快、最小且占用资源最少] 的 GPT 分词器，并使用 TypeScript 编写。

快来 游乐场 体验吧！

该库已被以下公司和项目信赖：

• 微软（Teams、GenAIScript）
• Elastic（Kibana）
• Effect TS
• CodeRabbit
• Ironclad 的 Rivet

如果您觉得这个项目有用，请考虑 🩷 赞助 该项目。

特性

它是 NPM 上功能最完整、开源的 GPT 分词器。本包是对 OpenAI 的 tiktoken 的移植，并在此基础上添加了一些独特的功能：

• 通过 encodeChat 函数轻松对聊天内容进行分词
• 支持当前所有 OpenAI 模型（可用编码：r50k_base、p50k_base、p50k_edit、cl100k_base、o200k_base 和 o200k_harmony）
• 可以同步加载并运行！（即在非 async/await 上下文中也能使用）
• 解码器和编码器函数均提供生成器版本
• 提供解码异步数据流的能力（使用 decodeAsyncGenerator 和 decodeGenerator，可处理任何可迭代输入）
• 无全局缓存（不会像原始 GPT-3 编码器实现那样出现意外内存泄漏）
• 内置高性能的 isWithinTokenLimit 函数，无需对整段文本或聊天内容进行编码即可评估是否超出 token 限制
• 内置成本估算功能 estimateCost，用于计算 API 使用成本
• 包含完整的 OpenAI 模型库及详尽的价格信息（参见 src/models.ts 和 src/models.gen.ts）
• 通过消除传递性数组提升了整体性能
• 类型安全（使用 TypeScript 编写）
• 在浏览器中开箱即用

安装

作为 NPM 包

npm install gpt-tokenizer

作为 UMD 模块

<script src="https://unpkg.com/gpt-tokenizer"></script>

<script>
  // 现在可以通过全局变量访问该包：
  const { encode, decode } = GPTTokenizer_cl100k_base
</script>

如果您希望使用自定义编码，请加载相应的脚本。

• https://unpkg.com/gpt-tokenizer/dist/o200k_base.js（适用于所有现代模型，如 gpt-5、gpt-4o、gpt-4.1、o1 等）
• https://unpkg.com/gpt-tokenizer/dist/o200k_harmony.js（适用于开放权重的 Harmony 模型，如 gpt-oss-20b 和 gpt-oss-120b）
• https://unpkg.com/gpt-tokenizer/dist/cl100k_base.js（适用于 gpt-4 和 gpt-3.5）
• https://unpkg.com/gpt-tokenizer/dist/p50k_base.js
• https://unpkg.com/gpt-tokenizer/dist/p50k_edit.js
• https://unpkg.com/gpt-tokenizer/dist/r50k_base.js

全局变量名格式为：GPTTokenizer_${encoding}。

更多信息请参阅 支持的模型及其编码 部分。

游乐场

游乐场已发布在一个便于记忆的 URL 上：https://gpt-tokenizer.dev/

使用方法

该库提供了多种函数，用于将文本转换为（以及从）可输入大型语言模型的整数序列（即标记）。这种转换是通过 OpenAI 使用的字节对编码（BPE）算法实现的。

import {
  encode,
  encodeChat,
  decode,
  isWithinTokenLimit,
  encodeGenerator,
  decodeGenerator,
  decodeAsyncGenerator,
  ALL_SPECIAL_TOKENS,
} from 'gpt-tokenizer'
// 注意：根据模型的不同，需从相应的文件中导入，例如：
// import {...} from 'gpt-tokenizer/model/gpt-4o'

const text = 'Hello, world!'
const tokenLimit = 10

// 将文本编码为标记
const tokens = encode(text)

// 将标记解码回文本
const decodedText = decode(tokens)

// 检查文本是否在标记限制内
// 如果超出限制则返回 false，否则返回实际的标记数量（真值）
const withinTokenLimit = isWithinTokenLimit(text, tokenLimit)

// 在需要时允许特殊标记
const withinTokenLimitWithSpecial = isWithinTokenLimit(text, tokenLimit, {
  allowedSpecial: ALL_SPECIAL_TOKENS,
})

// 示例对话：
const chat = [
  { role: 'system', content: '你是一个有用的助手。' },
  { role: 'assistant', content: 'gpt-tokenizer 非常棒。' },
] as const

// 将对话编码为标记
const chatTokens = encodeChat(chat)

// 检查对话是否在标记限制内
const chatWithinTokenLimit = isWithinTokenLimit(chat, tokenLimit)

const chatWithinTokenLimitWithSpecial = isWithinTokenLimit(chat, tokenLimit, {
  allowedSpecial: ALL_SPECIAL_TOKENS,
})

// 使用生成器编码文本
for (const tokenChunk of encodeGenerator(text)) {
  console.log(tokenChunk)
}

// 使用生成器解码标记
for (const textChunk of decodeGenerator(tokens)) {
  console.log(textChunk)
}

// 使用异步生成器解码标记
// （假设 `asyncTokens` 是一个 AsyncIterableIterator<number））
for await (const textChunk of decodeAsyncGenerator(asyncTokens)) {
  console.log(textChunk)
}

默认情况下，从 gpt-tokenizer 导入会使用 o200k_base 编码，所有现代 OpenAI 模型都采用此编码，包括 gpt-4o、gpt-4.1、o1 等。

若需获取其他模型的分词器，可直接导入，例如：

import {
  encode,
  decode,
  isWithinTokenLimit,
  // 等等...
} from 'gpt-tokenizer/model/gpt-3.5-turbo'

如果使用的解析器不支持 package.json 的 exports 解析，可能需要从相应的 cjs 或 esm 目录中导入，例如：

import {
  encode,
  decode,
  isWithinTokenLimit,
  // 等等...
} from 'gpt-tokenizer/cjs/model/gpt-3.5-turbo'

延迟加载

如果您不介意以异步方式加载分词器，可以在函数内部使用动态导入，如下所示：

const {
  encode,
  decode,
  isWithinTokenLimit,
  // 等等...
} = await import('gpt-tokenizer/model/gpt-3.5-turbo')

加载自定义编码

如果您的模型未被本包支持，但您知道它使用的 BPE 编码，可以直接加载该编码，例如：

import {
  encode,
  decode,
  isWithinTokenLimit,
  // 等等...
} from 'gpt-tokenizer/encoding/cl100k_base'

支持的模型及其编码

我们支持所有 OpenAI 模型，包括最新版本，具体编码如下：

• o 系列模型，如 o1-*、o3-* 和 o4-*（o200k_base）
• gpt-4o（o200k_base）
• gpt-oss-*（o200k_harmony）
• gpt-4-*（cl100k_base）
• gpt-3.5-*（cl100k_base）
• text-davinci-003（p50k_base）
• text-davinci-002（p50k_base）
• text-davinci-001（r50k_base）
• …以及其他众多模型，详情请参阅 models.ts，其中列出了当前支持的模型及其编码。

如果您没有找到所需的模型，那么默认编码很可能就是您所需要的。

API

encode(text: string, encodeOptions?: EncodeOptions): number[]

将给定文本编码为标记序列。当您需要将一段文本转换为 GPT 模型可处理的标记格式时，请使用此方法。

可选的 encodeOptions 参数允许您指定特殊标记的处理方式（详见特殊标记）。

示例：

import { encode } from 'gpt-tokenizer'

const text = 'Hello, world!'
const tokens = encode(text)

decode(tokens: number[]): string

将标记序列解码回文本。当您希望将 GPT 模型的输出标记转换为人类可读的文本时，请使用此方法。

示例：

import { decode } from 'gpt-tokenizer'

const tokens = [18435, 198, 23132, 328]
const text = decode(tokens)

isWithinTokenLimit(text: string | Iterable<ChatMessage>, tokenLimit: number, encodeOptions?: EncodeOptions): false | number

检查输入是否在标记限制内。如果超出限制则返回 false，否则返回标记数量。当您需要快速检查给定文本或对话是否在 GPT 模型的标记限制范围内，而无需对整个输入进行编码时，可使用此方法。可选的 encodeOptions 参数允许您配置特殊标记的处理方式。

示例：

import { isWithinTokenLimit, ALL_SPECIAL_TOKENS } from 'gpt-tokenizer'

const text = 'Hello, world!'
const tokenLimit = 10
const withinTokenLimit = isWithinTokenLimit(text, tokenLimit)

const withinTokenLimitWithSpecial = isWithinTokenLimit(text, tokenLimit, {
  allowedSpecial: ALL SPECIAL TOKENS,
})

countTokens(text: string | Iterable<ChatMessage>, encodeOptions?: EncodeOptions): number

统计输入文本或对话中的标记数量。当您需要确定标记数量而不必对照限制时，可使用此方法。 可选的 encodeOptions 参数允许您指定允许或禁止的特殊标记集合。

示例：

import { countTokens } from 'gpt-tokenizer'

const text = 'Hello, world!'
const tokenCount = countTokens(text)

countChatCompletionTokens(request: ChatCompletionRequest): number

计算一个调用函数的聊天完成请求将消耗的 token 数量，包括消息开销、可选的函数定义以及固定的函数调用。此辅助函数仅适用于支持 function_calling 功能的模型。

示例：

import {
  countChatCompletionTokens,
  type ChatCompletionRequest,
} from 'gpt-tokenizer/model/gpt-4o'

const request: ChatCompletionRequest = {
  messages: [
    { role: 'system', content: '你是一位乐于助人的助手。' },
    { role: 'user', content: '查询旧金山的天气。' },
  ],
  functions: [
    {
      name: 'get_weather',
      description: '查询某个城市的天气。',
      parameters: {
        type: 'object',
        required: ['city'],
        properties: {
          city: { type: 'string' },
          unit: { type: 'string', enum: ['摄氏度', '华氏度'] },
        },
      },
    },
  ],
}

const promptTokenEstimate = countChatCompletionTokens(request)

你也可以通过模块的默认导出来访问该辅助函数：

import gpt4o from 'gpt-tokenizer/model/gpt-4o'

// 复用上面定义的 `request`
const tokenCount = gpt4o.countChatCompletionTokens?.(request)

encodeChat(chat: ChatMessage[], model?: ModelName, encodeOptions?: EncodeOptions): number[]

将给定的聊天对话编码为一串 token 序列。可选的 encodeOptions 参数允许你配置特殊 token 的处理方式。

如果你没有直接导入模型版本，或者在初始化时未提供 model 参数，则必须在此处提供，以便正确地为特定模型对聊天进行分词。当你需要将聊天转换为 GPT 模型可以处理的 token 格式时，请使用此方法。

示例：

import { encodeChat } from 'gpt-tokenizer'

const chat = [
  { role: 'system', content: '你是一位乐于助人的助手。' },
  { role: 'assistant', content: 'gpt-tokenizer 真棒。' },
]
const tokens = encodeChat(chat)

请注意，即使你编码的是空聊天，它仍然会包含最少数量的特殊 token。

encodeGenerator(text: string): Generator<number[], void, undefined>

使用生成器对给定文本进行编码，每次生成一部分 token。 当你希望分块编码文本时，可以使用此方法，这在处理大型文本或流式数据时非常有用。

示例：

import { encodeGenerator } from 'gpt-tokenizer'

const text = '你好，世界！'
const tokens = []
for (const tokenChunk of encodeGenerator(text)) {
  tokens.push(...tokenChunk)
}

encodeChatGenerator(chat: Iterator<ChatMessage>, model?: ModelName): Generator<number[], void, undefined>

与 encodeChat 相同，但输出为生成器，并且可以接受任何迭代器作为输入的聊天内容。

decodeGenerator(tokens: Iterable<number>): Generator<string, void, undefined>

使用生成器解码 token 序列，每次生成一部分解码后的文本。 当你希望分块解码 token 时，可以使用此方法，这在处理大型输出或流式数据时很有用。

示例：

import { decodeGenerator } from 'gpt-tokenizer'

const tokens = [18435, 198, 23132, 328]
let decodedText = ''
for (const textChunk of decodeGenerator(tokens)) {
  decodedText += textChunk
}

decodeAsyncGenerator(tokens: AsyncIterable<number>): AsyncGenerator<string, void, undefined>

异步使用生成器解码 token 序列，每次生成一部分解码后的文本。当你希望以异步方式分块解码 token 时，可以使用此方法，这在异步上下文中处理大型输出或流式数据时非常有用。

示例：

import { decodeAsyncGenerator } from 'gpt-tokenizer'

async function processTokens(asyncTokensIterator) {
  let decodedText = ''
  for await (const textChunk of decodeAsyncGenerator(asyncTokensIterator)) {
    decodedText += textChunk
  }
}

estimateCost(tokenCount: number, modelSpec?: ModelSpec): PriceData

根据模型的定价信息，估算处理给定数量 token 的成本。此函数会计算不同 API 使用类型（主 API、批量 API）的成本，并在有缓存 token 的情况下考虑其成本。

该函数返回一个 PriceData 对象，结构如下：

• main: 主 API 定价，包含 input、output、cached_input 和 cached_output 成本
• batch: 战略 API 定价，同样包含上述成本类别

所有成本均基于提供的 token 数量以美元计算。

示例：

import { estimateCost } from 'gpt-tokenizer/model/gpt-4o'

const tokenCount = 1000
const costEstimate = estimateCost(tokenCount)

console.log('主 API 输入成本：', costEstimate.main?.input)
console.log('主 API 输出成本：', costEstimate.main?.output)
console.log('批量 API 输入成本：', costEstimate.batch?.input)

注意：模型规格必须通过特定于模型的导入获得，或者作为第二个参数传递。并非所有模型都提供成本信息。

特殊 token

GPT 模型使用了一些特殊的 token。 需要注意的是，不是所有模型都支持所有的特殊 token。

默认情况下，所有特殊 token 均被禁止。

encode、encodeGenerator、encodeChat、encodeChatGenerator、countTokens 和 isWithinTokenLimit 函数都接受一个 EncodeOptions 参数，用于自定义特殊 token 的处理方式：

自定义允许集

gpt-tokenizer 允许你在编码文本时指定自定义的特殊 token 允许集。为此，你可以将包含允许特殊 token 的 Set 作为参数传递给 encode 函数：

import {
  EndOfPrompt,
  EndOfText,
  FimMiddle,
  FimPrefix,
  FimSuffix,
  ImStart,
  ImEnd,
  ImSep,
  encode,
} from 'gpt-tokenizer'

const inputText = `一些文本 ${EndOfPrompt}`
const allowedSpecialTokens = new Set([EndOfPrompt])
const encoded = encode(inputText, { allowedSpecialTokens })
const expectedEncoded = [8538, 2991, 220, 100276]

expect(encoded).toBe(expectedEncoded)

你还可以使用一种特殊的简写方式来禁止或允许所有特殊 token，只需传递字符串 'all'，例如 { allowedSpecial: 'all' }。

自定义禁止集

同样，你也可以在编码文本时指定自定义的特殊 token 禁止集。将包含禁止特殊 token 的 Set 作为参数传递给 encode 函数：

import { encode, EndOfText } from 'gpt-tokenizer'

const inputText = `一些文本 ${EndOfText}`
const disallowedSpecial = new Set([EndOfText])
// 将抛出错误：
const encoded = encode(inputText, { disallowedSpecial })

在这个例子中，由于输入文本包含被禁止的特殊 token，因此会抛出错误。

如果同时提供了 allowedSpecialTokens 和 disallowedSpecial，则以 disallowedSpecial 为准。

性能优化

LRU 合并缓存

分词器使用 LRU（最近最少使用）缓存来提升相似字符串的编码性能。默认情况下，它会存储最多 10 万个合并后的标记对。你可以根据具体用例调整此值以达到最佳效果：

• 增大缓存大小会使相似字符串的编码速度更快，但会占用更多内存。
• 将其设置为 0 会完全禁用缓存。
• 对于处理大量唯一字符串的应用程序，较小的缓存可能更为高效。

你可以使用 setMergeCacheSize 函数来修改缓存大小：

import { setMergeCacheSize } from 'gpt-tokenizer'

// 设置为 5000 条目
setMergeCacheSize(5000)

// 完全禁用缓存
setMergeCacheSize(0)

缓存会在多次编码调用之间保持持久化。若需显式清空缓存（例如释放内存），可以使用 clearMergeCache 函数：

import { clearMergeCache } from 'gpt-tokenizer'

clearMergeCache()

测试与验证

gpt-tokenizer 在 TestPlans.txt 文件中包含一组测试用例，用于确保其与 OpenAI 的 Python tiktoken 库兼容。这些测试用例验证了 gpt-tokenizer 的功能和行为，为开发者提供了一个可靠的参考。

运行单元测试并验证这些测试用例，有助于保持该库与原始 Python 实现的一致性。

模型信息

gpt-tokenizer 通过 gpt-tokenizer/models 中的 models 导出，提供了关于所有 OpenAI 模型的全面数据。这包括上下文窗口、费用、训练数据截止日期以及弃用状态等详细信息。

这些数据会定期维护，以匹配 OpenAI 的官方文档。欢迎贡献以保持数据的最新状态；如果你发现任何差异或有更新内容，请随时提交 Pull Request。

基准测试

自 2.4.0 版本以来，gpt-tokenizer 已成为 NPM 上最快的分词器实现，甚至比现有的 WASM/node 绑定实现还要快。它具有最快的编码和解码速度，同时内存占用极小，并且初始化速度也优于其他所有实现。

此外，由于采用紧凑的存储格式，其编码结果的文件尺寸也是最小的。

许可证

MIT

贡献

我们欢迎各种形式的贡献！请提交 Pull Request 或 Issue 来讨论你的问题报告，或者使用 Discussions 功能提出想法或其他疑问。

致谢

感谢 @dmitry-brazhenko 的 SharpToken，其代码为本次移植提供了参考。

希望你在项目中能充分利用 gpt-tokenizer！

gpt-tokenizer 快速上手指南

gpt-tokenizer 是一个高性能的 JavaScript/TypeScript 库，支持所有 OpenAI 模型（包括 GPT-4o, o1, GPT-4.1 及旧版模型）的 Token 编码与解码。它是目前 JS 环境中速度最快、体积最小且无全局缓存泄漏风险的 GPT Tokenizer。

环境准备

• 运行环境：Node.js (推荐 v14+) 或现代浏览器。
• 语言支持：原生支持 TypeScript，无需额外配置类型定义。
• 前置依赖：无第三方运行时依赖。

安装步骤

方式一：使用 NPM 安装（推荐）

npm install gpt-tokenizer

国内加速建议：如果下载缓慢，可使用淘宝镜像源安装：

npm install gpt-tokenizer --registry=https://registry.npmmirror.com

方式二：浏览器直接使用 (UMD)

在 HTML 中直接引入脚本文件，库将暴露为全局变量 GPTTokenizer_${encoding}：

<!-- 以现代模型默认编码 o200k_base 为例 -->
<script src="https://unpkg.com/gpt-tokenizer/dist/o200k_base.js"></script>

<script>
  // 全局变量名为 GPTTokenizer_o200k_base
  const { encode, decode } = GPTTokenizer_o200k_base;
  
  const tokens = encode('Hello world');
  console.log(decode(tokens));
</script>

基本使用

1. 基础文本编码与解码

默认导入使用的是 o200k_base 编码，适用于 gpt-4o, o1, gpt-4.1 等最新模型。

import { encode, decode } from 'gpt-tokenizer'

const text = 'Hello, world!'

// 编码：文本 -> Token 数组
const tokens = encode(text)
console.log(tokens) 

// 解码：Token 数组 -> 文本
const decodedText = decode(tokens)
console.log(decodedText) 

2. 针对特定模型使用

如果需要为旧模型（如 gpt-3.5-turbo 或 gpt-4）进行分词，请从对应的模型路径导入：

import { encode, decode } from 'gpt-tokenizer/model/gpt-3.5-turbo'

const text = '你好，世界！'
const tokens = encode(text)

3. 对话消息编码 (Chat Messages)

处理包含 role 和 content 的对话数组时，请使用 encodeChat：

import { encodeChat } from 'gpt-tokenizer'

const chat = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: '解释一下量子力学。' },
] as const

// 将对话结构转换为 Token 数组
const chatTokens = encodeChat(chat)

4. 检查 Token 数量限制

在不完整编码整个文本的情况下，快速判断是否超出 Token 限制：

import { isWithinTokenLimit } from 'gpt-tokenizer'

const text = '这是一段很长的测试文本...'
const limit = 100

// 如果未超限，返回实际 token 数 (真值)；如果超限，返回 false
const result = isWithinTokenLimit(text, limit)

if (result) {
  console.log(`当前长度: ${result}，未超限`)
} else {
  console.log('已超出 Token 限制')
}