English: README_EN.md
在单张 AMD Strix Halo APU(gfx1151)上运行 177B MoE 模型的本地推理引擎, 目标模型为 Qwen3.8-Flash-Next(qwen4_exp 架构)及其同结构微调。
68 GiB 量化权重以 4-bit 量化存放在主机内存,GPU kernel 直读,不需要大显存; 整机 122 GiB 内存即可提供 256K 上下文。
性能实测
开发机器为 GMK EVO-X2(AMD Ryzen AI Max+ 395,Strix Halo / gfx1151), 122 GiB 内存:
| 指标 | 数值 |
|---|---|
| Prefill(128K 上下文) | 约 1200–1400 tok/s |
| Decode | 约 30–55 tok/s(视投机命中率) |
| 平均功耗 | 约 120 W |
| 瞬时最大功耗 | 约 130 W(爆发持续几秒后回落至 120 W 左右) |
特性
- 投机解码 chain:ngram 优先起草、MTP 兜底,逐轮回退;贪心逐位比对, 采样按目标分布重采样比对,输出分布与串行一致。默认生效,无需参数。 高度重复内容(代码注释、模板文本)实测显著加速。
- 独立 8-bit MTP 草稿权重 sidecar,接受率高于内置 4-bit 草稿头。
- 视觉:支持图像输入(OpenAI
image_url),KV 复用跨轮生效。 - OpenAI 兼容 API:流式、工具调用、
/v1/chat/completions。 - 256K 上下文,两级 prompt 缓存:消息边界的内存检查点(编辑重发秒回)
- KV 快照跨重启恢复。
- 模型转换工���:HF safetensors →
.hgn,量化无需校准数据, 可分发给自己的微调模型使用(见 CONVERT.md)。
要求
- Linux + ROCm(HIP 7.x),GPU 架构
gfx1151;或 Windows + AMD 显卡驱动 (GPU 需 BIOS 划分显存),见「Windows」一节 - 可用内存 ≥ 100 GiB(权重 68 GiB 锁页 + KV)
- 编译依赖:rocBLAS、hipBLASLt、rocPRIM;API 前端另需 libpng、libjpeg、libwebp（nlohmann/json 已随仓库提供）
快速开始
bash build.sh # 编译引擎 + API,输出在 build/
bash start_hgn.sh # hgn 权重:加载模型并启动服务(读取 service.conf)
bash start_gguf.sh # 或 GGUF 权重(Unsloth UD-Q4_K_XL,与 llama.cpp 同一份文件)
两个启动器都从 ./models 读取权重,缺文件时列出缺失项并退出;配置集中在
service.conf(hgn、GGUF 各一段)。GGUF 见 GGUF.md。
详见 QUICKSTART.md。
自有微调模型(HF safetensors,同架构)转换:
python3 tools/flashnext2hgn.py /path/to/hf-model --out ./models
详见 CONVERT.md。
Windows
Windows 版与 Linux 版功能一致(引擎 + OpenAI API + 多模态),移植记录与
实测见 PORTING-WINDOWS.md。编译在 Git Bash 中执行
(或双击 build_win.bat,仅编译期需要 Git):
bash build_win.sh # 引擎
bash build_win.sh api # OpenAI API 前端
bash build_win.sh launcher # 免脚本启动器 start_win.exe
日常运行双击 start_win.exe(原生 Win32,不需要 Git/PowerShell):拉起引擎
- API 双进程,输出实时显示并写入
logs\,Ctrl+C 或关窗停止。配置与 Linux 共用service.conf(换模型文件名、改上下文窗口都编辑它),环境变量可 临时覆盖。客户端连http://<主机>:8731/v1。
分发:build/ + start_win.exe + models/ 拷到任意 gfx1151 Windows
机器即用,无需安装 ROCm/TheRock;仅需 AMD 显卡驱动,并在 BIOS 为 GPU
划分足够显存(256K 上下文需 96 GiB)。
与 Linux 版的差异:
- 图片解码经 stb_image 支持 PNG/JPEG(WebP 未接)
- prefill chunk 默认 8192
- 冷加载为整权重读盘(分钟级,进度见控制台/日志)
- 启动器未开
GDEC_GEMM_WMMA与GDEC_GDN_FUSED(Linux 启动器已转正的 自写 WMMA GEMM 与 GDN 融合 kernel,合计约 8-10% PP,TheRock 下未验证—— 故 Windows 端 prefill 走 hipBLASLt + 旧 GDN 路径)
编译细节见 BUILD.md。
文档
- QUICKSTART.md — 编译、启动、配置
- BUILD.md — 编译环境细节与排错
- CONVERT.md — 模型转换工具
- MTP.md — 投机解码参数与对比方法
- NGRAM.md — ngram 验证���设计、收益与已知分歧
- HGN-FORMAT.md —
.hgn权重容器格式 - data/README.md — 数值回归基准(data/qsa-oracle)说明
- PORTING-WINDOWS.md — Windows 移植记录与实测
测试
bash build.sh test # kernel 单测,不加载模型,预期 ALL PASS
致谢
本项目的实现方式借鉴了 peonist-ai 的 halogen-flash-server;.hgn 权重容器格式即 halogen 的 checkpoint 容器格式(见 HGN-FORMAT.md)。感谢 halogen 作者的工作。
ngram 投机解码的起草思路另借鉴了开源项目 llama.cpp(MIT 许可证),声明详见 NGRAM.md 的「来源与声明」一节。
Comments