Llama 4 Scout / Maverick on Iluvatar BI-V150

在 16×Iluvatar BI-V150 32GB 上运行 Llama 4 Scout 与 Maverick 的统一 Docker 部署仓库。

• 基础镜像：registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v7（vLLM 0.17.0+corex）
• 一个镜像同时支持 Scout 和 Maverick；模型权重不打进镜像，运行时只读挂载
• 两个模型共用 Llama 4 chunked-attention 补丁；Maverick 额外使用 FP8 量化 / FP8 MoE 补丁
• CI 使用 ModelHub 标准 Gitea Actions：推送 v* 标签后构建、推送镜像并提交审核

模型	精度	并行	GPU 数	默认端口
LLM-Research/Llama-4-Scout-17B-16E-Instruct	BF16	TP8	8	8091
LLM-Research/Llama-4-Maverick-17B-128E-Instruct-FP8	FP8	TP8 + PP2	16	8092

---

1. 目录内容

llama4-bi150-deploy/
├── Dockerfile
├── entrypoint.sh
├── apply_patch.py              # 幂等应用全部 Llama 4 补丁
├── patches/
│   ├── 01_fp8_quant.patch      # Maverick FP8 量化
│   ├── 02_fp8_moe.patch        # Maverick FP8 MoE
│   ├── 03_llama4_chunked_attn.patch
│   └── corexx_fp8_moe.py       # 逐 expert 反量化 BF16 的 FP8 MoE 回退
├── presets/
│   ├── scout.env
│   └── maverick.env
├── run.sh                      # 构建 + 启动 + 等 /health
├── docker-compose.yml          # 可选，按 profile 启动
├── .gitea/workflows/
│   ├── docker-build-push.yml
│   └── task_info.env
└── README.md

---

2. 构建与启动

2.1 脚本（推荐）

# Scout：8 卡，8091
./run.sh scout

# Maverick：16 卡，8092
./run.sh maverick

run.sh 会先 docker build，再删除同名容器、启动新容器，并等待 /health 最多 10 分钟。

2.2 指定 GPU 和模型目录

所有预设值都可以用环境变量覆盖：

# Scout 使用 8-15 号卡
GPUS=8,9,10,11,12,13,14,15 ./run.sh scout

# Maverick 使用 0-15 号卡
GPUS=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15 ./run.sh maverick

# 模型放在其他目录
MODEL_HOST_DIR=/mnt/disk1/models/Llama-4-Scout-17B-16E-Instruct ./run.sh scout

# 额外挂载一个目录
EXTRA_DOCKER_ARGS="-v /mnt/disk1:/data:ro" ./run.sh scout

# 传递额外 vLLM 参数
EXTRA_ARGS="--max-model-len 8192" ./run.sh scout

# 已有镜像，不重新构建
BUILD=0 IMAGE=registry.example.com/llama4-bi150:v1.0.0 ./run.sh scout

# 只打印 docker run 命令，便于检查
DRY_RUN=1 ./run.sh scout

2.3 Docker Compose（可选）

docker compose --profile scout up -d --build
docker compose --profile maverick up -d --build

# 覆盖模型目录 / GPU
SCOUT_MODEL_HOST_DIR=/mnt/disk1/models/scout SCOUT_GPUS=8,9,10,11,12,13,14,15 \
  docker compose --profile scout up -d --build

---

3. 可配置项

变量	Scout 默认	Maverick 默认	说明
IMAGE	llama4-bi150:2026-10-26	同左	镜像名
NAME	llama4-scout	llama4-maverick	容器名
PORT	8091	8092	宿主机端口
MODEL_HOST_DIR	.../Llama-4-Scout-17B-16E-Instruct	.../Llama-4-Maverick-17B-128E-Instruct-FP8	宿主机模型目录
MODEL_MOUNT	/models/llama4	同左	容器内挂载点
SERVED_NAME	llama4-scout	llama4-maverick	OpenAI API 模型名
TP	8	8	张量并行
PP	1	2	流水线并行
GPUS	0,...,7	0,...,15	传给 CUDA_VISIBLE_DEVICES
MAX_MODEL_LEN	4096	4096	最大上下文
MAX_NUM_SEQS	1	1	最大并发
GPU_MEM_UTIL	0.90	0.90	显存利用率
ENFORCE_EAGER	1	1	是否 --enforce-eager
EXTRA_ARGS	空	空	额外 vLLM 参数
EXTRA_DOCKER_ARGS	空	空	额外 docker 参数，如 -v
BUILD	1	1	0 表示跳过构建
DRY_RUN	0	0	1 只打印命令

