enginex-qwen25-compat/README.md

# Qwen2.5 启动兼容引擎

这个[独立镜像仓库](https://dev.modelhub.org.cn/a4913994/enginex-qwen25-compat)沿用 [ModelHub A100 示例仓库](https://dev.modelhub.org.cn/zhengzhongwei/vLLM-Nvidia-A100-opt)
的方式：标签触发 `.gitea/workflows/docker-build-push.yml`，runner 检查元数据、构建并推送镜像，
最后调用 ModelHub 的 `image-verify` 接口注册验证。

支持 A100 参考端、寒武纪 MLU370 x4/x8、沐曦 C500 和 Vastai VA16；
一次显式全量发布构建四个镜像，五个 GPU 共用 `vllm_qwen25_compat` 框架名。
寒武纪 x4/x8 共用一个镜像，但仍分别进行平台验证。基础镜像均来自
平台已有验证任务使用的版本；A100 沿用示例仓库的基础镜像。每个 GPU 的注册
与可用性仍以平台镜像验证结果和 `frameworks` 接口回读为准。

## 修复范围

- 将列表型 `extra_special_tokens` 合并到 `additional_special_tokens`，解决
  Transformers 调用 `.keys()` 时的崩溃。
- 对明确写成 `TokenizersBackend` 且带 `tokenizer.json` 的仓库，改用
  `PreTrainedTokenizerFast`。
- 对 `model_type=qwen2`、`eos_token=<|im_end|>` 且缺少聊天模板的模型，补充
  简单的 Qwen ChatML 模板，避免 `/v1/chat/completions` 返回 400；已有独立
  `chat_template.jinja` 或 `chat_template.json` 的模型不补写。

启动时在 `/tmp` 建立新视图，只重写 `tokenizer_config.json`。若基础镜像使用
`--tokenizer` 指向单独的临时目录（Vastai 的现有启动脚本如此），则修复实际加载的
tokenizer 目录并保留模型仓库的独立聊天模板，权重路径仍指向原模型；否则修复模型
视图。源模型不变。没有命中问题时直接调用原始 `vllm`。修复记录写在新视图的
`.modelhub-compat-report.json`，同时输出到容器日志。

这不能修复缺失权重、尺寸不匹配、Ascend 上持续出现的 0 分输出或平台评测超时。
尤其是分数为 0 的参考端与目标端必须分别排查；只换一个端的镜像不能保证过审。

## 本地验证

```bash
python -m unittest discover -s tests -v
python -m py_compile engine_compat.py
```

有对应镜像访问权限的 Docker 主机上再运行：

```bash
docker build --build-arg BASE_IMAGE=harbor.4pd.io/dooke/vllm/vllm/vllm-openai:v0.11.0 \
  -t qwen25-compat:a100 .
docker build --build-arg BASE_IMAGE=harbor.4pd.io/hardcore-tech/cambricon-mlu370-pytorch:v25.01-20260228 \
  -t qwen25-compat:mlu370 .
docker build --build-arg BASE_IMAGE=harbor.4pd.io/modelhubxc/enginex-metax/vllm:0.9.1 \
  --build-arg PYTHON_BIN=/opt/conda/bin/python3 \
  --build-arg VLLM_BIN=/opt/conda/bin/vllm \
  -t qwen25-compat:metax .
docker build --build-arg BASE_IMAGE=harbor.4pd.io/modelhubxc/sunruoxi/enginex-vastai-vllm-vacc-fix-tokenizer:VVI-26.02 \
  -t qwen25-compat:vastai .
```

## 用 runner 发布

1. 源码在公开仓库 `a4913994/enginex-qwen25-compat` 的 `main`。推送源码不会构建镜像；
   只有带目标后缀的版本标签才触发 runner。历史 `v0.1.0` 和 `v0.2.1` 的镜像验证
   结果仍须单独回读。
2. runner 使用 `DOCKER_REGISTRY`、`DOCKER_USERNAME`、`DOCKER_PASSWORD`、
   `FIXED_TOKEN`；不要把凭证写进仓库。
3. 选择本次确实需要更新的镜像目标，推送 `vX.Y.Z-nvidia-a100`、
   `vX.Y.Z-cambricon-mlu370`、`vX.Y.Z-metax-c500` 或 `vX.Y.Z-vastai-va16`。
   例如 `v0.3.0-metax-c500` 只构建一份沐曦镜像并验证沐曦 C500；寒武纪标签
   构建一份镜像并分别验证 x4/x8。只有明确使用 `vX.Y.Z-all` 才构建四份镜像、
   发起五项验证。普通 `vX.Y.Z` 标签不触发工作流，也不会隐式全量发布。
4. 工作流先跑单元测试和目标 GPU 元数据校验，再构建、推送选定镜像并检查平台
   `image-verify` 接口业务码。通过本目录的 `python release_plan.py v0.3.0-metax-c500`
   可以在打标签前预览将构建与验证的目标。
5. 回读平台镜像验证记录，并检查新框架出现在目标 GPU 的 `frameworks` 接口中，
   再用少量已知缺陷模型做对照验证。`pending` 不代表镜像已经可用。

只有平台确认新框架可选且 A100 参考端实际使用新镜像后，才应让 `xc-agent` 把
列表型 `extra_special_tokens` 的模型路由到此框架。当前智能体继续预检并跳过它们。