# vllm-metax-fix-tokenizer

基于 `harbor.4pd.io/modelhubxc/enginex-metax/vllm:0.9.1` 的 tokenizer 自动修复镜像，面向 MetaX C500 GPU。

## 问题背景

部分模型的 `tokenizer_config.json` 存在以下问题，导致 vLLM 0.9.1 服务启动失败：

| 错误 | 原因 |
|---|---|
| `ValueError: Tokenizer class TokenizersBackend does not exist or is not currently imported.` | `tokenizer_class` 不是 transformers 合法类名，环境中缺少 `tokenizers` 包 |
| `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-metax/vllm:0.9.1

# 替换为
<this-image>
```

示例：
```bash
docker run -dit --name metax_sut_submit_task_<task_id> \
  -p 45169:8000 \
  --device=/dev/mxcd \
  --group-add video \
  --device=/dev/dri/card3 \
  --device=/dev/dri/renderD131 \
  -v /mnt/juicefs/leaderboard/modelHubXC/<model_path>:/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
```

## 构建

```bash
docker build -t vllm-metax-fix-tokenizer:latest .
```

CI 通过推送 `v*` tag 自动触发构建并推送镜像。