fix tokenizer

README.md

@@ -0,0 +1,55 @@
+# vllm-musa-fix-tokenizer
+
+基于 `harbor.4pd.io/modelhubxc/enginex-mthreads/vllm-musa-qy2-py310:v0.8.4-release` 的 tokenizer 自动修复镜像，面向 Mthreads S4000 GPU。
+
+## 问题背景
+
+部分模型的 `tokenizer_config.json` 存在以下问题，导致 vLLM 服务启动失败：
+
+| 错误 | 原因 |
+|---|---|
+| `ValueError: Tokenizer class TokenizersBackend does not exist` | `tokenizer_class` 不是 transformers 合法类名 |
+| `AttributeError: 'list' object has no attribute 'keys'` | `extra_special_tokens` 为 list 格式，transformers 要求 dict |
+
+## 修复方式
+
+构建时将镜像内的 `vllm` 二进制（`/usr/local/bin/vllm`）替换为同名 wrapper 脚本，原二进制重命名为 `vllm_real`。
+
+容器启动时 wrapper 自动检测 `tokenizer_config.json`：
+- 存在问题 → 将 tokenizer 文件复制到 `/tmp/fixed_tokenizer/` 并修复，追加 `--tokenizer /tmp/fixed_tokenizer` 参数后调用 `vllm_real`
+- 无问题 → 直接调用 `vllm_real`，行为与原镜像完全一致
+
+原始模型目录不做任何修改。
+
+## 使用方式
+
+**原始 docker run 命令只需替换镜像名，其他参数不变：**
+
+```bash
+# 原镜像
+harbor.4pd.io/modelhubxc/enginex-mthreads/vllm-musa-qy2-py310:v0.8.4-release
+
+# 替换为
+<this-image>
+```
+
+示例：
+```bash
+docker run -dit --name <container_name> \
+  -p 38079:8000 \
+  --privileged=true \
+  --ipc=host \
+  -v /path/to/model:/model \
+  -e MUSA_VISIBLE_DEVICES=0 \
+  --entrypoint vllm <this-image> \
+  serve /model --served-model-name llm \
+  --trust-remote-code --max-model-len 2048 --enforce-eager
+```
+
+## 构建
+
+```bash
+docker build -t vllm-musa-fix-tokenizer:latest .
+```
+
+CI 通过推送 `v*` tag 自动触发构建并推送镜像。