# gemma4-bi150 — Gemma 4 家族统一部署（Iluvatar BI-V150）

一个镜像同时支持两个 Gemma 4 家族模型，启动时读模型 `config.json` 自动选择运行参数：

| 模型 | 类型 | 权重 | TP | 卡数 | 端口 | served name | eager | 显存 | seqs |
|---|---|---:|---:|---:|---:|---|---:|---:|---:|
| `gemma-4-31B-it` | dense，60 层 | 58.25 GiB | **4** | 4 | **8095** | `gemma-4-31B-it` | 0 | 0.90 | 4 |
| `GEV-26B-Decide` | MoE，30 层 / 128 experts | 48.07 GiB | **2** | 2 | **8094** | `GEV-26B-Decide` | 1 | 0.95 | 2 |

> 本仓库由 `memory/gemma4-31b-deploy/` 和 `memory/gev-26b-decide-deploy/` 合并而来，
> 原目录保留未删。合并依据见文末「为什么可以合并」。

---

## 1. 目录结构

```text
gemma4-bi150-deploy/
├── Dockerfile              # 只放基础镜像 + 补丁 + 脚本，不写 ENV/EXPOSE/ENTRYPOINT
├── entrypoint.sh           # 容器入口：打补丁 → detect → exec vllm
├── detect_model.py         # 从 config.json 判断 dense / MoE，并校验 TP 可行性
├── apply_patch.py          # 幂等应用两个 CoreX vLLM 补丁
├── run.sh                  # 构建 + 启动 + 健康检查
├── verify.sh               # health / models / chat / 可选推理 / 可选图片
├── docker-compose.yml
├── .dockerignore
├── .gitignore
├── .gitea/workflows/
│   ├── docker-build-push.yml
│   └── task_info.env
└── README.md
```

---

## 2. 快速开始

```bash
cd gemma4-bi150-deploy

# Gemma-4-31B（4 卡，默认用 15,14,13,12）
./run.sh /mnt/disk0/models/google/gemma-4-31B-it

# GEV-26B-Decide（2 卡，默认用 14,15）
./run.sh /mnt/disk0/models/autotrust/GEV-26B-Decide

# 验证
./verify.sh --model-dir /mnt/disk0/models/google/gemma-4-31B-it
./verify.sh --model-dir /mnt/disk0/models/autotrust/GEV-26B-Decide --with-image
```

模型类型不需要手写参数，`run.sh` 会调用 `detect_model.py` 读 `config.json` 判断。

### 2.1 不传模型目录

```bash
./run.sh
```

按顺序尝试：

```text
/mnt/disk0/models/google/gemma-4-31B-it
/mnt/disk0/models/autotrust/GEV-26B-Decide
```

### 2.2 Compose

```bash
MODEL_HOST_DIR=/mnt/disk0/models/google/gemma-4-31B-it docker compose up -d --build
```

Compose 里 TP / PORT / SERVED_NAME / MAX_NUM_SEQS / GPU_MEM_UTIL / ENFORCE_EAGER
都默认留空，由容器内 `entrypoint.sh` 检测后填充。

---

## 3. 自动识别逻辑

### 3.1 判断变体

```python
arch = config["architectures"][0]        # 必须以 Gemma4 开头
text = config.get("text_config", config)
experts = num_experts / num_local_experts / n_routed_experts
```

| 条件 | 变体 | 运行参数 |
|---|---|---|
| `experts > 1` | GEV-26B-Decide（MoE） | TP2 / 8094 / eager1 / 0.95 / 2 seqs |
| `experts` 缺失或 `== 1` | Gemma-4-31B（dense） | TP4 / 8095 / eager0 / 0.90 / 4 seqs |
| 无 experts 且目录名含 `gev` | GEV | 同上 |
| 无 experts 且目录名含 `gemma` | Gemma-4-31B | 同上 |
| 其它 / 架构不是 Gemma4 | 直接报错 | 不启动 |

`num_experts=1` 按 dense 处理，因为部分 dense 配置用 1 表示"没有专家"。

### 3.2 顺便校验 TP 可行性（这是合并后的额外收益）

两个变体都有硬性 TP 上限，`detect_model.py` 会拿 `config.json` 反查：

