enginex-bi100-compat
天数智芯 天垓100（Iluvatar_bi-100） · 文本生成 · vLLM 兼容增强引擎。
一句话：不改模型、不改卡，只把「引擎镜像层」的结构性不兼容在容器启动前修掉。 这类失败的特征是——换任何模型、换任何卡都会遇到，所以修在引擎层比修在提交层更普适。
1. 动机：失败不是均匀分布的
我在信创模盒累计 37 个验证失败。把 74 份失败日志
（log-extract/<taskId>/pod_runtime_log.txt / error_report_raw.json）聚合后发现，
失败高度集中在几类「模型没坏、卡也没坏、纯粹是引擎/配置层不匹配」的问题上。
按卡分布（我有日志的 42 例）：
| 卡 | 失败数 | 主要缺陷 |
|---|---|---|
| Iluvatar_bi-100 | 10 | R2×4、R3×2、R7×1、R4×1 |
| hygon_k100-ai | 5 | R4×2 |
| Iluvatar_bi-150 | 4 | 其他×3 |
| Iluvatar_mrv-100 | 4 | R1×2（GGUF 需 llamacpp，属提交侧）、R2×2 |
| Cambricon_mlu-370-x8 | 3 | R2×3、R4×1 |
选 bi-100 首发，三个理由：
- 失败最集中（10 例，全平台第一）；
- 该卡社区通过率约 51%（15 张卡里最低），修好收益最大；
- 它的原生 build-config 最简单（
vllm serve /model --port 80 -tp 1），改动面小、风险低。
2. 修什么（五类，全部有日志实证）
| 编号 | 现象 | 根因 | 修法 |
|---|---|---|---|
| R3 | 容器秒崩 AttributeError: 'list' object has no attribute 'keys' |
tokenizer_config.json 里 extra_special_tokens 写成 list，而 transformers 的 SpecialTokensMixin 会执行 ... + list(special_tokens.keys()) |
生成 tokenizer 覆盖目录，把该字段规范成 dict，用 --tokenizer 指过去 |
| R3b | tokenizer 加载异常 | tokenizer_class 是 TokenizersBackend / TiktokenTokenizer 这类镜像不认的类 |
按 fast/sentencepiece/bpe 归一化成正常类，并清掉 backend |
| R2 | /v1/chat/completions 返回 400 或输出为空；启动参数里 chat_template=None |
模型自身没带 chat_template | 注入最小可用 Jinja 模板，用 --chat-template 指过去 |
| R4 | KeyError: 'xxx' / MODEL_NOT_SUPPORTED，配置加载阶段就挂 |
config.json 的 architectures 声明了引擎镜像没注册的类 |
用 --hf-overrides {"architectures":[...]} 把已证实的未注册类名映射到已注册类名 |
| R7 | ModuleNotFoundError: No module named 'ixformer.contrib.vllm.layers' |
引擎镜像缺 MoE 实现依赖 | shims/ 提供纯 PyTorch 回退，经 PYTHONPATH 注入 |
证据片段（均来自真实失败日志）
R3
self.SPECIAL_TOKENS_ATTRIBUTES = self.SPECIAL_TOKENS_ATTRIBUTES + list(special_tokens.keys())
AttributeError: 'list' object has no attribute 'keys'
R4
File ".../transformers/models/auto/configuration_auto.py", line N, in __getitem__
raise KeyError(key)
KeyError: 'olmo...'
R7
File ".../vllm/model_executor/models/mixtral.py", line N, in forward
from ixformer.contrib.vllm.layers import mixtral_decoder_layer_forward
ModuleNotFoundError: No module named 'ixformer.contrib.vllm.layers'
R2
startup args: ..., chat_template=None, ...
后续 MCQ 评测全部 HTTP Error 400 / 输出为空
3. 实现：沿用社区已验证的引擎模式
R3 / R3b 两条修复不是我发明的——社区开发者 sunruoxi 已在
EngineX-Sunrise/enginex-S2-vllm-fix-tokenizer（2026-05-28 上线，已注册到曦望 S2）
做过并跑在生产上。本引擎：
- 完全沿用它的结构：
Dockerfile+entrypoint.sh+ 修补脚本 +detect_tokenizer.py+ README，entrypoint.sh也是detect → fix → exec vllm serve "$MODEL_DIR" $EXTRA "$@"这一套； - 合并它那两条修复（
extra_special_tokenslist→dict 用同形的token→token，tokenizer_class归一化用同一份坏类清单），保证两套引擎口径一致、可交叉验证； - 在其上补了 R2 / R4 / R7 三条，把「只修 tokenizer」升级成「修 tokenizer + 模板 + 架构 + 缺模块」。
extra_special_tokens dict 的构造方式与社区上线版一致：
cfg["extra_special_tokens"] = {token: token for token in orig_list}
4. 三条设计红线
- 绝不写模型目录——平台挂载的
/model可能只读。所有修补只通过 「临时覆盖目录 + 命令行参数」实现；软链优先，软链不可用时只拷贝 tokenizer 白名单文件， 权重文件（.safetensors/.bin/.gguf/.pt/...）永远不碰（自测专门盯这条）。 - 修补失败绝不阻断启动——
entrypoint.sh里 preflight 非 0 退出也只打日志然后按原命令跑； preflight 内部每步都有 try/except。最坏情况＝没修上，不会比不装本引擎更差。 - 干净模型零改动——模型自带 chat_template、架构已注册、无 list 字段时， preflight 不产出任何额外参数（自测用例 5 专门盯这条）。
5. 自测（不需要 GPU / vLLM / Docker）
python3 test_engine.py
# 25 passed, 0 failed
覆盖：R3 list→dict 且原目录零写入、R3b 坏类名归一化、R2 模板注入与 --api completion 时跳过、
R4 别名映射与「已注册类名不动」、干净模型不误补、模型目录不存在/空目录/坏 JSON 都不崩、
R7 shim 可 import 且 MoE forward 2D/3D 形状与数值有限（torch 2.13 cpu 实测）、
entrypoint.sh bash 语法、覆盖目录不含权重文件。
6. 使用方式
Dockerfile 以 ENTRYPOINT ["/opt/entrypoint.sh"] 结尾，平台会把 GPU 数、端口、
--max-model-len 等参数作为 "$@" 传进来，原样透传给 vllm serve：
exec vllm serve "$MODEL_DIR" $EXTRA "$@"
修补结果打进容器日志，事后可归因：
[entrypoint] preflight extra args: --tokenizer /tmp/mhxc_compat_xxx/tokenizer --hf-overrides {...}
[entrypoint] preflight: [preflight] patches=3 R3: ... | R4: ... | R7: ...
7. 如何注册为平台可用框架（本轮挖出的完整链路）
平台侧的「上传驱动」按钮在当前 UI 里不存在，但引擎注册的完整链路藏在社区引擎的 CI 里。
照 EngineX-Sunrise/enginex-S2-vllm-fix-tokenizer 的 .gitea/workflows/ 复刻即可：
.gitea/workflows/docker-build-push.yml 平台官方引擎 CI（原样复制，勿改）
.gitea/workflows/task_info.env 声明三要素：FRAMEWORK / GPU_TYPE / TASK_TYPE
推送一个 v* 标签即触发，CI 会依次：
- 读
task_info.env取FRAMEWORK/GPU_TYPE/TASK_TYPE（FRAMEWORK 必填）； - 调
GET https://modelhub.org.cn/adminApi/image-verify/validate?gpuType=…&taskType=…校验元数据； docker build+docker push到平台 registry；- 调
POST https://modelhub.org.cn//adminApi/image-verify回填{framework, gpuType, imageUrl, taskType, createBy, repoUrl, tag}—— 这一步就是注册。
本仓的取值：FRAMEWORK=vllm_compat、GPU_TYPE=Iluvatar_bi-100、TASK_TYPE=text-generation，
并已推送标签 v1.0.0（commit d78a92b3）。
CI 运行记录：actions/runs/1，9 个步骤（Clone / Set metadata / Load Task Info / Validate Metadata /
Login / Build / Push / Notify / Complete）全部 success，其中 Build 2s、Push 1m1s。
注册生效后，提交适配任务时的「框架」下拉里会出现
vllm_compat（只对 Iluvatar_bi-100 × 文本生成）。
8. 已验证 / 未验证（分清楚，不把做了当成了成了）
已验证
python3 test_engine.py→ 25 passed, 0 failed（不需要 GPU / vLLM / Docker）- CI 9 步全部 success；
image-verify/validate返回code:0, data:true（平台认可元数据）
尚未验证
- 框架还没出现在平台侧：
Iluvatar_bi-100 × text-generation目前仍只有transformers / vllm / vllm-patch-tokenizer(个人开发者 zhengzhongwei) / vllm_fix_tokenizer四个，vllm_compat未出现，「我的驱动列表」也仍显示「暂无驱动」。 → 注册是异步或需平台审核，尚未生效，需要继续观察（不能声称已注册成功）。 - 没在真卡上跑过：本机没有天垓100，也拉不到该基础镜像，Dockerfile 未经真机验证。 风险已压到最小：基线镜像与官方基线一致、结构照搬生产引擎、修补全失败安全。
9. 已知边界
- R4 别名表只收已证实的 4 条（Qwen3_5 系列 + Gemma3 早期类名），不靠猜扩表。
- R7 shim 是兜底不是优化：保证「能出结果」，不追求吞吐。
- 提交任务的「框架」下拉要等平台注册生效后才看得到
vllm_compat。