ttok发布1.0：按token数统计和截断文本

原文要点

Simon Willison发布了他的命令行工具ttok 1.0。ttok的作用是对文本做token计数和按token截断，适合在给大模型喂上下文前控制长度。这次从0.4升到1.0的由头：他uv tool upgrade ttok后发现默认tokenizer还停在GPT-4，于是把默认切换为GPT-5/GPT-6系列。作者说明OpenAI尚未官方确认GPT-6与GPT-5同tokenizer（仓库里有个措辞激烈的issue），但引用了William Liu的一次实验：7个GPT模型（5.5、5.6 Sol/Terra/Luna、6 Astra/Sol/Luna）在同一批31个测试fixture上全部报告44,794个token且逐一相符，即‘GPT-6在该语料上没有引入输入计数变化’。该计数一致性只代表这一实验语料，不应外推为官方承诺。升级方式是uv tool upgrade ttok。

这次做成什么

在本地装好ttok 1.0，用它给准备喂给大模型的中文长文做token计数和截断，建立‘先量长度、再定截断点、最后才调用API’的习惯。

准备什么

• 一台装了Python 3.x的电脑（macOS/Linux/Windows WSL均可）
• 已安装uv（Python包管理器，安装方式见uv官方文档）
• 一段用于练习的长文本，比如一篇3000字以上的中文文章存成txt
• 能访问PyPI的网络环境

具体怎么做

1. 安装或升级ttok

   终端执行：uv tool install ttok（首次）或 uv tool upgrade ttok（从旧版升级）。装完跑 ttok --version 确认是1.0；再跑 ttok --help 查看本版本实际支持的参数，本文示例参数以你本地help输出为准。

2. 给一段文本计token

   把文章存为article.txt，执行：cat article.txt | ttok 或 ttok article.txt（具体是否支持文件参数以--help为准），得到token总数。把它和你目标模型的上下文上限对比，判断是否需要截断。

3. 按token预算截断

   假设你的提示词模板要占2000 token、希望输入不超过6000 token，就截断到4000：cat article.txt | ttok -t 4000 > trimmed.txt（-t为示意写法，确切参数名以ttok --help为准），再对trimmed.txt重新计数确认不超过4000。

4. 对比中英文的token密度

   分别对同一段意思的中文原文和英文译文计数：ttok对两类文本的token数差异通常明显（中文一个字往往不止一个token），用它估算翻译后再喂模型是否划算。

5. 接入你的调用脚本

   在调用任何LLM API前加一道哨兵：先对拼接好的完整提示词跑ttok计数，超过预算就截断或分块，避免被API按超长请求拒掉或产生意外费用。

可直接复制的材料

#!/usr/bin/env bash
# token-guard.sh —— 本站独立编写的调用前长度哨兵（示意）
# 用法：./token-guard.sh prompt.txt 6000
set -e
FILE="$1"; BUDGET="${2:-6000}"
COUNT=$(cat "$FILE" | ttok)
echo "token count: $COUNT / budget: $BUDGET"
if [ "$COUNT" -gt "$BUDGET" ]; then
  cat "$FILE" | ttok -t "$BUDGET" > "${FILE%.txt}.trimmed.txt"
  echo "已截断并写入 ${FILE%.txt}.trimmed.txt，请确认截断点语义完整"
else
  echo "未超预算，可直接调用"
fi

把下面这段重复20次存成article.txt做练习（总长约6000中文字）：

大模型上下文窗口并不是免费的仓库。每一段被塞进去的文本都会按token计费，也会稀释模型的注意力。工程实践里更稳妥的顺序是：先明确这次调用真正需要的信息，再对原材料做抽取和压缩，最后才轮到拼接提示词。把原文整篇丢进去看似省事，实际是在为懒惰付费，还经常换来更差的回答质量。

输入与输出示例

本站虚构演示，数字为示意而非实测；截断发生在token边界，可能切断句子，需要人工检查结尾。

输入

article.txt为材料B片段重复20次（约6000中文字），预算设为4000 token，执行 ./token-guard.sh article.txt 4000

对应输出

终端输出示意：token count: 7320 / budget: 4000
已截断并写入 article.trimmed.txt，请确认截断点语义完整
随后对article.trimmed.txt再跑ttok得到 3996 token，不超预算。注意：7320/3996是按中文token密度估的示意值，实际数字以你本地ttok输出为准

做完检查这些

• ttok --version显示1.0，ttok --help能正常输出参数说明
• 对同一文件重复计数结果完全一致（tokenizer是确定性的）
• 截断后的文件重新计数不超过预算值
• 能说出默认tokenizer从GPT-4切换到了GPT-5/GPT-6，并能解释‘实验显示计数一致’不等于OpenAI官方确认

容易卡住的地方

• ‘7个模型计数一致’只是William Liu在31个fixture上的实验结果，OpenAI未官方确认，别把44,794当成通用常数
• token截断不看语义，截断点可能正好切断句子或JSON，下游使用前要检查结尾
• 中文的token/字比率与英文差别大，按字数估预算会严重失真，必须以ttok实测为准
• 不同模型的tokenizer可能不同，换模型后要重新计数而不是沿用旧预算
• 精确参数写法以本地--help为准，本文未逐字核对ttok 1.0的全部flag