```text
dense:  num_global_key_value_heads % TP == 0
        Gemma-4-31B 的 4 个 global KV head，TP8 会切成 0.5 → 拒绝启动
MoE:    (moe_intermediate_size / TP) % 32 == 0
        CoreX ixfops.moe_w16a16_group_gemm 要求 k % 32 == 0
        GEV 704/2=352 ✅，704/4=176 ❌
```

所以下面这些都会被提前拦住，而不是等 vLLM 跑到一半才崩：

```bash
TP=8 ./run.sh .../gemma-4-31B-it      # num_global_key_value_heads=4 % 8 != 0
TP=4 ./run.sh .../GEV-26B-Decide      # 704/4=176，k % 32 != 0
```

确实需要强跑时用 `GEMMA4_SKIP_TP_CHECK=1` 降级为警告。

### 3.3 检测输出

```text
$ python3 detect_model.py /mnt/disk0/models/autotrust/GEV-26B-Decide
DETECTED_MODEL_KIND=gev-26b-decide
DETECTED_TP=2
DETECTED_PORT=8094
DETECTED_SERVED_NAME=GEV-26B-Decide
DETECTED_GPU_COUNT=2
DETECTED_MAX_NUM_SEQS=2
DETECTED_GPU_MEM_UTIL=0.95
DETECTED_ENFORCE_EAGER=1
DETECTED_DESCRIPTION='AutoTrust GEV-26B-Decide MoE (BF16, TP2, 2 GPUs)'
```

```bash
python3 detect_model.py <dir> --json          # verify.sh 用
python3 detect_model.py <dir> --tp 4          # 按 TP4 校验可行性
```

---

## 4. 覆盖启动参数

显式环境变量优先于检测结果。

```bash
# 换卡
GPUS=12,13,14,15 ./run.sh /mnt/disk0/models/google/gemma-4-31B-it

# 换端口和模型名
PORT=9001 SERVED_NAME=my-gemma4 ./run.sh /mnt/disk0/models/google/gemma-4-31B-it

# 加 vLLM 参数
EXTRA_ARGS="--max-model-len 16384" ./run.sh /mnt/disk0/models/google/gemma-4-31B-it

# 加 docker 参数
EXTRA_DOCKER_ARGS="-v /mnt/disk1:/data:ro" ./run.sh /mnt/disk0/models/google/gemma-4-31B-it

# 用已有镜像（CI 产物）不重新 build
BUILD=0 IMAGE=harbor.4pd.io/modelhubxc/xiejiahao/gemma4-bi150:v0.1.0 \
  ./run.sh /mnt/disk0/models/google/gemma-4-31B-it

# 只打印命令
DRY_RUN=1 ./run.sh /mnt/disk0/models/google/gemma-4-31B-it
```

常用环境变量：

```text
IMAGE NAME MODEL_HOST_DIR MODEL_MOUNT PORT SERVED_NAME TP GPUS
MAX_MODEL_LEN MAX_NUM_SEQS GPU_MEM_UTIL MAX_IMAGES ENFORCE_EAGER
AUTO_DETECT HEALTH_TIMEOUT EXTRA_ARGS EXTRA_DOCKER_ARGS BUILD DRY_RUN
GEMMA4_SKIP_TP_CHECK
```

`AUTO_DETECT=0` 可关闭容器内检测，全部手动给值。

---

## 5. 为什么 Dockerfile 里没有 ENV / EXPOSE / ENTRYPOINT

镜像必须能同时服务 dense 和 MoE 两个变体，而这些参数在两个变体之间不同：

| 参数 | Gemma-4-31B | GEV-26B-Decide |
|---|---:|---:|
| TP | 4 | 2 |
| 端口 | 8095 | 8094 |
| eager | 0 | 1 |
| 显存 | 0.90 | 0.95 |
| seqs | 4 | 2 |

写进镜像就只能二选一，或者做两个镜像，违背"一个家族一个镜像"的目标。
所以启动方式统一由 `run.sh` / `docker-compose.yml` 传入：

```bash
docker run ... \
  --entrypoint /usr/local/bin/gemma4-entrypoint.sh \
  --workdir /opt/gemma4 \
  --expose 8095 \
  -e MODEL_PATH=/models/gemma4 \
  -e AUTO_DETECT=1 \
  <image>
```

