天垓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 离线自测
S
Description
No description provided
Readme
79 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 95.5%
Shell 3.8%
Dockerfile 0.7%