# Z100L 通用开源模型栈可移植包教程 **（跟着教程还玩不转的朋友们，优先把教程发给你的AIagent，让他去弄）** > 适用对象：已经装好海光驱动、DTK 26.04、Ubuntu 22.04 的新机器。 > 本教程从“解压 tar 包”开始，不包含驱动和 DTK 安装。 > 目标：不用海光 demo，不伪装 CUDA，不刷 VBIOS，用通用 PyTorch/HIP + Transformers/HF 语义启动模型。 --- ## 1. 目的 这个压缩包的目的，是把当前 Z100L 上已经验证可用的一套“通用开源模型运行环境”迁移到另一台 Ubuntu 22.04 机器上。 它解决的问题不是“安装海光官方 demo”，而是： - 让海光 Z100L 在通用 `torch.cuda` / HIP 语义下工作。 - 让 Hugging Face Transformers 模型可以直接加载和推理。 - 提供一个最小可运行模型 `Qwen/Qwen2.5-0.5B-Instruct`，不需要首次联网即可验证。 - 提供 CLI 启动方式和 OpenAI-compatible 风格的 HTTP `/v1/chat/completions` 示例。 - 保留通用模型矩阵测试脚本，便于继续验证更多模型类型。 本包不包含： - 海光驱动安装包。 - DTK 安装包。 - 系统内核模块。 - 大模型权重。 - Docker 镜像。 本包包含： - 已验证可用的 Python venv。 - 自编译 PyTorch/HIP 运行时源码目录。 - DTK 环境变量脚本。 - 一个已缓存的小模型：`Qwen/Qwen2.5-0.5B-Instruct`。 - CLI 推理脚本。 - HTTP 模型服务脚本。 - 通用模型矩阵测试脚本和历史报告。 --- ## 2. 原理 ### 2.1 整体结构图 ```mermaid flowchart LR A[Ubuntu 22.04] --> B[海光驱动 hycu/hymgr] B --> C[DTK 26.04 /opt/dtk-26.04] C --> D[libgalaxyhip.so] D --> E[libamdhip64.so symlink] E --> F[PyTorch HIP runtime] F --> G[Transformers] G --> H[HF model cache] H --> I[CLI inference] H --> J[HTTP /v1/chat/completions] ``` ### 2.2 为什么 `torch.cuda` 在海光卡上仍然出现 PyTorch 上层长期把 GPU API 统一暴露成 `torch.cuda`，即使底层是 ROCm/HIP，很多接口名字仍然叫 `cuda`。这不是伪装 NVIDIA，也不是刷 BIOS。 实际链路是： ```text torch.cuda API -> PyTorch HIP backend -> libamdhip64.so -> 海光 DTK 的 libgalaxyhip.so -> hycu 驱动 -> Z100L GPU ``` 所以看到 `torch.cuda.is_available() == True` 是正常现象。关键要看： ```bash python - <<'PY' import torch print(torch.version.hip) print(torch.cuda.get_device_name(0)) PY ``` 如果输出里有 HIP 版本和 `Z100L`，说明跑的是 HIP/DCU 路线，不是 NVIDIA CUDA 路线。 ### 2.3 包内关键目录 解压后目录大致如下： ```text z100l_open_stack_portable_20260524/ env/ activate_z100l_open_stack.sh dtk26-z100l.original.sh runtime/ venv/torch-gpu-z100l/ pytorch_runtime/ torch/ functorch/ torchgen/ models/ hf_home/hub/models--Qwen--Qwen2.5-0.5B-Instruct/ scripts/ relocate_bundle.sh check_preflight.sh run_hip_smoke.py run_qwen25_05b_cli.py start_qwen25_05b_server.py run_universal_matrix_subset.sh tools/ z100l_universal_model_matrix.py reports/ universal_model_matrix_20260524_044952/ ``` ### 2.4 为什么需要 `relocate_bundle.sh` 当前 PyTorch 是 editable 方式安装的，原始路径在旧机器上，例如： ```text /home/muyi/z100l_nas/src/pytorch-z100l-gfx906/torch ``` 迁移到新机器后路径会变，所以必须执行： ```bash bash scripts/relocate_bundle.sh ``` 这个脚本会把 venv 里的 editable 映射改成当前解压目录： ```text 当前解压目录/runtime/pytorch_runtime/torch 当前解压目录/runtime/pytorch_runtime/functorch 当前解压目录/runtime/pytorch_runtime/torchgen ``` 同时它会修复 venv 的 shebang 和 activate 脚本，避免继续指向旧机器路径。 --- ## 3. 和海光 demo 的区别 ### 3.1 海光 demo 路线 典型海光 demo 通常是： ```text 指定模型 -> 指定脚本 -> 指定 vendor patch -> 指定 demo 参数 -> 跑通一个样例 ``` 这种路线的问题： - 可复用性差。 - 换模型容易失败。 - 换 Transformers / vLLM / PyTorch 版本容易失败。 - 很难定位问题是模型、框架、算子、驱动还是脚本。 - 对后续部署大模型、语音模型、多模态模型帮助有限。 ### 3.2 本包路线 本包走的是： ```text DTK 驱动运行时 -> PyTorch HIP -> Transformers / Hugging Face -> 任意模型按类别适配 ``` 差异如下： | 维度 | 海光 demo | 本包通用路线 | | ------------- | -------------- | --------------------------------- | | 目标 | 跑通厂商样例 | 跑通主流开源模型栈 | | API | vendor 脚本 | PyTorch / Transformers | | 模型 | 固定模型 | Hugging Face 模型 | | 可维护性 | 弱 | 强 | | 可定位性 | 依赖 demo 黑盒 | 可分层定位 | | 扩展方向 | demo 改 demo | LLM / ASR / TTS / VLM / Diffusion | | 是否伪装 CUDA | 否 | 否 | | 是否刷 VBIOS | 否 | 否 | ### 3.3 已验证模型类型 当前 Z100L 已经验证过 34 个模型，修复后 28 个可跑，覆盖： - 文本生成。 - 翻译。 - 摘要。 - BERT / Masked LM。 - QA。 - NER。 - Embedding。 - Reranker。 - 图像分类。 - CLIP。 - 图像描述。 - 深度估计。 - VLM。 - Whisper。 - wav2vec2 ASR。 - 音频分类。 - SpeechT5 TTS。 - tiny Stable Diffusion。 这说明路线不是“只跑一个 demo”，而是具备通用模型栈基础。 --- ## 4. 安装环境 下面从新机器上拿到压缩包开始。 假设压缩包叫： ```bash z100l_open_stack_portable_20260524.tar.zst ``` 假设你要解压到： ```bash /opt/z100l-open-stack ``` 如果你不想放 `/opt`，也可以放到： ```bash /home/你的用户名/z100l-open-stack ``` 路径可以变，但执行 `relocate_bundle.sh` 是必须的。 ### 4.1 安装解压和基础工具 ```bash sudo apt update ``` 解释：刷新 Ubuntu 软件源索引，确保后续能安装 `zstd`、`curl` 等工具。 ```bash sudo apt install -y zstd tar curl jq ca-certificates ``` 解释： - `zstd`：解压 `.tar.zst`。 - `tar`：解包 tar。 - `curl`：测试 HTTP 模型服务。 - `jq`：格式化 JSON 输出。 - `ca-certificates`：访问 HTTPS 时需要。 ### 4.2 创建安装目录 ```bash sudo mkdir -p /opt/z100l-open-stack ``` 解释：创建目标安装目录。 ```bash sudo chown -R "$USER:$USER" /opt/z100l-open-stack ``` 解释：把目录所有权交给当前用户，后续不需要每条命令都加 `sudo`。 ### 4.3 解压 tar 包 进入压缩包所在目录，例如： ```bash cd /path/to/package ``` 解释：把当前 shell 切换到压缩包所在位置。 执行解压： ```bash tar --use-compress-program=unzstd -xf z100l_open_stack_portable_20260524.tar.zst -C /opt/z100l-open-stack --strip-components=1 ``` 解释： - `tar`：解 tar 包。 - `--use-compress-program=unzstd`：用 zstd 解压。 - `-xf`：指定要解压的文件。 - `-C /opt/z100l-open-stack`：解到目标目录。 - `--strip-components=1`：去掉压缩包里的顶层目录，让文件直接进入 `/opt/z100l-open-stack`。 解压后检查目录： ```bash ls -la /opt/z100l-open-stack ``` 解释：确认能看到 `env`、`runtime`、`models`、`scripts` 等目录。 ### 4.4 修复可移植路径 ```bash cd /opt/z100l-open-stack ``` 解释：进入解压后的环境目录。 ```bash bash scripts/relocate_bundle.sh ``` 解释： 这一步会修复包内 venv 的路径。它会把原机器路径替换成当前目录路径。 如果不执行这一步，`import torch` 可能仍然尝试访问旧路径，导致失败。 成功时应该看到类似： ```text [OK] bundle relocated: /opt/z100l-open-stack [OK] relocation complete. Next: source /opt/z100l-open-stack/env/activate_z100l_open_stack.sh ``` ### 4.5 激活环境 ```bash source env/activate_z100l_open_stack.sh ``` 解释： 这个脚本会设置： - `ROCM_SOURCE_DIR=/opt/dtk-26.04` - `ROCM_PATH=/opt/dtk-26.04` - `HIP_PATH=/opt/dtk-26.04/hip` - `LD_LIBRARY_PATH`，包含 DTK 的 HIP/HSA/BLAS/rocBLAS/hyhal 库目录。 - `HF_ENDPOINT=https://hf-mirror.com` - `HF_HOME=/opt/z100l-open-stack/models/hf_home` - Python venv。 激活后检查 Python 路径： ```bash which python ``` 解释：确认当前 Python 来自解压包内部，而不是系统 Python。 期望类似： ```text /opt/z100l-open-stack/runtime/venv/torch-gpu-z100l/bin/python ``` ### 4.6 检查驱动和 DTK ```bash bash scripts/check_preflight.sh ``` 解释：执行完整预检，包括： - `hipcc --version` - `hy-smi` - `torch.__version__` - `torch.version.hip` - `torch.cuda.is_available()` - GPU 数量和名称 - 包内模型缓存 成功时关键输出应类似： ```text torch 2.9.1a0+gitd38164a torch_hip 6.3.26113 cuda_available True device_count 4 device 0 Z100L models--Qwen--Qwen2.5-0.5B-Instruct ``` 如果 `cuda_available` 是 `False`，通常说明： - 驱动没加载。 - DTK 路径不对。 - `LD_LIBRARY_PATH` 不完整。 - 机器没有识别到 Z100L。 先用下面命令检查： ```bash hy-smi ``` 解释：确认驱动层能看到卡。 再检查： ```bash ls -ld /opt/dtk /opt/dtk-26.04 ``` 解释：确认 DTK 软链接和目录存在。 ### 4.7 运行最小 HIP / torch smoke ```bash python scripts/run_hip_smoke.py ``` 解释：这个脚本会在 `cuda:0` 上创建 tensor，执行 GPU 计算并同步。 成功输出类似： ```text torch: 2.9.1a0+gitd38164a hip: 6.3.26113 cuda_available: True device_count: 4 sum_sq: 357389824.0 OK: torch HIP tensor smoke passed ``` 这一步通过，说明 PyTorch/HIP 计算链路已经真正可用。 --- ## 5. 运行模型 本包自带一个已经缓存好的模型： ```text Qwen/Qwen2.5-0.5B-Instruct ``` 模型缓存位置： ```text models/hf_home/hub/models--Qwen--Qwen2.5-0.5B-Instruct ``` 默认脚本使用 `local_files_only=True`，所以第一次验证不需要访问 Hugging Face，也不需要代理。 ### 5.1 CLI 方式运行模型 先确保在包目录中，并且环境已激活： ```bash cd /opt/z100l-open-stack source env/activate_z100l_open_stack.sh ``` 解释：进入环境目录并激活 DTK + Python venv。 运行模型： ```bash python scripts/run_qwen25_05b_cli.py --max-new-tokens 96 ``` 解释： - 加载包内 `Qwen/Qwen2.5-0.5B-Instruct`。 - 使用 `torch.bfloat16` 放到 `cuda:0`。 - 生成 96 个新 token。 - 输出加载耗时、推理耗时、token/s 和模型回答。 成功时会看到类似： ```text model: Qwen/Qwen2.5-0.5B-Instruct load_sec: 11.915 infer_sec: 4.214 new_tokens: 32 tok_per_sec: 7.594 --- output --- 通用开源模型栈相比厂商的demo，具有以下优势... ``` 你也可以指定 prompt： ```bash python scripts/run_qwen25_05b_cli.py \ --prompt "用三句话解释 Z100L 为什么可以走通用 PyTorch/HIP 路线。" \ --max-new-tokens 128 ``` 解释： - `--prompt`：指定输入问题。 - `--max-new-tokens`：指定最多生成多少 token。 ### 5.2 启动 HTTP 模型服务 启动服务： ```bash python scripts/start_qwen25_05b_server.py --host 0.0.0.0 --port 18080 ``` 解释： - `--host 0.0.0.0`：允许局域网其他机器访问。 - `--port 18080`：监听端口。 - 启动后模型会常驻内存，不是每次请求冷启动。 如果你只想本机测试，可以用： ```bash python scripts/start_qwen25_05b_server.py --host 127.0.0.1 --port 18080 ``` 解释：只允许本机访问，更安全。 ### 5.3 健康检查 另开一个终端，执行： ```bash curl http://127.0.0.1:18080/health | jq ``` 解释：检查服务是否启动、模型是否加载、torch/HIP 是否可用。 成功输出类似： ```json { "status": "ok", "model": "Qwen/Qwen2.5-0.5B-Instruct", "device": "cuda:0", "torch": "2.9.1a0+gitd38164a", "hip": "6.3.26113", "load_sec": 2.02 } ``` ### 5.4 调用 OpenAI-compatible 风格接口 创建请求文件： ```bash cat > /tmp/z100l_chat.json <<'JSON' { "model": "Qwen/Qwen2.5-0.5B-Instruct", "messages": [ { "role": "user", "content": "用一句话说明 Z100L 通用模型栈是否启动成功。" } ], "max_tokens": 64, "temperature": 0, "stream": false } JSON ``` 解释：写一个标准 JSON 请求。使用文件可以避免 shell 引号和中文编码问题。 发送请求： ```bash curl http://127.0.0.1:18080/v1/chat/completions \ -H "Content-Type: application/json" \ --data-binary @/tmp/z100l_chat.json | jq ``` 解释： - `curl`：发送 HTTP 请求。 - `/v1/chat/completions`：兼容 OpenAI 风格的路径。 - `--data-binary @/tmp/z100l_chat.json`：从文件读取 JSON，避免编码和转义问题。 - `jq`：格式化输出。 返回中重点看： ```json { "choices": [ { "message": { "role": "assistant", "content": "..." } } ], "z100l_metrics": { "infer_sec": 2.856, "tok_per_sec": 11.204 } } ``` ### 5.5 局域网访问 假设模型服务器 IP 是： ```text 192.168.147.248 ``` 服务启动命令必须是： ```bash python scripts/start_qwen25_05b_server.py --host 0.0.0.0 --port 18080 ``` 其他机器调用： ```bash curl http://192.168.147.248:18080/health | jq ``` 解释：如果这里不通，先检查： ```bash ss -lntp | grep 18080 ``` 期望看到： ```text 0.0.0.0:18080 ``` 如果只看到 `127.0.0.1:18080`，说明服务只监听本机，局域网访问不到。 ### 5.6 停止模型服务 前台启动时，按： ```text Ctrl+C ``` 解释：停止 uvicorn 服务并释放显存。 如果你用后台启动，可以查进程： ```bash ps aux | grep start_qwen25_05b_server.py | grep -v grep ``` 解释：找到服务进程。 停止进程： ```bash pkill -f start_qwen25_05b_server.py ``` 解释：结束该模型服务脚本。 确认显存释放： ```bash hy-smi ``` 解释：查看 GPU 显存占用是否回落。 --- ## 6. 其他补充 ### 6.1 如果要下载其他模型 本环境默认使用 hf-mirror： ```bash export HF_ENDPOINT=https://hf-mirror.com ``` 解释：让 Hugging Face Hub 优先走 hf-mirror。 模型缓存放在包内： ```bash export HF_HOME=/opt/z100l-open-stack/models/hf_home ``` 解释：避免把模型塞到系统盘默认缓存目录。 如果要下载一个新模型，可以先激活环境： ```bash cd /opt/z100l-open-stack source env/activate_z100l_open_stack.sh ``` 然后用 Python 触发下载： ```bash python - <<'PY' from transformers import AutoTokenizer, AutoModelForCausalLM model_id = "Qwen/Qwen2.5-0.5B-Instruct" AutoTokenizer.from_pretrained(model_id, trust_remote_code=True) AutoModelForCausalLM.from_pretrained(model_id, trust_remote_code=True) print("download ok") PY ``` 解释：模型会进入 `$HF_HOME`，也就是包内 `models/hf_home`。 ### 6.2 如果新机器有多张卡 本包默认示例只用 `cuda:0`。 原因： - 小模型没必要多卡。 - 单卡最容易验证环境是否正确。 - 多卡 TP / vLLM / SGLang 是下一层优化，不应该混进第一阶段验证。 确认多卡： ```bash python - <<'PY' import torch print(torch.cuda.device_count()) for i in range(torch.cuda.device_count()): print(i, torch.cuda.get_device_name(i)) PY ``` 解释：列出 PyTorch/HIP 能看到的所有 GPU。 ### 6.3 如果报 `libhipblas.so.2` 找不到 通常是 `LD_LIBRARY_PATH` 不完整。 先重新激活环境： ```bash source env/activate_z100l_open_stack.sh ``` 检查： ```bash echo $LD_LIBRARY_PATH ``` 应该包含： ```text /opt/dtk-26.04/lib /opt/dtk-26.04/hip/lib /opt/dtk-26.04/hsa/lib /opt/dtk-26.04/hipblas/lib /opt/dtk-26.04/rocblas/lib /opt/dtk-26.04/.hyhal/lib /opt/dtk-26.04/dcc/lib ``` 确认库存在： ```bash find /opt/dtk-26.04 -name 'libhipblas.so*' -o -name 'librocblas.so*' ``` 解释：如果找不到，说明 DTK 安装不完整或路径不是 `/opt/dtk-26.04`。 ### 6.4 如果 `torch` 仍然指向旧路径 检查： ```bash python - <<'PY' import torch print(torch.__file__) PY ``` 正确路径应该类似： ```text /opt/z100l-open-stack/runtime/pytorch_runtime/torch/__init__.py ``` 如果仍然是旧机器路径，例如： ```text /home/muyi/z100l_nas/src/pytorch-z100l-gfx906/torch/__init__.py ``` 重新执行： ```bash bash scripts/relocate_bundle.sh source env/activate_z100l_open_stack.sh ``` 解释：这会重新修复 editable mapping。 ### 6.5 如果 `hy-smi` 不在 PATH 驱动安装后 `hy-smi` 可能没有加入全局 PATH。 先查找： ```bash sudo find /opt /usr -name hy-smi 2>/dev/null ``` 假设找到： ```text /opt/dtk-26.04/bin/hy-smi ``` 可以临时加入： ```bash export PATH=/opt/dtk-26.04/bin:$PATH ``` 也可以写入全局： ```bash echo 'export PATH=/opt/dtk-26.04/bin:$PATH' | sudo tee /etc/profile.d/hygon-dtk.sh ``` 解释：让以后登录 shell 自动找到 `hy-smi`。 ### 6.6 通用模型矩阵测试 包内带了通用模型矩阵脚本，可以先跑前 6 个模型： ```bash bash scripts/run_universal_matrix_subset.sh 6 ``` 解释：这会复用包内环境，按模型类别做小范围测试。 历史完整报告在： ```text reports/universal_model_matrix_20260524_044952/universal_model_matrix_operator_notes.md ``` 可以查看： ```bash sed -n '1,200p' reports/universal_model_matrix_20260524_044952/universal_model_matrix_operator_notes.md ``` ### 6.7 推荐排错顺序 ```mermaid flowchart TD A[模型启动失败] --> B{hy-smi 是否能看到卡} B -- 否 --> B1[检查驱动 / hymgr / hycu] B -- 是 --> C{hipcc 是否可用} C -- 否 --> C1[检查 /opt/dtk-26.04 和 PATH] C -- 是 --> D{torch.cuda.is_available 是否 True} D -- 否 --> D1[检查 LD_LIBRARY_PATH / libamdhip64 / libgalaxyhip] D -- 是 --> E{torch.__file__ 是否在包内 runtime} E -- 否 --> E1[重新运行 relocate_bundle.sh] E -- 是 --> F{模型是否能 local_files_only 加载} F -- 否 --> F1[检查 HF_HOME 和模型缓存] F -- 是 --> G[进入模型自身 dtype / processor / 算子问题] ``` ### 6.8 这套包的边界 这套包能保证： - 在同类 Ubuntu 22.04 + DTK 26.04 + 驱动正常的机器上复用当前 Python/PyTorch/HIP/Transformers 环境。 - 启动包内 Qwen2.5-0.5B-Instruct 做 CLI 推理。 - 启动一个最小 HTTP chat completions 服务。 - 继续扩展 Hugging Face 模型测试。 这套包不能保证： - 自动适配所有海光卡型号的驱动差异。 - 自动修复缺失或不兼容的 DTK 安装。 - 自动让所有 vLLM / SGLang / Triton kernel 都达到最优速度。 - 自动运行超大模型，因为那还取决于显存、TP、KV cache、attention kernel 和模型结构。 ### 6.9 一句话原则 先确认 `hy-smi`，再确认 `hipcc`，再确认 `torch.cuda.is_available()`，再跑最小 tensor，最后再加载 Transformers 模型。不要一上来就跑大模型，否则问题层级会混在一起。