enginex-qwen25-compat/README.md

Qwen2.5 启动兼容引擎

这个独立镜像仓库沿用 ModelHub A100 示例仓库 的方式：标签触发 .gitea/workflows/docker-build-push.yml，runner 检查元数据、构建并推送镜像， 最后调用 ModelHub 的 image-verify 接口注册验证。

当前为 A100 参考端和寒武纪 MLU370 x4/x8 构建两个镜像，三个 GPU 共用 vllm_qwen25_compat 框架名。A100 基础镜像来自示例仓库；寒武纪基础镜像来自 平台现有 MLU370 验证任务使用的镜像。是否允许一个仓库为多个 GPU 注册同一框架， 需要以 runner 的 validate 和镜像验证结果为准。

修复范围

• 将列表型 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。权重、模型代码和 其他文件以符号链接指回只读 /model；源模型不变。没有命中上述问题时直接调用原始 vllm。修复记录写在新视图的 .modelhub-compat-report.json，同时输出到容器日志。

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

本地验证

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

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

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 .

用 runner 发布

1. 源码已推送到公开仓库 a4913994/enginex-qwen25-compat 的 main；目前尚未推送触发构建的 v* 标签。
2. 为该仓库的 runner 配置 DOCKER_REGISTRY、DOCKER_USERNAME、 DOCKER_PASSWORD、FIXED_TOKEN。不要把凭证写进仓库。
3. 推送 v* 标签。工作流依次跑单元测试、验证 GPU/任务元数据、构建与推送镜像、 为 A100 和 MLU370 x4/x8 各发起一次镜像验证。
4. 在“我的驱动列表”确认三个镜像验证通过，并检查新框架出现在对应 GPU 的 frameworks 接口中，再用少量已知缺陷模型做对照验证。

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