# Z100L 可迁移重部署包使用说明 这份交付的目标不是“直接把模型也带过去”，而是： - **把除模型外的运行资源都打包** - 在另一台**已经安装好驱动和 DTK** 的新机器上 - 按固定步骤重新部署出当前这套可运行的 `PyTorch + vLLM + Gemma4` 环境 这份包默认面向和当前机器**同类**的新环境，也就是： - Ubuntu 22.04 系 - DTK 安装在 `/opt/dtk-26.04` - Z100L / `gfx906` - Python 3.10 它不是“任意 Linux 机器的通用二进制包”，而是一个**同类 Z100L 环境的可重建包**。 ## 1. 交付内容 当前目录包含两部分： ### 1. 资源包 - `z100l-redeploy-resources-20260421.tar.gz` 里面包含： - 已验证可运行的源码树 - `sources/pytorch-clean-v291` - `sources/vllm-0191-test` - `sources/aiter` - `triton` wheel - `FindHIP.cmake` shim - `z100l-smoke` - `pip-freeze.txt` - PyTorch / vLLM patch 文件 注意： - **模型不在包里** - Docker 镜像也不在这个包里 - 这是 host 直接运行路线 ### 2. overlay 目录 - `overlay/` 这里面是为“新机器重部署”补的可迁移脚本，作用是： - 去掉旧机器上的绝对路径 - 提供可迁移版 `envs/dtk26-z100l.sh` - 提供可迁移版 smoke 脚本 - 提供最小化的构建/启动脚本 ## 2. 新机器前置条件 新机器至少要满足这些条件： ### 硬件 - `Z100L` 显卡，建议至少 1 张 - 如果要跑更大的模型，建议多卡 - 内存建议至少 `64GB` - 磁盘建议至少保留 `200GB+` ### 系统 - Ubuntu `22.04` - Python `3.10` - `git` - `curl` - `build-essential` ### GPU 运行时 - 海光驱动已正常安装 - DTK 已正常安装到： - `/opt/dtk-26.04` - `rocminfo` 能正常识别到 `gfx906 / Z100L` 这份包**不包含驱动和 DTK**，因为它们必须由宿主机自己提供。 ## 3. 推荐的部署根目录 建议在新机器上选择一个固定目录，例如： ```bash export DEPLOY_ROOT=/opt/z100l-stack sudo mkdir -p "${DEPLOY_ROOT}" sudo chown -R "$USER":"$USER" "${DEPLOY_ROOT}" ``` ## 4. 第一步：复制资源包和 overlay 到新机器 把这两个东西复制到新机器： - `z100l-redeploy-resources-20260421.tar.gz` - `overlay/` 例如放到： ```bash ${DEPLOY_ROOT} ``` ## 5. 第二步：解压资源包 在新机器上执行： ```bash cd "${DEPLOY_ROOT}" tar -xzf z100l-redeploy-resources-20260421.tar.gz ``` 解压后你会看到类似结构： ```text envs/ cmake-shims/ z100l-smoke/ src/pytorch-clean-v291/ src/vllm-0191-test/ src/aiter/ src/triton-rocm/dist/triton-3.6.0-cp310-cp310-linux_x86_64.whl redeploy-pack-20260421/metadata/pip-freeze.txt redeploy-pack-20260421/patches/*.patch ``` ## 6. 第三步：用 overlay 覆盖可迁移脚本 把 `overlay/` 里的内容覆盖到部署根目录： ```bash cp -a overlay/. "${DEPLOY_ROOT}/" ``` 这一步非常重要。原因是资源包里原始脚本还带有旧机器路径，overlay 会把它们替换成可迁移版本。 ## 7. 第四步：准备 Python venv 建议先新建一套独立 venv： ```bash bash "${DEPLOY_ROOT}/scripts/prepare_venv.sh" "${DEPLOY_ROOT}/venv" ``` 这个脚本会做几件事： 1. 创建 venv 2. 安装基础构建工具 3. 安装 vLLM 的 common Python 依赖 4. 安装打包进去的 `triton` wheel 5. 安装打包进去的 `aiter` 源码 注意： - 这一步不会下载模型 - 这一步也不会自动重编 PyTorch ## 8. 第五步：先尝试直接导入已打包产物 这份资源包里已经带了当前机器上可运行的源码树和关键二进制产物。 如果新机器环境和当前机器足够接近，先试直接导入。 执行： ```bash source "${DEPLOY_ROOT}/scripts/use_bundle_paths.sh" "${DEPLOY_ROOT}/venv" python -c 'import torch; print(torch.__version__); print(torch.version.hip)' python -c 'import vllm; print(vllm.__version__)' ``` 如果这两条都成功，说明新机器可以直接用打包进去的源码树和二进制。 ## 9. 如果 torch 导入失败：重编 PyTorch 最小目标 如果新机器上 `import torch` 失败，再执行： ```bash bash "${DEPLOY_ROOT}/scripts/build_pytorch_minimal.sh" "${DEPLOY_ROOT}/venv" ``` 这个脚本会： - 使用 `/opt/dtk-26.04` - 用 `gfx906` - 重新配置并构建最关键的几个目标： - `c10` - `c10_hip` - `torch_cpu` - `torch_hip` 构建完成后再重新测试： ```bash source "${DEPLOY_ROOT}/scripts/use_bundle_paths.sh" "${DEPLOY_ROOT}/venv" python -c 'import torch; print(torch.__version__); print(torch.version.hip)' ``` ## 10. 第六步：跑底层 smoke test 先不要急着上大模型，先确认 GPU 计算链路正常。 执行： ```bash bash "${DEPLOY_ROOT}/z100l-smoke/run_all.sh" ``` 这一步会验证： - `hipcc` - `rocminfo` - HIP runtime - hipBLAS SGEMM - Python ctypes 直连 HIP runtime ## 11. 第七步：启动 vLLM 模型不在资源包里，所以这里要你自己指定模型路径。 例如模型目录是： ```bash export MODEL=/data/models/google/gemma-4-E2B-it ``` 然后执行： ```bash bash "${DEPLOY_ROOT}/scripts/run_vllm_api.sh" "${DEPLOY_ROOT}/venv" ``` 默认参数是： - `--enforce-eager` - `--attention-backend TRITON_ATTN` - `--gpu-memory-utilization 0.82` - `--max-model-len 512` 你也可以在启动前改： ```bash export TOKENIZER="${MODEL}" export PORT=8000 export GPU_UTIL=0.70 export MAX_MODEL_LEN=512 export DTYPE=float16 ``` ## 12. 第八步：验证 API 另开终端，执行： ```bash curl -s http://127.0.0.1:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "'"${MODEL}"'", "messages": [ {"role": "user", "content": "Say hello in exactly five words."} ], "temperature": 0.0, "max_tokens": 16 }' ``` ## 13. 资源包里几个重要文件的用途 ### `envs/dtk26-z100l.sh` 可迁移版 DTK 环境脚本。 它会自动把 `cmake-shims/FindHIP.cmake` 接到当前部署根目录下，不再依赖旧机器的 `/home/muyi`。 ### `cmake-shims/FindHIP.cmake` 给这套非标准 DTK 布局补 HIP 发现逻辑。 这个文件对 PyTorch 的 HIP/CMake 发现很关键。 ### `src/pytorch-clean-v291` 当前可运行 PyTorch 源码树。 这棵树已经不是纯上游，它包含了当前验证可用的修改。 ### `src/vllm-0191-test` 当前可运行的 `v0.19.1` 基座源码树。 里面包含 `gfx906/Z100L` 相关兼容修正。 ### `redeploy-pack-20260421/patches/*.patch` 这是 patch 参考，不是必须第一时间使用。它们的用途主要是： - 对照上游 - 审计改动范围 - 后续想最小化迁移时用 ## 14. 已知边界 ### 这份包不包含模型 模型必须你自己准备。 ### 这份包默认面向同类环境 也就是： - Ubuntu 22.04 - 同类 Z100L / `gfx906` - 同类 DTK 路径 如果你换成完全不同的系统或工具链，不保证直接导入现成二进制还能用。 ### 如果现成二进制导入失败 优先重编 PyTorch，再测试。 不要先去碰 Docker，不要先去走 vendor demo。 ## 15. 推荐的最短重部署路径 如果你只想快速验证新机器能不能复现，按这个顺序走： 1. 解压资源包 2. 覆盖 `overlay/` 3. `bash scripts/prepare_venv.sh` 4. `source scripts/use_bundle_paths.sh` 5. 直接试 `import torch` / `import vllm` 6. 跑 `z100l-smoke/run_all.sh` 7. 再启动 `run_vllm_api.sh` 如果第 5 步失败，再跑： 8. `bash scripts/build_pytorch_minimal.sh` ## 16. 当前建议 新机器第一次复现时，先用更小的 `Gemma 4 E2B` 做最小成功验证； 等 API 和短对话通了，再上更大的模型。 这样最稳。 ## 以下是海光卡有群，有兴趣的加入