---

## 6. 补丁

`apply_patch.py` 应用两个补丁，构建镜像时和容器启动时都会幂等执行一次。

| 补丁 | 目标文件 | 不打的后果 |
|---|---|---|
| `MultiModalDataDict` 导入路径 | `vllm/model_executor/models/gemma4_mm.py` | `ImportError`，模型检查阶段就失败（**两个变体都需要**） |
| decode fast path 的 attention metadata 判断 | `vllm/model_executor/layers/fused_moe/fused_moe.py` | GEV 的 CUDA graph capture 报 `AttributeError: no attribute 'num_decodes'` |

第二个补丁对 dense 的 Gemma-4-31B 通常用不到，但保持幂等一起打，避免同一镜像换模型后失效。

补丁是针对这个精确基础镜像生成的，换镜像需要重新生成：

```text
registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v7
vLLM 0.17.0+corex.20260612070235
```

---

## 7. 验证

```bash
# 自动找运行中的容器
./verify.sh

# 指定模型目录（推荐，能顺带校验变体）
./verify.sh --model-dir /mnt/disk0/models/google/gemma-4-31B-it

# 指定容器
./verify.sh --container gemma4-31b

# 额外图片识别
./verify.sh --model-dir /mnt/disk0/models/autotrust/GEV-26B-Decide --with-image

# 额外推理题（期望 27）
./verify.sh --model-dir /mnt/disk0/models/google/gemma-4-31B-it --with-reasoning

# 直接指定服务地址
./verify.sh --base-url http://127.0.0.1:8095 --served-name gemma-4-31B-it
```

检查项：`/health`、`/v1/models`、`/v1/chat/completions`，可选推理题和图片识别。
只依赖 `bash`、`curl`、`python3`。全部通过返回 0。

> `/health` 只看 `curl` 退出码，不看 body——vLLM 会返回 200 但 body 为空。

---

## 8. 关键参数的理由

### 8.1 Gemma-4-31B 为什么是 TP4

```text
Gemma4ForConditionalGeneration
  num_attention_heads        = 32
  num_key_value_heads        = 16     # sliding attention
  num_global_key_value_heads = 4      # full attention
  head_dim / global_head_dim = 256 / 512
  num_hidden_layers          = 60
```

`num_global_key_value_heads=4` 是最紧的约束：TP8 会切成 0.5，当前 vLLM 不支持。
TP4 下 4/4=1，权重 58.25 GiB / 4 ≈ 14.6 GiB/卡，实测加载后 15.89 GiB/卡。

### 8.2 GEV-26B-Decide 为什么是 TP2

```text
Gemma4ForConditionalGeneration
  hidden_size           = 2816
  num_hidden_layers     = 30
  num_attention_heads   = 16
  num_key_value_heads   = 8
  moe_intermediate_size = 704
  num_experts           = 128
  top_k_experts         = 8
```

CoreX `ixfops.moe_w16a16_group_gemm` 要求分组 GEMM 的 K 维能被 32 整除，
`704 / TP` 的结果：TP8→88 ❌、TP4→176 ❌、TP2→352 ✅。
TP1 显存不够，所以只有 TP2。

### 8.3 GEV 为什么开 `--enforce-eager`

MoE + CoreX 的 CUDA graph 路径不稳定，实测开 eager 才能稳定启动；
dense 的 Gemma-4-31B 不需要，关掉可以拿到更好的吞吐。

### 8.4 GEV 为什么用 0.95 显存

权重 48.07 GiB / 2 ≈ 24.99 GiB/卡，0.95 下 KV 约 4.9 GiB，适合低并发。
`max-num-seqs` 同时降到 2，避免 KV 被并发打爆。

---

## 9. GPU 选择

`run.sh` 默认优先序号大的卡，避免和 16 卡大模型抢 0-11：

```text
Gemma-4-31B  → 15,14,13,12
GEV-26B-Decide → 14,15
```

卡数不足会直接报错，卡数多余只警告（vLLM 只用前 TP 张）：

