Switch to bridge networking with fixed container port 80 and served name llm

- run.sh: bridge + -p ${HOST_PORT:-24396}:80, health check uses host port - entrypoint.sh: PORT defaults to 80, SERVED_NAME defaults to llm detected port/served name become log hints only - verify.sh: read host port from port bindings, expect model name llm - docker-compose.yml: ports mapping instead of network_mode host - README: update tables, commands and rationale
2026-10-28 14:19:42 +08:00
parent d2624682ca
commit ade41407d7
5 changed files with 99 additions and 56 deletions
--- a/README.md
+++ b/README.md
@@ -2,10 +2,12 @@

 一个镜像同时支持两个 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 |
+| 模型 | 类型 | 权重 | TP | 卡数 | eager | 显存 | seqs |
+|---|---|---:|---:|---:|---:|---:|---:|
+| `gemma-4-31B-it` | dense，60 层 | 58.25 GiB | **4** | 4 | 0 | 0.90 | 4 |
+| `GEV-26B-Decide` | MoE，30 层 / 128 experts | 48.07 GiB | **2** | 2 | 1 | 0.95 | 2 |
+
+两个变体共用：容器内端口 **80**、模型名 **`llm`**、宿主端口 **24396**（由 `-p` 决定）。

 > 本仓库由原先各自独立的 `gemma4-31b-deploy` 和 `gev-26b-decide-deploy` 两套目录合并而来，
 > 合并依据见文末「为什么可以合并」。
@@ -87,8 +89,8 @@ 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 > 1` | GEV-26B-Decide（MoE） | TP2 / eager1 / 0.95 / 2 seqs |
+| `experts` 缺失或 `== 1` | Gemma-4-31B（dense） | TP4 / eager0 / 0.90 / 4 seqs |
 | 无 experts 且目录名含 `gev` | GEV | 同上 |
 | 无 experts 且目录名含 `gemma` | Gemma-4-31B | 同上 |
 | 其它 / 架构不是 Gemma4 | 直接报错 | 不启动 |
@@ -122,8 +124,8 @@ TP=4 ./run.sh .../GEV-26B-Decide      # 704/4=176，k % 32 != 0
 $ 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_PORT=8094              # 仅提示，不决定实际端口
+DETECTED_SERVED_NAME=GEV-26B-Decide   # 仅提示，模型名固定 llm
 DETECTED_GPU_COUNT=2
 DETECTED_MAX_NUM_SEQS=2
 DETECTED_GPU_MEM_UTIL=0.95
@@ -147,7 +149,7 @@ python3 detect_model.py <dir> --tp 4          # 按 TP4 校验可行性
 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
+HOST_PORT=24397 ./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
@@ -183,7 +185,6 @@ GEMMA4_SKIP_TP_CHECK
 | 参数 | Gemma-4-31B | GEV-26B-Decide |
 |---|---:|---:|
 | TP | 4 | 2 |
-| 端口 | 8095 | 8094 |
 | eager | 0 | 1 |
 | 显存 | 0.90 | 0.95 |
 | seqs | 4 | 2 |
@@ -195,8 +196,10 @@ GEMMA4_SKIP_TP_CHECK
 docker run ... \
  --entrypoint /usr/local/bin/gemma4-entrypoint.sh \
  --workdir /opt/gemma4 \
-  --expose 8095 \
+  -p 24396:80 \
  -e MODEL_PATH=/models/gemma4 \
+  -e PORT=80 \
+  -e SERVED_NAME=llm \
  -e AUTO_DETECT=1 \
  <image>
 ```
@@ -242,7 +245,7 @@ vLLM 0.17.0+corex.20260612070235
 ./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
