← 返回首页

Chat Template 吃掉的 token:工具定义与消息信封实测

tokenChat TemplateLLM

我把同一段 40 轮的运维对话,按四个模型的官方 chat template 渲染后再数 token:正文部分 1,842 个 token,实际进上下文的是 3,012 个。多出来的 1,170 个不是对话内容,是模板加的信封和工具清单。

一句话结论:按正文估 token 的预算表,在这四个模型上会低估 3.6% 到 63.5%;其中两个模型的模板根本不认工具,一个 token 都不加,也不报任何错。本文不含任何联盟推广链接,所有数字都是我在本机跑出来的。

我实际测了什么

环境是 CPython 3.13.14、transformers 5.22.1、tokenizers 0.23.3。四份 chat template 取自各自 Hugging Face 仓库的 tokenizer_config.json,2026-11-03 抓取:Llama-3.1 的模板 348 个字符、DeepSeek-V3 2,145 个字符、Mistral-7B-Instruct-v0.3 3,959 个字符、Qwen3-8B 4,168 个字符。

测法是同一条路径,不掺任何猜测:把 messages 列表交给 apply_chat_template,tokenize 打开,数出 id 长度;再拿同一批 messages 的 content 单独编码求和,两者相减就是模板加的量。20 轮问答、40 条消息,每条用户消息 35 个词左右,助手回复 12 个词左右。

信封:每条消息都收一次过路费

先看最小的一层,也就是只有结构、没有内容的开销。把 content 全设为空字符串,逐条加上去:

模型单条空 user 消息每多一条 user每多一轮问答40 条消息信封合计
Llama-3.110 token+5+15205
Qwen35 token+5+14207
DeepSeek-V32 token+1+362
Mistral-v0.38 token无法单加+9141

Llama-3.1 的一条 user 消息渲染出来是 <|begin_of_text|><|start_header_id|>user<|end_header_id|> 加两个换行,再跟正文和 <|eot_id|>,一共 5 个 token 只为了说「下面是用户说的话」。Qwen3 用 <|im_start|>user 加换行,也是 5 个。DeepSeek-V3 最省,<|User|> 只要 1 个 token,因为它的角色标记被训练成了单个词表条目。

Mistral 那栏写「无法单加」,原因后面单独说:这个模板不接受两条连续的 user 消息,逐条加会直接抛异常,只能按「user 加 assistant」成对加。

信封本身不吓人,40 条消息最多 207 个 token。吓人的是它随消息条数线性长:一个 200 条消息的长会话,光信封就是 1,000 个 token 上下,而你在正文里一个数字都看不到。

工具定义:不是按 JSON 的字符数计价

真正的大头在工具。我准备了 10 个真实感的函数 schema,压缩成单行 JSON 之后,工具清单的裸文本是这样的:Llama 的词表下 745 个 token,Qwen3 下 756 个,Mistral 下 888 个。

但模板不会把 JSON 原样贴进去,它会加说明文字:

模型1 个工具10 个工具JSON 裸文本模板自带的说明
Qwen3+175+963756约 207
Mistral-v0.3+113+939888约 51
Llama-3.1+0+0745无
DeepSeek-V3+0+0745无

Qwen3 一个工具要 175 个 token,而它的 JSON 只有 69 个。多出来的 106 个是模板自己写的一段系统消息,原文是 # Tools、You may call one or more functions to assist with the user query.、You are provided with function signatures within XML tags:,然后才是 JSON。十个工具时这段说明只加一次,所以单价从 175 掉到 96 左右。

Mistral 走的是另一套:它把工具清单包成 [AVAILABLE_TOOLS] 塞在最后一条 user 消息前面,一个工具 113 个 token,十个 939 个,边际成本大约 94 个。

这里有个容易被忽略的量级:Qwen3 上 10 个工具(963 token)比整段 40 轮对话的正文(1,842 token)的一半还多。如果你在做一个二十个工具的 Agent,按实测每个约 96 token 外推,光工具清单就接近 1,900 个 token,还没开始聊。这个外推我没有实测,只作量级参考。

