Strix Halo 推理栈 loonylabs/strix-halo-inference

strix-halo-inference

tests
license
GPU
RAM
backend
python

一台经过实测的 Strix Halo 推理机器：一个投入生产的本地编码代理——以及在同一内存管理之下运行的文本到图像、语音和视频。 一种配置——Ryzen AI Max+ 395（gfx1151），128 GB 共享内存——这里的每一个数字都是在它上面测得的，并附有日期和方法。

bash setup/preflight.sh # is this repo for your machine?
bash setup/install.sh # once — writes ~/.config/llm-stack.env bash setup/switch-model.sh halogen-qwen38flash # (alias: halogen) serve the high-speed Halogen container or: bash setup/switch-model.sh halogen-qwen38 # serve 27B via Halogen or: bash setup/switch-model.sh qwen38 # serve GGUF via llama-server bash tests/run.sh # the gate (1529 tests, ~20 s, no GPU)

你拉取的名称就是你服务的名称。没有 pull 命令，因为一个模型就是它在 setup/env/ 中的配置文件——而该配置文件承载了权重来自何处、一个上下文 token 在 KV 中的开销，以及其命令行上每个标志背后的测量依据。

这适合你的机器吗？

bash setup/preflight.sh 在五秒内给出答案，无需 root，不做任何更改：

| RAM | 按原样适配的配置文件 |
| 128 GB | 7 个中的 7 个——这里所有测量所基于的配置 |
| 64 GB | 7 个中的 3 个——batch、gemma26、gemma31 |
| 32 GB | 无：17.6 权重 + 6.0 缓冲下限 + 12 主机已经超了 |

没有任何东西被缩减以改变这一点——一个被缩减的数字只是猜测。有意不做一个通用技术栈；preflight.sh 会在你花掉一个下午之前告诉你所处的位置。

引擎：Strix Halo 上的开箱即用性能

无需与 ROCm 编译标志或手动容器挂载作斗争，该技术栈为此芯片上最快的推理引擎提供了开箱即用的配置：

* Halogen Flash Server（setup/halogen/）：一个无 root 容器后端，运行 Qwen 3.8 Flash-Next 并采用 MTP 推测解码——在此投入生产用于日常代理工作，自 26.09.2026 起为 0.14.0。于 24.09.2026 在 0.13.8 上测得：一个冷启动的 186k token 提示词用时 192 秒（约 970 tok/s），从 2k 到 193k 上下文的长回答为 31-34 tok/s；0.14.0 的新草稿头从 35.4-35.9 提升到 39.0-40.3 tok/s（在 2k-32k 下），这是在同一时段内与 0.13.8 对比测得的（报告）。它的提示缓存存放在 RAM 以及 NVMe 中：一段被逐出的深度对话，或在重启后仍保留的对话，可在 2-3 秒内恢复，而不是约 3 分钟（报告）。它的引擎是闭源的，因此容器以无对外路由运行，并且其端口仅监听回环地址（为何以及如何测试）。
* llama.cpp（setup/scripts/build-llama.sh）：上游 master 加上一小组精选的硬件补丁（setup/patches/），以支持广泛的 GGUF 模型生态。

在它们之间切换只需一条命令：

bash setup/switch-model.sh halogen-qwen38flash # 切换到 Halogen Flash Server（或：halogen） bash setup/switch-model.sh halogen-qwen38 # 切换到 Halogen Server（27B） bash setup/switch-model.sh qwen38 # 切换回 llama.cpp

网关完全屏蔽你的客户端：更换底层引擎无需在你的编辑器或测试框架中做任何配置更改。

网关：通用接口与即时轮次

LLM 网关（setup/gateway/）位于你的客户端与服务引擎之间：

* 双方言转换： 在进程内同时支持 Anthropic（/v1/messages）和 OpenAI （/v1/chat/completions）。Claude Code、DeepSeek Harness、Cursor 以及脚本可与正在运行的任一后端通信，而无需单独的桥接守护进程。
* 真正的提示与前缀缓存： 智能体提示通常携带 20k–40k token 的系统指令和工具定义。在 llama.cpp 上，网关跟踪前缀哈希并保存 KV 状态，将约 120 秒的冷预填充变为 1.3 秒的后续轮次（>90% 缓存复用）。在 Halogen 上，引擎自行缓存，网关会透传 Claude Code 的缓存标记，因此即使其自动模式安全检查也能从其转录结束处恢复：每次检查 32.5 秒 → 18.6 秒，判定结果不变（24.09.2026，报告）。
* 边缘稳定流式传输： 针对工具调用的增量逐 token 参数流式传输以及 10 秒 SSE keepalive 心跳，可防止 Cloudflare Tunnel 和代理在长生成过程中掉线（500 / 524）。
* 稳定的模型别名： 在你的客户端中使用 local-low、local 或 local-medium。
它们会解析为当前活动引擎的等效模式，因此切换模型永远不会破坏你的客户端配置。
* 专用 CPU 视觉 Sidecar： 在主 GPU 模型之外暴露 qwen3-vl-4b 和 vision。通过 llama-vision.service 运行在 8 个专用 Zen 5 CPU 核心（CCD1：核心 8–15）上，并带有独立的准入闸门（VISION_GATE），以保护 Halogen GPU 解码免受内存总线争用影响。自动启动于在闲置 10 分钟后停止（VISION_IDLE_TIMEOUT=600），以回收 RAM 供 Linux 页缓存使用。与 Unity Asset Inventory、DeepSeek Harness 和 OpenAI 多模态客户端完全兼容。