+./verify.sh --base-url http://127.0.0.1:24396 --served-name llm
 ```

 检查项：`/health`、`/v1/models`、`/v1/chat/completions`，可选推理题和图片识别。
@@ -373,47 +376,54 @@ CI 的 `naming to` 行与本表 digest 一致，可作为复核依据。

 镜像不声明 `ENTRYPOINT`，`--entrypoint` 必须显式给。以下命令可直接粘贴。

-**Gemma-4-31B-it（TP4，4 卡，8095）**
+**Gemma-4-31B-it（TP4，4 卡，宿主 24396 → 容器 80）**

 ```bash
 docker run -d --name gemma4-31b \
  --entrypoint /usr/local/bin/gemma4-entrypoint.sh \
  --workdir /opt/gemma4 \
-  --privileged --pid host --network host --ipc host \
+  --privileged --pid host --ipc host \
  -v /dev:/dev \
  -v /mnt/disk0/models/google/gemma-4-31B-it:/models/gemma4:ro \
  --ulimit memlock=-1 --ulimit stack=67108864 \
+  -p 24396:80 \
  -e CUDA_VISIBLE_DEVICES=15,14,13,12 \
  -e MODEL_PATH=/models/gemma4 \
+  -e PORT=80 \
+  -e SERVED_NAME=llm \
  -e AUTO_DETECT=1 \
  -e PYTHONUNBUFFERED=1 \
  --restart unless-stopped \
  harbor.4pd.io/modelhubxc/xiejiahao/gemma4-bi150:v0.1.0
 ```

-**GEV-26B-Decide（TP2，2 卡，8094）**
+**GEV-26B-Decide（TP2，2 卡，宿主 24396 → 容器 80）**

 ```bash
 docker run -d --name gev-26b-decide \
  --entrypoint /usr/local/bin/gemma4-entrypoint.sh \
  --workdir /opt/gemma4 \
-  --privileged --pid host --network host --ipc host \
+  --privileged --pid host --ipc host \
  -v /dev:/dev \
  -v /mnt/disk0/models/autotrust/GEV-26B-Decide:/models/gemma4:ro \
  --ulimit memlock=-1 --ulimit stack=67108864 \
+  -p 24396:80 \
  -e CUDA_VISIBLE_DEVICES=14,15 \
  -e MODEL_PATH=/models/gemma4 \
+  -e PORT=80 \
+  -e SERVED_NAME=llm \
  -e AUTO_DETECT=1 \
  -e PYTHONUNBUFFERED=1 \
  --restart unless-stopped \
  harbor.4pd.io/modelhubxc/xiejiahao/gemma4-bi150:v0.1.0
 ```

-两个变体共用挂载点 `/models/gemma4`，靠 `config.json` 区分；TP / 端口 / eager / 显存 / 并发数都不用传，入口脚本会自动判定（见第 3 节）。
+两个变体共用挂载点 `/models/gemma4`，靠 `config.json` 区分；TP / eager / 显存 / 并发数都不用传，入口脚本会自动判定（见第 3 节）。

-需要覆盖时加同名 `-e`，例如 `-e MAX_MODEL_LEN=16384`、`-e PORT=24396`。
+容器内端口恒为 80、模型名恒为 `llm`，所以两个变体可以复用同一个宿主端口 24396，串行切换时客户端不用改地址也不用改 `model` 字段。
+需要覆盖时加同名 `-e`，例如 `-e MAX_MODEL_LEN=16384`。

-**注意**：`--network host` 下不要写 `-p`，端口映射会被丢弃；要换对外端口就传 `-e PORT=<port>`。
+**注意**：并行跑两个变体时必须给不同的 `-p` 左侧端口，例如 `-p 24397:80`。

 ### 11.3 用 run.sh 启动 CI 镜像

@@ -437,10 +447,10 @@ BUILD=0 IMAGE=harbor.4pd.io/modelhubxc/xiejiahao/gemma4-bi150:v0.1.0 \
 | 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 可判 |
+| 端口 | 80 | 80 | 统一，无需判定 |
+| served name | `llm` | `llm` | 统一，无需判定 |

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