6.5 KiB
6.5 KiB
vllm-metax-fix-tokenizer
面向 MetaX C500、vLLM 0.9.1 的 tokenizer 自动修复镜像:在原镜像上加一层 wrapper,启动时按需修复模型自带的 tokenizer 配置。
解决什么问题
部分模型的 tokenizer_config.json 由新版本 transformers生成(或由模型作者手工写过),
卡上 vLLM 0.9.1(transformers 4.x)读不动,容器在 tokenizer 初始化阶段直接崩,
/v1/models 永远起不来 —— 表现为「服务启动失败 / API 未在预期时间内就绪」。
| 缺陷 | 模型侧的写法 | 原镜像的报错 |
|---|---|---|
① tokenizer_class 不是 transformers 合法类名 |
"tokenizer_class": "TokenizersBackend" |
ValueError: Tokenizer class X does not exist or is not currently imported. |
② extra_special_tokens 写成 list |
"extra_special_tokens": ["<a>", …] |
AttributeError: 'list' object has no attribute 'keys' |
③ 有 tokenizer.json 却 from_slow: true |
"from_slow": true, "backend": "tokenizers" |
ValueError: Cannot instantiate this tokenizer from a slow version… |
④ 仓库自带 tokenizer 代码(auto_map) |
"tokenizer_class": "QWenTokenizer" + auto_map + tokenization_qwen.py / qwen.tiktoken |
ValueError: … contains custom code which must be executed,或 OSError: … does not appear to have a file named tokenization_qwen.py |
补充说明:
- ③ 的根因是 transformers 见到
from_slow: true会丢弃现成的tokenizer.json去走 slow 转换, 而目标类PreTrainedTokenizerFast没有slow_tokenizer_class,于是直接把启动打断。 - ④ 不能靠改类名解决:这些 tokenizer 是仓库自带 Python 代码实现的(常配私有词表,如 Qwen1 的
qwen.tiktoken),换成GPT2TokenizerFast这类通用类会改变分词结果(MuPT 对<|endoftext|>的编码就会变),验证数据也就失真了。正确做法是把代码和词表一起拷过去、保留auto_map, 让仓库自己的 tokenizer 跑起来。
修复方式
构建时把镜像里的 vllm 二进制(/opt/conda/bin/vllm)替换成同名 wrapper,原二进制改名为 vllm_real。
容器启动时:
vllm_wrapper.sh只拦serve <model_dir>,其它子命令原样透传;- 调
fix_tokenizer.py:把模型目录里 tokenizer 相关文件(含tokenization_*.py、qwen.tiktoken、spiece.model等仓库自带代码/词表;权重文件不拷)复制到临时目录; - 候选配置按「改动最小 → 逐级兜底」排队,每个候选都真的
AutoTokenizer.from_pretrained()试加载并encode()一次,第一个通过才落地:- 候选 1「keep-class」:只修 ①②③,
tokenizer_class/auto_map原样保留 (保住仓库自带 tokenizer 的分词口径,这是 ④ 唯一正确的修法); - 候选 2「rewrite-class」:按目录里实际存在的数据文件挑
PreTrainedTokenizerFast/LlamaTokenizer/GPT2TokenizerFast,同时去掉auto_map(最后兜底,日志会提示有可能改变分词口径);
- 候选 1「keep-class」:只修 ①②③,
- 拿到可用的修复目录才追加
--tokenizer <dir>;全都不行就什么都不输出,按原样启动 vLLM。
原始模型目录不做任何修改。
行为契约
| 情况 | 行为 |
|---|---|
| 配置没问题 | 不产出目录、不加参数,与原始镜像完全一致 |
| 修好且试加载通过 | stdout 输出一行修复目录,wrapper 追加 --tokenizer <dir> |
| 一个候选都跑不通 | stdout 为空,按原样启动(等价于没有这个补丁,不会更差) |
| 修复脚本崩溃 / 超时 / 输出非法路径 | wrapper 兜底,按原样启动 |
调用方已显式传 --tokenizer |
尊重调用方,不覆盖 |
stdout 只留修复目录一行,诊断信息全部走 stderr([fix_tokenizer] 前缀),便于在容器日志里检索。
验证过的场景
用真实模型的 tokenizer 文件(transformers 4.51.3)跑过:
| 场景 | 结果 |
|---|---|
TokenizersBackend + tokenizer.json + from_slow: true |
清掉 from_slow 改 PreTrainedTokenizerFast,加载成功 |
auto_map + tokenization_mupt.py + vocab/merges |
拷代码与词表、保留类名,MuPTTokenizer 加载成功,编码与仓库自带实现逐 id 一致 |
auto_map + qwen.tiktoken |
拷 tokenization_qwen.py + qwen.tiktoken,QWenTokenizer 加载成功 |
extra_special_tokens list |
list → dict,加载成功 |
| 干净模型 | 不产出修复目录,原样启动 |
修复脚本崩溃 / 脚本不存在 / 已有 --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 |
镜像内固定路径 | 仅测试时覆盖 |
已知不覆盖
- 模型仓库根本没有 tokenizer 数据文件(既无
tokenizer.json,也无vocab/merges/*.model, 也没有可拷的auto_map代码):改类名只会换一条报错,所以脚本选择「不修」,保持原行为。 - 依赖缺失导致的失败(例如仓库自带 tokenizer 需要
tiktoken而镜像没装):试加载会失败 → 不修, 日志里会打出trust=…: ImportError/OSError …,方便定位该往镜像里补什么依赖。
使用方式
原始 docker run 命令只需替换镜像名,其他参数不变:
docker run -dit --name vllm-fix-tokenizer \
-p 8000:8000 \
--device=/dev/mxcd \
--group-add video \
--device=/dev/dri/card0 \
--device=/dev/dri/renderD128 \
-v /path/to/model:/model \
--entrypoint /opt/conda/bin/vllm \
<this-image> \
serve /model --port 8000 --served-model-name llm --max-model-len 2048 --gpu-memory-utilization 0.9 --enforce-eager --trust-remote-code -tp 1
构建
docker build -t vllm-metax-fix-tokenizer:latest .
本仓没有配置 CI,构建与推送都在本地/构建机手动执行:
docker build -t <registry>/<namespace>/vllm-metax-fix-tokenizer:<tag> .
docker push <registry>/<namespace>/vllm-metax-fix-tokenizer:<tag>