main
天垓100 vLLM 引擎(滑窗 + tokenizer 修复)
在 harbor-contest.4pd.io/luopingyi/bi100/vllm:0.6.3 之上加一层启动期适配,
让两类原本「服务起不来」的模型能正常跑,且不改动模型目录、不改动镜像里的任何库。
| # | 问题 | 现场表现 |
|---|---|---|
| ① | 带 sliding_window 的模型(Mistral / YaRN / Phi-3 等)走 xformers 后端 |
模型能加载,第一次推理抛 AttributeError: 'BlockDiagonalCausalMask' object has no attribute 'make_local_attention' |
| ② | tokenizer_config.json 由新版本 transformers 写出,旧版读不动 |
服务启动阶段直接崩,/v1/models 永远不就绪 |
根因
① vLLM 0.6.3 的 xformers 后端会调用 attn_bias.make_local_attention(...),而镜像里
vendored 的 ixformer.contrib.xformers 那份 BlockDiagonalCausalMask 没有这个方法
(xformers 包里的那份有,但后端创建对象时用的是 ixformer 的)。vLLM 自带
--disable-sliding-window,打开后 ModelConfig.get_sliding_window() 返回 None,
后端就不再走这条分支。代价是滑窗退化成全局注意力:输入不超过窗口长度时输出与原来一致。
② 旧版 transformers 不认识新写法,典型四类:
| 缺陷 | 模型侧写法 | 报错 |
|---|---|---|
tokenizer_class 不是合法类名 |
"tokenizer_class": "TokenizersBackend" |
ValueError: Tokenizer class X does not exist… |
extra_special_tokens 写成 list |
"extra_special_tokens": ["<a>", …] |
AttributeError: 'list' object has no attribute 'keys' |
有 tokenizer.json 却 from_slow: true |
"from_slow": true |
ValueError: Cannot instantiate this tokenizer from a slow version… |
仓库自带 tokenizer 代码(auto_map + tokenization_*.py) |
"auto_map": {"AutoTokenizer": [...]} |
OSError: … does not have a file named tokenization_x.py |
启动流程
/opt/entrypoint.sh <model_dir> [vllm 参数...]
│
├─ 1. fix_tokenizer.py 四类 tokenizer 缺陷,逐候选试加载,通过才用
├─ 2. swa_guard.py 有滑窗且后端缺方法 → 追加 --disable-sliding-window
│ 并把超限的 --max-model-len 压回窗口大小
└─ 3. exec vllm serve <model_dir> [参数...]
行为契约
| 情况 | 行为 |
|---|---|
| 模型没有滑窗、tokenizer 配置正常 | 命令行与原始镜像完全一致 |
有滑窗且镜像后端缺 make_local_attention |
追加 --disable-sliding-window |
有滑窗但 rope_scaling 是 yarn 等(vLLM 0.6.3 明确不支持这个组合) |
不加开关,按原样启动(宁可维持原状,也不让它启动即报 NotImplementedError) |
传了 --max-model-len N 且 N > sliding_window |
压到 sliding_window,日志里给出原因 |
| tokenizer 四类缺陷修好且试加载通过 | 追加 --tokenizer /tmp/fixed_tokenizer |
| 候选配置全部试加载失败 | 不加参数,按原样启动(等价于没有这个补丁,绝不会更差) |
| 修复脚本崩溃 / 输出非法路径 | 兜底按原样启动 |
调用方自己给了 --tokenizer |
尊重调用方,不覆盖 |
所有诊断日志走 stderr,分别以 [fix_tokenizer] / [swa_guard] / [engine] 开头,
便于在容器日志里检索。
用法
调用方式与原镜像一致,只需要换镜像名:
docker run -dit --name <container_name> \
-p 8000:8000 \
-v /lib/modules:/lib/modules -v /dev:/dev \
--device=/dev/iluvatar0:/dev/iluvatar0 \
-v /path/to/model:/model \
--entrypoint /opt/entrypoint.sh <this-image> \
/model --port 8000 --served-model-name llm \
--max-model-len 4096 --gpu-memory-utilization 0.9 \
--enforce-eager --trust-remote-code -tp 1
环境变量(都有缺省值,一般不用动):
| 变量 | 作用 |
|---|---|
VLLM_ENGINE_NO_TOKENIZER_FIX=1 |
关掉 tokenizer 修复 |
VLLM_ENGINE_NO_SWA_GUARD=1 |
关掉滑窗守卫(保留原始 --max-model-len) |
VLLM_ENGINE_DRY_RUN=1 |
只打印最终 argv(JSON),不启动服务 |
FIX_TOKENIZER_OUT_DIR |
修复目录,默认 /tmp/fixed_tokenizer |
FIX_TOKENIZER_VERIFY=0 |
跳过试加载(不建议,调试用) |
构建
docker build -t <image>:<tag> .
自测(不需要 GPU)
python3 selftest_swa_guard.py # 滑窗参数决策(12 个用例)
python3 selftest_launcher.py # 最终 argv 组装(8 个用例)
python3 selftest_fix_tokenizer.py # tokenizer 配置分析(10 个用例)
python3 selftest_fix_tokenizer.py --real # 用真 tokenizer 文件跑修复+试加载(需要 transformers)
--real 会现场构造带各类缺陷的小 tokenizer,验证「修完真的能被 AutoTokenizer 加载」,
包括 auto_map 场景下保留仓库自带代码的路径。
已知边界
- 不修仓库本身缺 tokenizer 数据(没有
tokenizer.json/vocab.json/tokenizer.model) 或缺tokenization_*.py的模型 —— 没有可修的东西,按原样启动; rope_scaling为yarn等类型、同时带滑窗的模型,vLLM 0.6.3 不允许关闭滑窗, 本层不强行处理;- 关闭滑窗后最大长度会被压到窗口大小(例如 Phi-3 mini 的 2047),超长 prompt 会被拒;
- 与 tokenizer / 滑窗无关的失败(架构不支持、权重量化 kernel 缺失、显存不足等) 不在本层范围内。
目录
| 文件 | 作用 |
|---|---|
Dockerfile |
基础镜像 + 安装 |
install_patch.sh |
构建期:装文件、校验 vllm 与脚本可编译(不改镜像里的库) |
entrypoint.sh |
容器入口:准备运行环境后交给 launcher |
vllm_launch.py |
串起 tokenizer → 滑窗 → vllm serve |
fix_tokenizer.py |
四类 tokenizer 缺陷检测 + 候选试加载 |
swa_guard.py |
滑窗开关与 --max-model-len 决策 |
selftest_*.py |
离线自测 |
Languages
Python
95.5%
Shell
3.8%
Dockerfile
0.7%