kyuz0/amd-strix-halo-vllm-toolboxes 源代码：https://github.com/kyuz0/amd-strix-halo-vllm-toolboxes

AMD Strix Halo (gfx1151) — vLLM 工具箱/容器

一个基于 Fedora 43 的 Docker/Podman 容器，兼容 Toolbx（可用作 Fedora 工具箱），用于在 AMD Ryzen AI Max “Strix Halo” (gfx1151) 上使用 vLLM 运行 LLM 推理。构建于 TheRock 夜间构建版的 ROCm 之上。

🚀 高性能集群支持（新功能！）

更新： 本工具箱现在附带 自定义构建的 ROCm/RCCL，为 Strix Halo (gfx1151) 启用了 原生 RDMA/RoCE v2 支持。这使得您可以通过低延迟互连（例如 Intel E810）连接两个节点，并运行 vLLM 的张量并行（TP=2），有效实现单个 256GB 统一内存 GPU 的效果。

👉 阅读完整的 RDMA 集群设置指南 了解硬件要求和配置说明。

📦 项目背景

本仓库是 Strix Halo AI 工具箱（https://strix-halo-toolboxes.com） 项目的一部分。访问网站可获取所有工具箱、教程和主机配置指南的概览。

❤️ 支持

这是一个业余时间维护的个人项目。如果您觉得这些工具箱和教程有用，可以 请我喝杯咖啡（https://buymeacoffee.com/dcapitella） 支持我的工作！☕

🙏 致谢

• Adrian (@Lafunamor (https://github.com/Lafunamor))：非常感谢他提供的所有帮助、PR 和测试，使得该项目稳定下来！
• Patrick Audley (paudley/ai-notes (https://github.com/paudley/ai-notes))：感谢他提供的 strix-halo 构建笔记。本工具箱依赖该研究（特别是 Triton 补丁和 aiter 编译策略）才能在 Strix Halo 上成功运行 vLLM 和 AITER Flash-Attention。

目录

• 已测试模型（基准测试）
• 1) Toolbx vs Docker/Podman
• 2) 快速入门 — Fedora Toolbx
• 3) 快速入门 — Ubuntu (Distrobox)
• 4) 测试 API
• 5) 使用 Web UI 进行聊天
• 6) 主机配置
• 7) 分布式集群（RDMA/RoCE）

已测试模型（基准测试）

关于吞吐量的说明： 这些基准测试测量的是高并发条件下的 峰值多用户吞吐量（Tokens/秒），即同时对多个序列进行批处理以饱和 Strix Halo 的内存带宽。如果您使用单个请求（并发数=1）进行测试，您的个人生成速度将低于这些最大硬件饱和数值。这些指标代表了系统在重负载下的总容量。

查看完整基准测试：https://kyuz0.github.io/amd-strix-halo-vllm-toolboxes/

1) Toolbx vs Docker/Podman

kyuz0/vllm-therock-gfx1151 镜像提供两个频道：

该镜像可同时用作：

• Fedora Toolbx（推荐用于开发）： Toolbx 共享您的 HOME 和用户，因此模型/配置文件存放在宿主机上。非常适合快速迭代，同时保持宿主机干净。
• Docker/Podman（推荐用于部署/性能）： 用于将 vLLM 作为服务运行（主机网络、IPC 调优等）。务必 挂载一个宿主机目录 用于模型权重，使其保留在容器外部。

2) 快速入门 — Fedora Toolbx

推荐： 使用附带的 refresh_toolbox.sh 脚本。它会拉取镜像并使用正确的参数创建工具箱：

``bash

交互式 — 提示您选择 latest（默认）或 dev

./refresh_toolbox.sh

或直接指定：

./refresh_toolbox.sh latest # 验证有效的构建 ./refresh_toolbox.sh dev # 前沿构建 ``

InfiniBand / RDMA 支持： 该脚本会自动检测是否存在快速 InfiniBand 链路（检查 /dev/infiniband）。如果发现，它会正确设置容器以暴露这些设备，从而启用高性能集群。

手动创建： 要手动创建一个暴露 GPU 并放宽 seccomp 的工具箱：

bash toolbox create vllm \ --image docker.io/kyuz0/vllm-therock-gfx1151:latest \ -- --device /dev/dri --device /dev/kfd \ --group-add video --group-add render --security-opt seccomp=unconfined

进入该工具箱：

bash toolbox enter vllm

模型存储： 默认情况下，模型会下载到 ~/.cache/huggingface。如果您正确创建了工具箱，该目录会与宿主机共享，因此下载内容会持久保存。

运行模型（最简单方式）

该工具箱包含一个名为 start-vllm 的 TUI 向导，其中包含预配置的模型并为您处理启动参数。这是上手的最简单方式。

bash start-vllm

缓存说明： vLLM 将编译后的内核写入 ~/.cache/vllm/。

3) 快速入门 — Ubuntu (Distrobox)

Ubuntu 的 toolbox 包仍然会破坏 GPU 访问，因此请改用 Distrobox：

