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 首发，三个理由：

1. 失败最集中（10 例，全平台第一）；
2. 该卡社区通过率约 51%（15 张卡里最低），修好收益最大；
3. 它的原生 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_tokens list→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. 三条设计红线

1. 绝不写模型目录——平台挂载的 /model 可能只读。所有修补只通过 「临时覆盖目录 + 命令行参数」实现；软链优先，软链不可用时只拷贝 tokenizer 白名单文件， 权重文件（.safetensors/.bin/.gguf/.pt/...）永远不碰（自测专门盯这条）。
2. 修补失败绝不阻断启动——entrypoint.sh 里 preflight 非 0 退出也只打日志然后按原命令跑； preflight 内部每步都有 try/except。最坏情况＝没修上，不会比不装本引擎更差。
3. 干净模型零改动——模型自带 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. 已知边界（不藏着）

• 没在真卡上跑过。本机没有天垓100，也拉不到该基础镜像，Dockerfile 未经真机验证。 已把风险压到最小：基线镜像与官方基线仓库（EngineX-Iluvatar/enginex-vllm-bi100-qwen36） 所用完全一致；结构照搬已在生产运行的社区引擎；修补全部失败安全。 真实反馈需要平台侧的引擎审核流程给出。
• R4 别名表只收已证实的 4 条（Qwen3_5 系列 + Gemma3 早期类名）。 不靠猜扩表——猜错会把本来能跑的模型改坏。
• R7 shim 是兜底不是优化：保证「能出结果」，不追求吞吐。
• 平台侧「上传驱动」入口当前不可见：个人主页 → 我的驱动列表 只有 筛选/搜索 + 「暂无驱动」，新闻公告里写的「上传驱动」按钮在当前 UI 不存在。 本引擎的注册需要走平台/社区的引擎收录流程（dev.modelhub.org.cn 建仓 + 平台同步）， 这一点已在 cdp/PROGRESS.md 记录。