GPUS 也可以直接用 CUDA_VISIBLE_DEVICES 设置。run.sh 会检查 GPU 数是否少于 TP*PP，少于时直接报错。

---

4. 验证

# 健康检查
curl -s http://127.0.0.1:8091/health
curl -s http://127.0.0.1:8092/health

# 模型列表
curl -s http://127.0.0.1:8091/v1/models | python3 -m json.tool
curl -s http://127.0.0.1:8092/v1/models | python3 -m json.tool

# 文本
curl -s http://127.0.0.1:8091/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"llama4-scout","messages":[{"role":"user","content":"你好"}],"max_tokens":64}'

Maverick 图片输入测试：

from PIL import Image
import base64, io, requests

img = Image.new("RGB", (336, 336), (220, 20, 20))
buf = io.BytesIO(); img.save(buf, format="PNG")
b64 = base64.b64encode(buf.getvalue()).decode()

payload = {
    "model": "llama4-maverick",
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "这张图片主要是什么颜色？只回答颜色。"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64," + b64}},
    ]}],
    "max_tokens": 32,
    "temperature": 0,
}
print(requests.post("http://127.0.0.1:8092/v1/chat/completions",
                    json=payload, timeout=300).json()["choices"][0]["message"]["content"])

首次使用统一镜像时，建议把 Scout 和 Maverick 都跑一遍，确认 FP8 补丁没有影响 Scout 的 BF16 路径。

---

5. CI / ModelHub 发布

仓库已包含 ModelHub 标准 CI：

.gitea/workflows/docker-build-push.yml
.gitea/workflows/task_info.env

触发方式：

git tag v1.0.0
git push origin v1.0.0

CI 会：

1. 在 amd64-ubuntu-24.04 runner 上 clone 仓库；
2. 校验 task_info.env；
3. docker build；
4. 推送 ${DOCKER_REGISTRY}/${DOCKER_USERNAME}/llama-4-bi150:v1.0.0；
5. 调 ModelHub image-verify 接口提交审核。

task_info.env：

FRAMEWORK=vllm
GPU_TYPE=Iluvatar_bi-150
TASK_TYPE=text-generation

Runner 需要配置以下环境变量（不是仓库 secret）：

DOCKER_REGISTRY
DOCKER_USERNAME
DOCKER_PASSWORD
FIXED_TOKEN

注意事项：

• Runner 必须能拉取 registry.iluvatar.com.cn:10443 的基础镜像；如果该仓库需要登录，请在 runner 上预登录，或自行给 workflow 增加基础镜像 registry 的 login step。
• CI 只负责构建和推送，不负责 GPU / 模型挂载；GPU 和挂载通过 run.sh 或 docker compose 设置。
• CI 构建机不需要 GPU，但需要足够的磁盘空间。
• 如果仓库改名，CI 生成的镜像名会跟着变。

---

6. 限制与注意事项

• Scout 需要 8 张卡（TP8）；Maverick 需要 16 张卡（TP8+PP2）。16 卡机器上两者不能同时运行。
• 当前默认 MAX_MODEL_LEN=4096、MAX_NUM_SEQS=1，适合功能验证；生产并发需要先调整显存/上下文。
• 补丁是针对当前精确基础镜像生成的。更换基础镜像后不要直接复用，需要重新生成 diff 并在目标环境验证。
• --privileged --pid host -v /dev:/dev 是 Iluvatar 运行时要求；只给 /dev/iluvatar* 可能报 cudaGetDeviceCount() ... Error 1001。
• 模型目录只读挂载，容器不会修改宿主机模型文件。