两个模板把工具整个吞掉,还不报错

Llama-3.1 的模板只有 348 个字符,全文是循环 messages、拼 <|start_header_id|> 加 role、再拼 content,最后补一个 assistant 头。里面没有出现 tools 这个变量名一次。

结果是:你把 tools 传进去,模板照收,但渲染出来的字符串和不传时逐字节相同。我用字符串相等做了断言,tools_rendered_identical 为 true;40 条消息下带 10 个工具是 1,905 个 token,不带也是 1,905 个。

DeepSeek-V3 更绕。它的模板 2,145 个字符,里面确实有工具相关的分支:message['tool_calls'] 会被渲染成 <|tool▁call▁begin|> 那一串,tool 角色也有对应的输出格式。但它从头到尾没有读过 tools 这个变量。也就是说,这个模板能渲染「模型已经调用过工具」的历史消息,却不能把「你有哪些工具可用」写进 prompt。

这类失败最难查:接口不抛异常,日志里 tools=[...] 看起来传得好好的,模型就是不调用工具,你会先怀疑模型能力、再怀疑提示词,最后才想到模板。

对照办法只有一条,而且很便宜:把同一组 messages 渲染两遍,一遍带 tools 一遍不带,比较两个字符串是否相等。相等就说明工具没进 prompt。

18,780 与 939:我自己的测试踩了模板的相等判定

上面那栏破折号的来源值得单独讲,因为它是这次最贵的一课。

Mistral 的模板里有这么一行判断:{%- if tools is not none and (message == user_messages[-1]) %},意思是「只有当这条消息是最后一条 user 消息时,才注入工具清单」。它用的是字典相等,不是索引比较。

我第一版测试为了省事,40 条消息里每一条用户消息的 content 完全相同、每一条助手回复也完全相同。于是每一对 user 消息都相等,判断对每一条都成立,工具清单被注入了 20 次。

那一版测出来是 20,681 个 token,正文 1,740 个,工具成本 18,780 个,超了 1,088.6%。我第一反应是「Mistral 每轮都重发工具」,差点就这么写进文章。

改法很简单:给每条消息加一个不同的后缀,让字典不相等。同样 40 条消息、同样 10 个工具,工具成本从 18,780 掉到 939,正好是 20 倍差。

教训有两层。第一层是测试自己的:对照组必须真的不同,否则你测的是「模板的行为」还是「你数据重复导致的放大」,分不清。第二层是模板的:用字典相等判断位置,只要客户端重发同一条消息(重试、回填、占位消息),工具清单就会被重复注入,成本按次数翻倍,而且没有任何提示。

一个能用的预算公式

把上面几层加起来,就是实际占用:

实际 token ≈ 正文 token 之和 + 信封单价 × 消息条数 + 工具清单 × 注入次数 + 生成提示

四个模型的验算,全部对得上:

模型正文信封工具实际偏差
Llama-3.11,70020501,905+12.1%
Qwen31,8422079633,012+63.5%
DeepSeek-V31,7206201,782+3.6%
Mistral-v0.31,9421419393,022+55.6%

用法很直接:先用你的分词器把正文数出来,再加上表里的信封单价乘以条数,最后确认工具模板到底认不认 tools。三步里最容易被跳过的是第三步,而它恰好是那种「不认也不会告诉你」的检查。

还有个细节:空 system 消息也要钱。Llama 上塞一条 content 为空的 system,多 5 个 token;Mistral 多 3 个;Qwen3 多 5 个;DeepSeek 是 0,因为它把 system 内容直接拼到开头,空字符串等于没拼。

报错与不报错的陷阱

我实际测试时踩到的四个真报错,原文照抄:

