pixmaate/gufo

来源：https://github.com/pixmaate/gufo

Gufo：Strix Halo 推理引擎

Gufo 是一个专为 AMD Strix Halo 硬件垂直构建并深度优化的本地推理引擎：即配备 Radeon 8060S（gfx1151）的 Ryzen AI MAX+ 395 系统，最高支持 128 GiB 统一内存。

欢迎贡献！

模型与基准测试

所有模型文档位于 docs/models：

以上为实测峰值负载；文本提示词处理（pp）采用自回归（AR）方式，生成（tg）则使用表中标注的推测解码模式。峰值数据包含重复性输出；聚合 tg 为各请求解码速率之和。Qwen27B 的单用户峰值采用短提示词的 C1 负载。音频测试不包含模型加载时间。每份模型指南均列出了所需文件和完整的基准测试配置。

设计理念

• 欢迎贡献！我们需要 Strix Halo 社区的帮助来持续改进 gufo！
• 我们希望把它打造成 Strix Halo 本地 AI 爱好者的一站式选择：文本、音频、图像和视频模型开箱即用。
• 专门针对 Strix Halo 128 GiB 硬件构建和优化。更小的内存配置同样可以运行，并为内存能容纳的模型保留速度优势。
• 只支持该硬件上能运行的、同尺寸下最优的模型：更少的维护代码，更专注的优化和测试工作。
• 优化时保持质量。每份模型质量报告都记录了独立的数值校验、执行一致性和未解决的差异。不要在不同模型之间复用内核，以限制代码变更的影响范围。
• 将并发请求、取消和对话缓存视为一等公民负载。
• 保持生产依赖精简，开发工具与生产环境分离。

快速开始

hf download unsloth/Qwen3.8-27B-GGUF \
  Qwen3.8-27B-UD-Q8_K_XL.gguf \
  --revision 4ca720788d1e01f1bff70c033e0d0028fd02e502 \
  --repo-type model \
  --local-dir models/Qwen3.8-27B-GGUF

hf download z-lab/Qwen3.8-27B-DFlash2-GGUF \
  Qwen3.8-27B-DFlash2-Q4_K_M.gguf \
  --revision 2d9571f8ce46e151f61c6499c99dee6079e1d610 \
  --repo-type model \
  --local-dir models/Qwen3.8-27B-DFlash2-GGUF

podman pull ghcr.io/gufo-org/toolboxes/gufo-runtime:latest

podman run --rm \
  --userns=keep-id:uid=1000,gid=1000 \
  --device /dev/kfd \
  --device /dev/dri \
  --group-add keep-groups \
  --ulimit memlock=-1 \
  -p 8080:8080 \
  -v ./models:/models:ro \
  ghcr.io/gufo-org/toolboxes/gufo-runtime:latest \
  gufo serve --host 0.0.0.0 --port 8080 llm \
  --model /models/Qwen3.8-27B-GGUF/Qwen3.8-27B-UD-Q8_K_XL.gguf \
  --speculative dflash2 \
  --dflash-model /models/Qwen3.8-27B-DFlash2-GGUF/Qwen3.8-27B-DFlash2-Q4_K_M.gguf