内存权威：绝不冻结机器

在像 Strix Halo 这样的统一内存架构上，没有独立的 VRAM。
GPU 通过 GTT 分配主机 RAM，而该分配是固定的。
超出可用内存的工作负载不会换出，也不会被 OOM 杀死：它会硬冻结整台机器，导致所有进程宕机，且不写入内核日志。

setup/lib/budget.py 在启动前会权衡每个配置文件，如果放不下就会主动拒绝：

REFUSING TO START qwen38: it needs about 70.1 GiB and it does not fit.
the host has 44.2 GiB available, 12 must stay free

出于同样的原因，绝不要手动启动第二个模型——或媒体工作负载：
python3 bench/sideserver.py 是唯一安全的方式，它会停止生产、
计量内存上限，然后再把生产恢复。

不只是语言模型：多模态租户

自 2026 年 9 月 1 日起，同一台机器在同一内存权威下渲染图像、语音和视频。
在本机上测量，每项 n=3，机器闲置，每个输出均由机器评判：

| 工作负载 | 内容 | 成本 | 许可证 |
| flux-schnell | 文本到图像，1024² | 56 秒 / 图像 | Apache 2.0 |
| sdxl | 文本到图像，1024² | 112 秒 / 图像 | OpenRAIL++ |
| qwen-image | 文本到图像，顶级质量档 | 409 秒 / 图像 | Apache 2.0 |
| qwen3-tts | 文本到语音，包含德语，Vulkan | 2.65× 实时 | Apache 2.0 |
| chatterbox | 文本到语音，声音克隆，23 种语言 | 0.29× 实时（CPU） | MIT |
| wan21-t2v | 文本到视频，480p | 约 9 分钟 / 2 秒片段 | Apache 2.0 |
| wan22-ti2v | 文本到视频，5B——更快且已标记 | 288 秒 / 片段，见其配置文件 | Apache 2.0 |

每个工作负载都在 setup/workloads/ 中声明其测得的内存占用，并由 budget.py 守护。基础安装保持无 torch（约 20 秒的测试门禁证明了这一点）；torch 工作负载被限制在 media/ 之后。

为什么不用通用运行器（比如 ollama）？

通用运行器能快速让端点跑起来，但它们是为标准独立 GPU 或通用 CPU 回退而构建的。在像 Strix Halo 这样的统一内存 APU 上，这会留下关键缺口：

| 能力 | 通用运行器（ollama 等） | 本技术栈 |
| 芯片目标 | 通用 CPU / CUDA | 为 Strix Halo gfx1151（128 GB UMA）量身定制并实测 |
| 引擎选择 | 单一内部运行时 | 每项任务使用最快引擎：Halogen（MTP）或打过补丁的 llama.cpp |
| 多方言网关 | 仅 OpenAI | 进程内 OpenAI ↔ Anthropic 转换（Claude Code 与 DSH） |
| 前缀与状态缓存 | 仅每次运行的内存内缓存 | 跨重启持久化，磁盘重载，即时后续轮次 |
| 流式稳定性 | 缓冲的工具负载 | 增量参数流式传输与 SSE 心跳，以应对代理超时 |
| 内存安全 | 系统 OOM（会硬冻结 Strix Halo） | 跨 LLM、Diffusion、TTS 与 Video 的严格 GTT 预算（budget.py） |

我们测量，而非声称

本仓库中的任何内容都不基于估算或营销宣传：

* 每个标志都经过测量： 速度、上下文窗口和 KV 成本都在 profile 注释中直接附有测量日期和方法。
* 将缺陷作为可测试数据： 静默硬件损坏（例如 //// 退化）和上游 bug 都作为数据记录在 setup/defects.json 中。python3 setup/lib/defects.py 会验证你正在运行的构建是否受影响。
* 严格的测试门禁： bash tests/run.sh 在约 20 秒内运行 1529 个测试，无需 GPU，在触及生产环境之前验证解析器完整性、方言转换、预算计算和防护栏。

从哪里开始

| 如果你想…… | 去这里 |
| 了解这个仓库是否适合你的机器 | bash setup/preflight.sh — 先运行它 |
| 查看有哪些变化，以及它是针对哪些组件版本测量的 | CHANGELOG.md |
| 从零开始设置机器 — 从 BIOS 到第一个 token | docs/setup/，共六章 |
| 运行它 — 服务、启动、四个上限 | setup/README.md |
| 将 Claude Code 或 OpenAI agent 指向它 — 你的或别人的 | docs/CONSUMERS.md，以及用 bash setup/consumer-info.sh 获取相关值 |
| 决定采用哪个模型，以及为什么当前模型可用于生产 | docs/MODELS.md |
| 在同一台机器上生成图像、语音或视频 | setup/workloads/ — profile 中带有每个测量数值 — 以及 setup/README.md 的 workload-registry 部分 |
| 验证正在运行的机器 — 门禁、实时通道、冒烟测试 | tests/README.md |
| 查看原始测量数据 | docs/measurements/ 和 bench/reports/ |
| 重复或扩展它们 | bench/ |
| 了解哪些内容受保护 | docs/SECURITY.md — 模型。SECURITY.md — 发现的问题提交到哪里 |
| 修改某些内容而不破坏它 | tests/，以及 CONTRIBUTING.md |
| 报告它在你的机器上的表现 | 提交 issue — 这是本仓库唯一无法自行测量的东西 |