ttok 1.0 发布：token 计数 CLI 升级默认 tokenizer 踩坑实录 · 干货攻略
- 链接:https://simonwillison.net/2026/Oct/9/ttok
- 分类:x-tips
- 来源:X @simonw
- 作者:Jay
- 更新:2026-10-12
- 仓库:simonw/ttok
这是什么
ttok 是 Simon Willison 开源的一款命令行工具，基于 OpenAI 的 tiktoken 库，专职做两件事：计数文本的 token 数量和将文本截断到指定 token 数上限。
2026 年 10 月 9 日发布的 1.0 版本做了一件大事：将默认 tokenizer 从 GPT-4/GPT-3.5 时代的 cl100k_base 切换为 GPT-5/GPT-6 时代的 o200k_base。这次切换导致同一个文本在 1.0 前后的 token 计数结果可能完全不同，直接影响了所有依赖 ttok 做 token 预算控制的 AI 应用。
为什么值得关注
谁分享的，解决什么问题
@simonw（Simon Willison）是 AI 工具链领域的知名开发者，也是 Datasette 和 llm 系列工具的作者。他在 2023 年就推出了 ttok，核心动机是：LLM 按 token 计费，但开发者经常低估或高估实际消耗的 token 数。
典型坑场景：
- 调用 API 前用
ttok -t 2000截断提示词，防止超出 context 上限 - 给 AI 应用做成本估算，用 token 计数乘以单价
- 构建 RAG pipeline 时，用 token 数判断一块文本能否塞进 context window
这些问题在 1.0 之前用 cl100k_base tokenizer 一切都好；升级后，同样的命令、同样的文本，可能算出截然不同的 token 数——导致截断结果偏差、计费数字失真。
硬核点：两个 tokenizer 计数差异是真实的生产风险
Simon 在博客中记录了触发他发布 1.0 的具体场景：
"我发布了 ttok 0.4，运行
uv tool upgrade ttok，把一个文件 pipe 进新版本……然后意识到它默认用了 GPT-4 tokenizer，但显然应该默认切换到 GPT-5/GPT-6 tokenizer！"
切换默认 tokenizer 被他当作发布 1.0 的合理借口，但背后揭示了一个真实问题：用旧 tokenizer 做计费控制的应用，升级 ttok 后可能悄悄出现 token 计数漂移。
核验过程
官方来源
GitHub README（simonw/ttok） 确认了以下关键事实：
- 默认 tokenizer：GPT-5（即
o200k_base），这是 1.0 版本的变更 - 前一个默认 tokenizer：GPT-4/GPT-3.5（
cl100k_base），可通过--model gpt-3.5-turbo回退 - 底层库：OpenAI tiktoken
- Python 版本要求：3.10+
- 支持的 tokenizers 列表（通过
ttok --list-models可查看本地 tiktoken 支持的全部模型） - 安装方式：
pip install ttok、uv tool install ttok、brew install simonw/llm/ttok、uvx ttok
GitHub Releases 页面确认 1.0 发布于 2026 年 10 月 9 日，变更内容：
- 默认 tokenizer 切换为
o200k_base（GPT-5/GPT-6 族） - 新增
ttok --list-models命令 - Click 版本警告修复（
--tokens参数重复警告） --allow-special扩展到计数/截断模式- 打包从 setup.py 迁移到 pyproject.toml
Simon Willison 博客（simonwillison.net） 补充了 GPT-6 tokenizer 验证细节：OpenAI 尚未官方确认 GPT-6 使用与 GPT-5 相同的 tokenizer，但独立开发者 William Liu 的实验表明，GPT-5.5、GPT-5.6 Sol/Terra/Luna、GPT-6 Astra/Sol/Luna 全部报告 44,794 tokens，且在 31 个测试 fixture 上彼此完全一致，可以高度确信 GPT-6 使用同款 o200k_base encoding。
交叉验证
- tiktoken Rust 文档（docs.rs/tiktoken）确认
o200k_base的词汇表大小（100,256 regular + 5 special tokens）与cl100k_base相同，但底层编码不同——这解释了同一文本计数差异的来源。 - Hugging Face 论坛讨论佐证了 tiktoken 的广泛使用和生态地位。
⚠️ 未核验处
- 原帖提及"更新导致 token 计数差异显著"，但未找到具体的差异幅度数字（如"同一段代码旧版 1200 tokens，新版 1150 tokens"这类实测对比）。差异大小取决于具体文本语言（中文 token 效率显著高于英文），无法给出通用数字——差异是否"显著"需结合自身业务文本判断。
- William Liu 的 tokenizer 一致性实验尚未找到独立复现，GPT-6 tokenizer 官方确认状态仍为"未官宣"（原帖已注明）。
上手步骤
安装
# 方式一：pip
pip install ttok
# 方式二：uv（推荐）
uv tool install ttok
# 方式三：Homebrew（macOS/Linux）
brew install simonw/llm/ttok
# 方式四：不安装，直接跑
uvx ttok --help
核心用法
# 1. 计数（默认用 GPT-5 tokenizer，即 o200k_base）
ttok Hello world
# → 2
# 2. 从文件计数
ttok -i input.txt
# 3. 从 stdin 计数
cat input.txt | ttok
# 4. 截断到 N tokens（用于防止超出 context 上限）
cat input.txt | ttok -t 2000
# 5. 查看 token ID
ttok "Hello world" --encode
# → 13225 2375
# 6. 查看 token 详情
ttok "Hello world" --encode --tokens
# → [b'Hello', b' world']
# 7. 列出本地 tiktoken 支持的所有模型
ttok --list-models
# 8. 临时切换 tokenizer（回退到 GPT-4 旧行为）
cat input.txt | ttok -m gpt-3.5-turbo
版本升级后的行为对比
| 场景 | ttok < 1.0 | ttok ≥ 1.0 |
|---|---|---|
| 默认 tokenizer | cl100k_base（GPT-4） |
o200k_base（GPT-5/6） |
ttok "hello" |
2 tokens | 2 tokens（数值可能相同） |
| 中文文本计数 | 偏低（相对新 tokenizer） | 更准确 |
| 长代码片段 | 与 GPT-4 API 计费一致 | 与 GPT-5 API 计费一致 |
坑与适用边界
⚠️ 升级 ttok 后 token 计数"漂移"
这是本工具最核心的坑。 如果你用 ttok < 1.0 做的截断/计费逻辑，升级到 1.0 后： - 截断结果可能变得更长或更短（取决于文本语言组合） - 计费估算数字会与之前不同
建议：重要场景先用 ttok --list-models 确认本地 tiktoken 支持的 tokenizer，再用 -m 指定与实际 API 调用一致的模型，不要盲目依赖默认行为。
回退到旧 tokenizer
# 强制使用 GPT-4 tokenizer（cl100k_base）
export TTOK_MODEL=gpt-3.5-turbo
# 或者每次手动指定
cat input.txt | ttok -m gpt-3.5-turbo
不是所有 token 计数都准确
ttok 使用 tiktoken，与 OpenAI 官方 API 的 token 计数高度接近但不一定完全一致（API 内部可能还有额外处理）。对计费精度要求极高的场景，建议直接用 API 返回的 usage 字段做最终核算，ttok 作为事前估算工具更合适。
Python 3.10+ 要求
1.0 版本要求 Python 3.10 以上。如果你的环境是 Python 3.9 或更老版本，升级 ttok 后会报错，需先升级 Python。
不支持非 OpenAI 模型
ttok 底层是 tiktoken，只支持 OpenAI 系的 tokenizer（GPT 系列、o 系列、embeddings 系列）。如果你用 Claude、Llama、Gemini 等，需要找对应的 tokenizer 工具。
一句话结论
ttok 1.0 将默认 tokenizer 升级到 GPT-5/GPT-6 族（o200k_base），解决了历史遗留的默认值问题，但同时意味着依赖旧版默认行为做 token 预算控制的应用需要重新核验——用 -m gpt-3.5-turbo 可随时回退到旧 tokenizer。