Unified Llama 4 Scout/Maverick BI-V150 deployment bundle
This commit is contained in:
222
README.md
Normal file
222
README.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 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. 目录内容
|
||||
|
||||
```text
|
||||
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 脚本（推荐）
|
||||
|
||||
```bash
|
||||
# Scout：8 卡，8091
|
||||
./run.sh scout
|
||||
|
||||
# Maverick：16 卡，8092
|
||||
./run.sh maverick
|
||||
```
|
||||
|
||||
`run.sh` 会先 `docker build`，再删除同名容器、启动新容器，并等待 `/health` 最多 10 分钟。
|
||||
|
||||
### 2.2 指定 GPU 和模型目录
|
||||
|
||||
所有预设值都可以用环境变量覆盖：
|
||||
|
||||
```bash
|
||||
# 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（可选）
|
||||
|
||||
```bash
|
||||
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. 验证
|
||||
|
||||
```bash
|
||||
# 健康检查
|
||||
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 图片输入测试：
|
||||
|
||||
```python
|
||||
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：
|
||||
|
||||
```text
|
||||
.gitea/workflows/docker-build-push.yml
|
||||
.gitea/workflows/task_info.env
|
||||
```
|
||||
|
||||
触发方式：
|
||||
|
||||
```bash
|
||||
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`：
|
||||
|
||||
```bash
|
||||
FRAMEWORK=vllm
|
||||
GPU_TYPE=Iluvatar_bi-150
|
||||
TASK_TYPE=text-generation
|
||||
```
|
||||
|
||||
Runner 需要配置以下环境变量（不是仓库 secret）：
|
||||
|
||||
```text
|
||||
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`。
|
||||
- 模型目录只读挂载，容器不会修改宿主机模型文件。
|
||||
Reference in New Issue
Block a user