K100-vllm/README.md

K100-vLLM Patched 镜像

背景

在海光 K100-AI GPU 和 Nvidia A100 上跑大批量模型 benchmark 时，部分模型因 tokenizer 配置问题导致 vLLM 启动失败。本仓库通过在基础镜像上打 patch，修复已知的兼容性问题，无需逐个修改模型文件。

目录结构

├── K100-vLLM Patched 镜像/        # K100-vLLM补丁镜像
│   ├── Dockerfile                 
│   └── patch.py                   
├── NV A100 Patched 镜像/          # 英伟达A100基础tokenizer补丁镜像
│   ├── Dockerfile                 
│   └── patch.py                   
└── NV A100 Patched 镜像合并/      # 英伟达A100合并tokenizer补丁镜像
    ├── Dockerfile                 
    ├── detect_tokenizer.py        
    ├── entrypoint.sh              
    ├── fix_tokenizer.py           
    └── patch.py                  

镜像信息

海光 K100-AI

项目	值
基础镜像	git.modelhub.org.cn:9443/enginex-hygon/vllm:0.9.2
Patched 镜像	git.modelhub.org.cn:9443/enginex-hygon/vllm:0.9.2-patched

Nvidia A100

项目	值
基础镜像	harbor.4pd.io/dooke/vllm/vllm/vllm-openai:v0.11.0
Patched 镜像	harbor.4pd.io/dooke/vllm/vllm/vllm-openai:v0.11.0-patched

已修复问题

Patch 1：extra_special_tokens 类型兼容

问题： 部分模型的 tokenizer_config.json 中 extra_special_tokens 字段为 list 类型，而 transformers 库要求其为 dict，导致 vLLM 启动时报错崩溃。

修复文件： transformers/tokenization_utils_base.py

修复方式： 在 _set_model_specific_special_tokens 方法入口处，检测到 list 类型时自动转换为 dict。

已验证模型：

• beyoru/Luna-Ethos ✅
• boqiny/Qwen3-8B-FengGe-SFT ✅

Patch 2：Tokenizer 配置自动修复（仅 Nvidia A100）

问题： vLLM 遇到不兼容的 tokenizer 类（如 TokenizersBackend、TiktokenTokenizer）时无法加载模型。

解决方案： 容器启动时自动检测并修复 tokenizer 配置：

检测到的类型	判断依据	替换为
fast	存在 tokenizer.json	PreTrainedTokenizerFast
sentencepiece	存在 tokenizer.model	LlamaTokenizer
bpe	存在 vocab.json + merges.txt	GPT2TokenizerFast
unknown	无法识别	PreTrainedTokenizerFast（默认）

执行流程：

容器启动 → entrypoint.sh → fix_tokenizer.py（修复）→ vllm serve --tokenizer /tmp/fixed_tokenizer

影响范围： 运行时，每次容器启动时执行，不修改原始模型文件。

构建方法

海光 K100-AI

在对应目录执行：

docker build -t git.modelhub.org.cn:9443/enginex-hygon/vllm:0.9.2-patched .

Nvidia A100

在对应目录执行：

docker build -t harbor.4pd.io/dooke/vllm/vllm/vllm-openai:v0.11.0-patched .

文件说明

海光 K100-AI

• Dockerfile — 镜像构建文件
• patch.py — 执行实际文件修改的脚本

Nvidia A100

文件	作用
Dockerfile	镜像构建配置，集成两个修复方案
patch.py	Transformers 库源码修复脚本（构建时执行）
detect_tokenizer.py	检测 tokenizer 类型（运行时调用）
fix_tokenizer.py	修复 tokenizer 配置（运行时执行）
entrypoint.sh	容器入口脚本，协调修复流程并启动 vLLM

注意事项

1. 原始模型文件不受影响：Patch 2 的所有修复操作在 /tmp/fixed_tokenizer 中进行，不修改挂载的模型目录。
2. 必需文件：使用 Patch 2 时，模型目录必须包含 tokenizer_config.json 或相关 tokenizer 文件。
3. 特殊 token 风险：自动修复可能影响特殊 token 的处理逻辑，建议在生产环境前充分测试。

参考资料

• 原始 Tokenizer 修复方案：enginex-s2-sglang-private
• vLLM 官方文档：https://docs.vllm.ai/

维护信息

• 构建日期：2026-04-27
• 维护者：i-peixingyu