loonylabs-dev/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 推测解码——在这里投入生产用于日常智能体工作。2026 年 9 月 24 日在 0.13.8 上实测：一个 186k token 的冷提示词在 192 秒内完成（约 970 tok/s），从 2k 到 193k 上下文，长回答速度为 31-34 tok/s。它的提示词缓存存在于 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 保活心跳，可防止 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 成本都带有
它们的日期和测量方法直接放在配置文件中的旁边
注释。
* 将缺陷作为可测试数据： 静默硬件损坏（例如 ////
退化）和上游 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/ — 这些配置文件包含所有测量数值 — 以及 setup/README.md 的工作负载注册表部分 |
| 验证正在运行的机器 — 门禁、实时通道、冒烟测试 | tests/README.md |
| 查看原始测量数据 | docs/measurements/ 和 bench/reports/ |
| 重复或扩展它们 | bench/ |
| 了解哪些内容受保护 | docs/SECURITY.md — 模型。SECURITY.md — 发现的问题应提交到哪里 |
| 修改某些内容而不破坏它 | tests/，以及 CONTRIBUTING.md |
| 报告它在你的机器上的表现 | 一个 issue — 这是这个仓库唯一无法自行测量的东西 |