vllm-tokenizer-patch

面向天数智芯加速卡(mrv-100)、vLLM 0.8.3 的 tokenizer 自动修复镜像: 在原镜像上加一层 wrapper,容器启动时按需修复模型自带的 tokenizer 配置,不改动模型目录。

解决什么问题

部分模型的 tokenizer_config.json 由新版本 transformers生成(或由模型作者手工写过), 镜像里的 transformers 4.x 读不动,容器在 tokenizer 初始化阶段直接崩,/v1/models 永远起不来 —— 表现为「服务启动失败 / API 未在预期时间内就绪」。

缺陷 模型侧的写法 原镜像的报错
① extra_special_tokens 写成 list "extra_special_tokens": ["<a>", …] AttributeError: 'list' object has no attribute 'keys'
② tokenizer_class 不是 transformers 合法类名 "tokenizer_class": "TokenizersBackend" ValueError: Tokenizer class X does not exist or is not currently imported.
③ 有 tokenizer.json 却 from_slow: true "from_slow": true, "backend": "tokenizers" ValueError: Cannot instantiate this tokenizer from a slow version…
④ 仓库自带 tokenizer 代码(auto_map) "tokenizer_class": "XxxTokenizer" + auto_map + tokenization_xxx.py / 私有词表 ValueError: … contains custom code which must be executed,或 OSError: … does not appear to have a file named tokenization_xxx.py

补充说明:

  • ③ 的根因是 transformers 见到 from_slow: true 会丢弃现成的 tokenizer.json 去走 slow 转换, 而目标类 PreTrainedTokenizerFast 没有 slow_tokenizer_class,于是直接把启动打断。
  • ④ 不能靠改类名解决:这些 tokenizer 是仓库自带 Python 代码实现的(常配私有词表), 换成 GPT2TokenizerFast 这类通用类会改变分词结果,下游验证数据也就失真了。 正确做法是把代码和词表一起拷过去、保留 auto_map,让仓库自己的 tokenizer 跑起来。

修复方式

构建期由 install_patch.sh 完成:把 PATH 上的 vllm 换成 wrapper,原二进制改名成 vllm_real (真实路径现场解析、解释器取原 vllm 脚本的 shebang),Dockerfile 只保留三行。容器启动时:

  1. wrapper 只拦 serve <model_dir>,其它子命令原样透传;
  2. 调 fix_tokenizer.py:把模型目录里 tokenizer 相关文件(含 tokenization_*.py、私有词表 如 qwen.tiktoken、spiece.model 等;权重文件不拷)复制到临时目录;
  3. 候选配置按「改动最小 → 逐级兜底」排队,每个候选都真的 AutoTokenizer.from_pretrained() 试加载并 encode() 一次,第一个通过才落地:
    • 候选 1「keep-class」:只修 ①②③,tokenizer_class / auto_map 原样保留 (保住仓库自带 tokenizer 的分词口径,这是 ④ 唯一正确的修法);
    • 候选 2「rewrite-class」:按目录里实际存在的数据文件挑 PreTrainedTokenizerFast / LlamaTokenizer / GPT2TokenizerFast,同时去掉 auto_map(最后兜底,日志会提示可能改变分词口径);
  4. 拿到可用的修复目录才追加 --tokenizer <dir>;全都不行就什么都不输出,按原样启动 vLLM。

行为契约

情况 行为
配置没问题 不产出目录、不加参数,与原始镜像完全一致
修好且试加载通过 stdout 输出一行修复目录,wrapper 追加 --tokenizer <dir>
一个候选都跑不通 stdout 为空,按原样启动(等价于没有这个补丁,不会更差)
修复脚本崩溃 / 超时 / 输出非法路径 wrapper 兜底,按原样启动
调用方已显式传 --tokenizer 尊重调用方,不覆盖

stdout 只留修复目录一行,诊断信息全部走 stderr([fix_tokenizer] 前缀),便于在容器日志里检索。

验证过的场景

用真实模型的 tokenizer 文件(transformers 4.x)跑过:

场景 结果
extra_special_tokens 为 list list → dict,加载成功
TokenizersBackend + tokenizer.json + from_slow: true 清掉 from_slow 改 PreTrainedTokenizerFast,加载成功
auto_map + tokenization_*.py + vocab/merges 拷代码与词表、保留类名,加载成功且编码与仓库自带实现逐 id 一致
auto_map + 私有词表(如 qwen.tiktoken) 拷代码与私有词表,仓库自带 tokenizer 加载成功
干净模型 不产出修复目录,原样启动
修复脚本崩溃 / 脚本不存在 / 已有 --tokenizer 均按原样启动,不影响服务

离线自测(不需要 transformers / GPU):

python3 selftest_fix_tokenizer.py

可调项(环境变量)

变量 默认 说明
FIX_TOKENIZER_VERIFY 1 试加载开关;0 = 跳过(不推荐,仅离线调试)
FIX_TOKENIZER_OUT_DIR /tmp/fixed_tokenizer 修复目录
FIX_TOKENIZER_MAX_COPY_MB 256 单文件拷贝上限(防止把权重拷进来)
FIX_TOKENIZER_TIMEOUT 180 wrapper 里修复脚本的超时(秒)
FIX_TOKENIZER_PYTHON / FIX_TOKENIZER_SCRIPT / FIX_TOKENIZER_VLLM 构建时烘焙的路径 仅测试时覆盖

使用方式

命令行和原镜像完全一样,只是镜像名换成打过补丁的:

docker run -dit --name vllm-tokenizer-patch \
  -p 8000:80 \
  --privileged \
  -v /path/to/model:/model \
  --entrypoint vllm \
  <this-image> \
  serve /model --port 80 --served-model-name llm --max-model-len 1024 \
  --gpu-memory-utilization 0.9 --enforce-eager --trust-remote-code -tp 1

构建

Dockerfile 已经写好了基础镜像,直接构建即可:

docker build -t vllm-tokenizer-patch:latest .

本仓没有配置 CI,构建与推送都在本地/构建机手动执行:

docker build -t <registry>/<namespace>/vllm-tokenizer-patch:<tag> .
docker push <registry>/<namespace>/vllm-tokenizer-patch:<tag>

已知不覆盖

  • 模型仓库根本没有 tokenizer 数据文件(既无 tokenizer.json,也无 vocab/merges/*.model, 也没有可拷的 auto_map 代码):改类名只会换一条报错,所以脚本选择「不修」,保持原行为。
  • 依赖缺失导致的失败(例如仓库自带 tokenizer 需要额外包而镜像没装):试加载会失败 → 不修, 日志里会打出 trust=…: ImportError/OSError …,方便定位该往镜像里补什么依赖。
S
Description
No description provided
Readme
51 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 82.6%
Shell 15.9%
Dockerfile 1.5%