# 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 的构造方式与社区上线版一致：

```python
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）

```bash
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`：

```bash
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` 记录。