无 root 权限的 Podman 使用 --group-add keep-groups 时需要 crun。你的宿主机用户必须对 /dev/kfd 和 /dev/dri/renderD* 拥有读写权限，通常通过 render 和 video 用户组实现；更改组成员关系后请注销并重新登录。容器内名为 video/render 的组不会保留宿主机的附加用户组。如果 ROCm 报告找不到设备，请检查 id、ls -l /dev/kfd /dev/dri/renderD* 以及 podman info --format '{{.Host.OCIRuntime.Name}}'。参见 Podman 的无 root 用户组访问指南 (https://github.com/containers/podman/blob/main/troubleshooting.md#20-passed-in-devices-or-files-cant-be-accessed-in-rootless-container)。

在 Fedora 或其他启用 SELinux 的宿主机上，GPU 枚举可能成功，但 SELinux 会阻止映射 /dev/kfd，导致 ROCR 报出误导性的 “Memory critical” 错误。请检查宿主机审计日志：

sudo ausearch -m avc -ts recent | grep -E '/dev/kfd|hsa_device_t'

如果显示容器的 map 操作被拒绝，Podman 文档给出了以下修复方法：

sudo setsebool -P container_use_devices true

这将永久允许容器访问传入设备的设备标签；该设置会影响宿主机上的所有容器。启用前请确认该策略的适用范围。参见 Podman 的设备文档 (https://docs.podman.io/en/latest/markdown/podman-run.1.html#device-host-device-container-device-permissions) 和 SELinux 容器策略 (https://github.com/containers/container-selinux/blob/main/container.te)。

然后，在另一个终端中，通过 OpenAI 兼容 API 向它提问：

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
  "model": "Qwen3.8-27B-UD-Q8_K_XL",
  "messages": [{"role": "user", "content": "Say something"}]
}'

对于 Open WebUI、VS Code 和 OpenAI SDK 客户端，将 API 基础 URL 设置为 http://localhost:8080/v1。Chat Completions 支持文本、图像、工具和流式输出；Responses 支持文本和流式输出。参见 API 契约。

文本服务默认使用模型的原生上下文长度，持续生成直到遇到 EOS 或上下文写满。--context N 设置每个会话的上下文容量；--max-tokens N 设置默认响应长度上限，客户端可以覆盖该值。推理（reasoning）token 计入该响应长度上限。

从源码构建

支持的目标平台是 AMD Strix Halo（gfx1151）上的 Linux x86-64。CMake 为 Nix 和普通 Linux 构建维护同一套生产配置。测试、性能分析器、调优可执行文件和 Python 参考运行器不会随生产包安装。无需 build.sh 包装脚本。

Windows 11 x64 可针对 AMD 的 TheRock ROCm 原生构建；工具链、环境检查、构建脚本和启动器（start.cmd、tools\windows\start.ps1）参见 Windows；发行版附带预编译 zip 包。

使用 Nix

nix build

./result/bin/gufo diagnose
./result/bin/gufo serve llm --model /path/to/model.gguf

flake.lock 锁定了所有依赖版本。nix develop 会加入性能分析、模型下载和独立评测工具；这些不是运行时要求。可选的基准测试基线分别通过 nix shell .#ds4-reference、.#llama-cpp-reference 或 .#llama-cpp-mtp-reference 选择；参见基准测试。参见测试了解小型托管 CI 套件和本地质量检查方法。

不使用 Nix

安装 C++20 编译器、CMake 3.21+、Ninja、pkg-config 以及下列开发库。当前通过认证的工具链为 GCC 15.3 和 ROCm 7.2.3。注意力和音频卷积内核直接从 HIP 源码编译。Python、Triton/AOTriton、Composable Kernel 和 MIOpen 不是生产构建或运行时要求。

按照 AMD 的 Linux 说明 (https://rocm.docs.amd.com/projects/install-on-linux/en/latest/) 安装 ROCm。请安装上述库的开发包。ROCm 通常安装在 /opt/rocm 下。例如在 Debian/Ubuntu 上，普通的系统库安装方式如下：

sudo apt install build-essential cmake ninja-build pkg-config \
  libicu-dev libcurl4-openssl-dev libssl-dev libpng-dev libjpeg-dev ffmpeg

# 按 AMD 仓库发布的命名安装上表中的 ROCm 库。
sudo apt install hipblas-dev hipblaslt-dev rocblas-dev \
  hipcub-dev rocprim-dev rocwmma-dev

cmake --preset release -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build --preset release --parallel 4
./build/release/gufo diagnose
./build/release/gufo serve llm --model /path/to/model.gguf

如果缺少上述 ROCm 包，配置阶段会在 find_package(hipblas) 处失败。其他发行版的命名方式可能是 -devel 而非 -dev。对于非标准安装路径，请传入常规的 CMake 路径，例如 cmake --preset release -DCMAKE_PREFIX_PATH="/opt/rocm"。如果编译器发现机制选中了系统的 Clang，请同时传入 -DCMAKE_HIP_COMPILER=/opt/rocm/llvm/bin/clang++。使用 cmake --install build/release 安装 Gufo、其运行时数据和许可证声明。

GPU 驱动必须允许你的用户访问 /dev/kfd 和 /dev/dri；模型权重需要单独获取。两套构建方式使用相同的源码、编译器选项和安装规则。Nix 锁定完整工具链以保证可复现的对比测试；更换编译器或数学库需要重新运行受影响模型的质量检查。

许可证

Gufo 的原始代码采用 MIT 许可证。经过改编的代码和依赖保留其各自的声明，见 NOTICE、THIRD_PARTY_NOTICES.md 和 licenses/，随包安装在 share/licenses/gufo 下。模型权重不随包分发，仍适用其发布方的条款。

参考项目

最初的设计参考了以下开源项目：

• llama.cpp (https://github.com/ggml-org/llama.cpp)：紧凑的模型服务、GGUF 格式以及 CPU/GPU 正确性验证路径。
• LaurentZuijdwijk/llama.cpp (https://github.com/LaurentZuijdwijk/llama.cpp)、Nathanw1014/strix-halo-llamacpp (https://github.com/Nathanw1014/strix-halo-llamacpp) 和 gaetan-puleo/llama-cpp-strix-halo (https://github.com/gaetan-puleo/llama-cpp-strix-halo)：Strix Halo 优化的灵感来源。
• vLLM (https://github.com/vllm-project/vllm)：连续批处理和分页请求调度。
• hipEngine (https://github.com/shisa-ai/hipEngine)：无 torch 的 HIP 执行，以及原生推测解码周期的实现。
• ds4 (https://github.com/antirez/ds4)：DeepSeek V4 Flash、MoE 调度和 DSpark。
• audio.cpp (https://github.com/0xShug0/audio.cpp)：用于 tts 和 asr 任务的音频模型。