bash distrobox create -n vllm \ --image docker.io/kyuz0/vllm-therock-gfx1151:latest \ --additional-flags "--device /dev/kfd --device /dev/dri --group-add video --group-add render --security-opt seccomp=unconfined" distrobox enter vllm

验证： 运行 rocm-smi 检查 GPU 状态。

运行模型（最简单方式）

该工具箱包含一个名为 start-vllm 的 TUI 向导，其中包含预配置的模型并为您处理启动参数。这是上手的最简单方式。

bash start-vllm

4) 测试 API

服务器启动后，访问 OpenAI 兼容的端点：

bash curl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"Hello! Test the performance."}]}'

您将收到一个 JSON 响应，其中包含 choices[0].message.content 回复。如果您不想指定模型名称，可以运行以下命令查询当前部署的模型：

bash MODEL=$(curl -s http://localhost:8000/v1/models | jq -r '.data[0].id') curl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d "{ \"model\": \"$MODEL\", \"messages\":[{\"role\":\"user\",\"content\":\"Hello! Test the performance.\"}] }"

5) 使用 Web UI 进行聊天

如果 vLLM 运行在远程服务器上，可以通过 SSH 端口转发暴露 8000 端口：

bash ssh -L 0.0.0.0:8000:localhost:8000 <remote-host>

然后，您可以像这样启动 HuggingFace ChatUI（在您的宿主机上）：

bash docker run -p 3000:3000 \ --add-host=host.docker.internal:host-gateway \ -e OPENAI_BASE_URL=http://host.docker.internal:8000/v1 \ -e OPENAI_API_KEY=dummy \ -v chat-ui-data:/data \ ghcr.io/huggingface/chat-ui-db

6) 主机配置

此配置应适用于任何 Strix Halo 设备。有关可用硬件的完整列表，请参见：Strix Halo 硬件数据库（https://strixhalo-homelab.d7.wtf/Hardware）

6.1 测试配置

6.2 内核参数（在 Fedora 42 上测试）

添加以下启动参数以启用统一内存，同时为操作系统保留至少 4 GiB（iGPU 最大 124 GiB）：

根据 Lars Urban (@urbanswelt) (https://github.com/urbanswelt) 的基准测试，有明确迹象表明设置 amd_iommu=off 比之前推荐的 iommu=pt 性能更好。关键结果：amd_iommu=off 比任何启用 IOMMU 的模式快 5-12%。详情参见 Issue #66 (https://github.com/kyuz0/amd-strix-halo-toolboxes/issues/66#issuecomment-4460612951)。

amd_iommu=off amdgpu.gttsize=126976 ttm.pages_limit=32505856

来源：https://www.reddit.com/r/LocalLLaMA/comments/1m9wcdc/comment/n5gf53d/?context=3&utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

应用更改：

``

编辑 /etc/default/grub，将参数添加到 GRUB_CMDLINE_LINUX

sudo grub2-mkconfig -o /boot/grub2/grub.cfg sudo reboot ``

7) 分布式集群（RDMA/RoCE）

本工具箱支持使用 InfiniBand 或 RoCE v2（例如 Intel E810）对多个 Strix Halo 节点进行高性能集群。这使得跨机器的 张量并行 成为可能，延迟极低（约 5μs）。

详细文档： RDMA 集群设置指南

主要特性：

• 自定义 RCCL 补丁： 使用自定义构建的 librccl.so 以支持 gfx1151 上的 RDMA。
• 简易设置： refresh_toolbox.sh 自动检测并暴露 RDMA 设备。
• 集群管理： 包含 start-vllm-cluster TUI 用于管理 Ray 和 vLLM。

8) Strix Halo 上的 AITER 支持状态

本工具箱支持在 Strix Halo (gfx1151) 上运行 AITER Flash Attention。通常情况下，如果启用 VLLM_ROCM_USE_AITER=1，vLLM 会在 RDNA APU 上崩溃，因为 AITER 尝试 JIT 编译 CDNA 特定的 MoE（混合专家）和 CustomOps 汇编指令，而这些指令缺乏 RDNA 硬件支持。

为了绕过此限制，scripts/patch_strix.py 应用了一些 APU 特定的防护措施（基于上述 ai-notes 的工作）：

• 补丁 2（vllm/_aiter_ops.py）： 拦截 MoE 门控（is_fused_moe_enabled()），强制在 gfx1x 架构上禁用 AITER MoE 和 Linear FP8。
• 补丁 3.5（vllm/model_executor/layers/fused_moe/oracle/unquantized.py）： 阻止 VLLM_ROCM_USE_AITER_MOE 环境变量强制进行 JIT 编译覆盖。
• 补丁 5（vllm/platforms/rocm.py）： 在 gfx1x 上绕过 RMSNorm 自定义操作注册，以防止模型初始化期间 CUDA Graph 捕获崩溃。

由于这些补丁，当启动器选择 ROCm 注意力时，vLLM 会将注意力路由到 AITER（使用通过 scripts/patch_aiter_headers.py 注入的 ds_swizzle RDNA 头文件回退），同时安全地回退到 Triton 处理 MoE 矩阵，以及 Torch/Triton 处理 RMSNorm。