```bash
GPUS=12,13 ./run.sh .../gemma-4-31B-it        # 报错：需要 4 张
GPUS=0,1,2,3,4,5 ./run.sh .../GEV-26B-Decide  # 警告：只用其中 2 张
```

查看空闲卡：

```bash
/usr/local/corex/bin/ixsmi
```

---

## 10. 常见问题

| 现象 | 原因 | 处理 |
|---|---|---|
| `ImportError: cannot import name 'MultiModalDataDict'` | 补丁没打上 | 确认 `apply_patch.py` 执行过 |
| `AttributeError: 'TritonAttentionMetadata' object has no attribute 'num_decodes'` | MoE 补丁没打上 | 同上 |
| `Expected k % 32 == 0 to be true` | GEV 用了 TP4/TP8 | 回到 TP2；`detect_model.py` 会提前拦住 |
| KV head 无法切分 / head 数不整除 | dense 用了 TP8 | 回到 TP4 |
| `cudaGetDeviceCount() ... Error 1001` | 少了 `--privileged -v /dev:/dev` | 用 `run.sh`，不要手写简化版 `docker run` |
| 启动 10 分钟还没 ready | 冷读 49–59 GB 权重 | 默认给 900s；`docker logs -f` 看 `Loading weights` |
| `/health` 超时但容器在跑 | 还在加载权重 | 以 `Loading weights took` 和 `/v1/models` 为准 |

---

## 11. CI 与发布

```bash
# 首次
git tag v0.1.0 && git push origin v0.1.0
```

- 只有推送 `v*` 标签才触发；
- runner label：`amd64-ubuntu-24.04`，需要 `DOCKER_*` / `FIXED_TOKEN`；
- `task_info.env`：`FRAMEWORK=vllm_gemma_4`（必须独特，不要用泛化的 `vllm`）；
- CI 被取消后**不要复用标签**，直接 bump patch；
- CI 构建 vLLM 基础镜像较久，本次预计 1.5 小时量级，别着急。

CI 产物通用，不会自动启动，用 `run.sh` 指定 entrypoint：

```bash
BUILD=0 IMAGE=<ci-image> ./run.sh /mnt/disk0/models/google/gemma-4-31B-it
```

---

## 12. 为什么可以合并

合并前是 `gemma4-31b-deploy/` 和 `gev-26b-decide-deploy/` 两套目录。逐项对比：

| 项 | Gemma-4-31B | GEV-26B-Decide | 能否 detect |
|---|---|---|---|
| 基础镜像 | 同一个 | 同一个 | — |
| 架构 | `Gemma4ForConditionalGeneration` | 同一个 | 不需要 |
| vLLM 补丁 | 两个 | 同样两个 | 不需要 |
| docker run 参数 | 相同 | 相同 | — |
| TP | 4 | 2 | ✅ config 可判 |
| 端口 | 8095 | 8094 | ✅ config 可判 |
| served name | `gemma-4-31B-it` | `GEV-26B-Decide` | ✅ config 可判 |
| eager | 0 | 1 | ✅ config 可判 |
| 显存 / seqs | 0.90 / 4 | 0.95 / 2 | ✅ config 可判 |

差异项全部可由 `config.json` 推断，和 Llama 4 用 `num_local_experts` 分 Scout/Maverick 是同一形态，
因此按"一个模型家族一个仓库"的原则合并。

顺带解决的问题：

1. 两份 `apply_patch.py` 原本只差注释，现在只有一份；
2. 两个 Dockerfile 原本都写死了 `ENV/EXPOSE/ENTRYPOINT`，现在通用；
3. 一次 CI 覆盖两个模型，而不是两次构建（每次约 1.5 小时）；
4. 新增 TP 可行性校验，把"GEV 只能 TP2、Gemma4 只能 TP4"从文档结论变成启动前断言。

---

## 13. 变更记录

| 日期 | 变更 |
|---|---|
| 2026-10-27 | 由 `gemma4-31b-deploy` + `gev-26b-decide-deploy` 合并为本目录；新增 `detect_model.py`、`verify.sh`、`.gitea`；Dockerfile 去掉 ENV/EXPOSE/ENTRYPOINT；新增 TP 可行性校验和 `GEMMA4_SKIP_TP_CHECK` |