报错一:ValueError: Cannot use chat template functions because tokenizer.chat_template is not set and no template argument was passed! 原因是只加载了 tokenizer.json,没设模板。解法是从 tokenizer_config.json 里读 chat_template 赋给 tokenizer,或者直接给 apply_chat_template 传 template 参数。

报错二:jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'role'。messages 里有一条只有 content 没有 role。模板会直接去取 message['role'],缺键就炸在渲染阶段,与分词无关。

报错三:ValueError: Cannot apply chat template to an empty conversation. Provide at least one message.。消息列表是空的时候,连渲染都进不去。这个报错本身很清楚,但它常出现在「历史被清空后重试请求」的场景里。

报错四:TemplateError: After the optional system message, conversation roles must alternate user/assistant/user/assistant/...。这是 Mistral 的交替校验,两条连续的 user 消息会直接失败。修法是在中间补一条 assistant,或者把两条 user 合并成一条。

三个不报错但更危险的:

一是 role 写成 wizard,模板原样渲染成 <|start_header_id|>wizard<|end_header_id|>,11 个 token,模型看到的是一个它没训练过的角色名。

二是 content 传 None,渲染出来就是字符串 None,同样是 11 个 token,模型会把「None」当成用户说的话。

三是 content 传多模态的列表,文本模板会把整个 Python 结构 repr 进去,渲染结果是 [{'type': 'text', 'text': 'hi'}],24 个 token,比纯文本多花 13 个,而且模型看到的是带引号的字面量。

官方文档怎么说,实测对得上对不上

Hugging Face 的 chat templating 文档把机制写得很清楚:role 和 content 组成的字典「会被转换成 token 序列,通常带有 <|user|>、<|assistant|>、<|end_of_message|> 这类控制 token,让模型看到对话结构」。同一页还提醒,模板本身已经包含所有必要的特殊 token,再额外加通常是不对或重复的。

关于生成提示,文档的原话是「并非所有模型都需要生成提示,有些模型比如 Llama 在 assistant 回复前没有任何特殊 token,这种情况下 add_generation_prompt 不起作用」。我的实测完全对上:Llama 加不加差 0,Mistral 差 0,Qwen3 差 3,DeepSeek 差 1。

工具这块,文档只说「当一个模型支持工具调用时,把函数传给 apply_chat_template 的 tools 参数」。它没有写不支持时会怎样。我实测的答案是:静默丢弃,零 token,零报错。

OpenAI 那边的口径不同。官方 cookbook 的计数函数是每条消息固定加 3 个 token、最后再加 3 个给回复打底,并且自己注明「这个函数算出来的是估计值,不是永久保证」,还专门写了一句「带 functions 参数的请求会在估算之外额外消耗 token」。所以哪怕在 OpenAI 这一侧,按正文数 token 也是低估。

再看看另一套格式:tiktoken 里 o200k_harmony 编码带 1,091 个特殊 token。同一段两轮对话,纯文本 11 个 token,套上 <|start|>user<|message|>…<|end|> 之后是 22 个,正好翻倍。

本文的边界

我只测了 tokenizer 和模板渲染,没有测服务端真实计费,API 侧可能再包一层,也可能按不同的消息格式计。四个模型都只做前缀编码,没有跑生成质量,工具调用能不能成功还要看模型本身。四份模板是 Hugging Face 上开源权重仓库里的版本,DeepSeek 官方 API 的函数调用走的是服务端另一份模板,与我测的这份不是同一个文件。

想接着往下看计数口径,可以先读我前面写的一个汉字被切成几个 token,那篇讲单库两个编码的差异;再读五个分词器数同一段中文差 73%,那篇讲换厂商词表之后的偏差。两篇都在讲「正文怎么数」,这篇补的是「正文之外还有多少」。如果你在做流式输出,LangGraph 的三个流式入口那篇讲 token 怎么一段段吐出来,和这里的信封成本是同一件事的两头。

三句话收尾

先渲染再数,不要数正文。渲染两遍做相等断言,确认工具真的进了 prompt。最后按条数算信封,别按字数算。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页