# 天垓 150 文本生成兼容引擎

本仓是 ModelHub XC 上 Iluvatar bi-150（天垓 150）的文本生成引擎：**Gitea 仓库 + CI 构建镜像**。日常引擎贡献不走 ZIP。

**不代提交。** 本仓不向 modelhub.org.cn 提交适配任务，也不调用平台审核接口。推送、打 Tag、在模盒选用引擎都由人完成，步骤见 [docs/upload-runbook.md](docs/upload-runbook.md)。

积分：待平台核实。成功看审核通过，以及适配任务能否选用该引擎。

## 非目标

- Track B（竞赛）为 **NO-GO**。没有 `contest/`，没有竞赛构建。
- 没有 ZIP 打包，没有上传驱动的 Makefile 目标。
- `FRAMEWORK` 使用 `vllm_bi150_r2r4`，不使用 `vllm_fix_tokenizer`。
- tokenizer 修补（I5）未开启。现有 bi150 引擎已覆盖 tokenizer；本仓补的是 chat_template（R2）和 architecture 白名单（R4）。

## 基线镜像

默认：

`registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v4.1`

这个 tag 来自公开仓反推，置信度为中高，不是官方另行发布的锁定说明。官方入口若给出不同 tag，只改 [Dockerfile](Dockerfile) 里的 `BASE_IMAGE`。

构建覆盖：

```bash
docker build --build-arg BASE_IMAGE=<官方 tag> -t modelhub-engine-bi150-compat:dev .
```

无卡环境只能验证修补逻辑，不能证明吞吐。

## 本地检查

需要本机 `python3`、`bash`、`make`。不需要 GPU，也不需要平台账号。

```bash
make test
make dry-run
```

`make dry-run` 只打印启动计划与模板预览，不启动 vLLM，不访问平台。

## FRAMEWORK

默认值写在 [task_info.env.example](task_info.env.example)。镜像内和 CI 使用同一组值：

- `GPU_TYPE=Iluvatar_bi-150`
- `FRAMEWORK=vllm_bi150_r2r4`
- `TASK_TYPE=text-generation`

### 为什么不用 `vllm_0_17_0_corex_4_4_0`

适配页按 FRAMEWORK 聚合。该名字已被 **i-liangzhuobang** 占用展示，本仓 v0.1.0 用它注册时，引擎下拉里看到的是对方的开发者身份。`vllm_bi150_r2r4` 是本仓独有的名字，用来让适配页正确归属。

若平台给出新的 FRAMEWORK 名，同时改这三处，并让 `make test` 保持通过：

- `task_info.env.example`
- `.gitea/workflows/task_info.env`
- `Dockerfile` 的 `ENV`

不要改回 `vllm_fix_tokenizer`，也不要改回撞名的旧值。

## CI 与 image-verify

`v*` 标签触发 [.gitea/workflows/build.yml](.gitea/workflows/build.yml)：

```text
Clone → Load task info → Validate Image Verify Metadata → Build image → Push → Notify Image Verify
```

Validate 在构建前校验 `gpuType` 与 `taskType`；Notify 只在镜像真的推送成功后注册 `imageUrl`。两步都要 Runner 注入 `FIXED_TOKEN`，仓库里不存任何 Token。

CI 只调用 `adminApi/image-verify` 和它的 `validate`。不代领、也不代提交适配任务。

## 建仓与选用

见 [docs/upload-runbook.md](docs/upload-runbook.md)。事项状态见 [docs/issues.md](docs/issues.md)。证据模板见 [docs/evidence.md](docs/evidence.md)。

参考公开仓的启动包装和架构改写思路，没有整仓复制：

- zhengzhongwei/vLLM-Iluvatar_bi-100-opt
- wanglin/enginex-bi100-compat
- 公开 bi150 tokenizer 引擎只覆盖 tokenizer，本仓补 R2/R4