专为 Intel Mac 与 AMD 独立显卡组合设计的本地 LLM 推理工具，通过针对性补丁解决 Metal 内核兼容性问题，提供与 Ollama 和 OpenAI 兼容的 HTTP API 接口。

QuenchForge：为 Intel Mac + AMD GPU 打造的本地大模型推理解决方案\n\n## 问题背景：被忽视的硬件组合\n\n在 AI 推理工具的生态中，Apple Silicon Mac（M1/M2/M3/M4）因其统一的内存架构和出色的能效比获得了广泛关注，NVIDIA GPU 凭借 CUDA 生态统治了服务器端市场。然而，夹在两者之间的用户群体——Intel Mac 搭配 AMD 独立显卡——却长期处于被忽视的状态。\n\n这类用户面临的核心问题是：\n\n1. Ollama 的 GPU 支持缺失：在 2019 Mac Pro 搭配 AMD Radeon Pro Vega II 的配置上，Ollama 无法调用 GPU 加速， silently 回退到 CPU 推理，性能损失巨大。相关 issue（ollama/ollama#1016）自 2023 年提出至今未解决。\n\n2. llama.cpp 的 Metal 内核缺陷：即使手动编译 llama.cpp 并启用 Metal 支持，非 Apple Silicon 的 AMD GPU 也会遇到 simdgroup-reduction 和 bfloat 内核的编译错误，导致采样器输出无意义的乱码 token。\n\nQuenchForge 项目正是为解决这一特定硬件组合的痛点而生。\n\n## 技术方案：精准的补丁策略\n\nQuenchForge 的核心技术贡献并非重写整个推理引擎，而是提供了一个精心设计的补丁层，在保持与上游 llama.cpp 兼容的同时，修复 AMD GPU 在 Intel Mac 上的兼容性问题。\n\n### 补丁机制\n\n项目通过 scripts/apply-patches.sh 在构建时向 llama.cpp 注入运行时门控逻辑：\n\n- simdgroup-reduction 内核：仅在 Apple Silicon 架构上启用，避免 AMD GPU 上的编译错误\n- bfloat 数据类型支持：同样通过架构检测进行条件编译\n- Metal 设备枚举：确保 AMD GPU 能被正确识别和初始化\n\n这种"运行时门控"（runtime-gated）的设计确保了补丁不会影响 Apple Silicon 用户的体验，同时让 Intel Mac + AMD GPU 用户获得可用的 GPU 加速。\n\n### 验证结果\n\n根据项目文档，该补丁已在 Mac Pro 2019 + Radeon Pro Vega II（32GB HBM2）配置上进行端到端验证：\n\n- 模型：llama3.2:3b-Q4_K_M\n- Prompt 处理速度：72.6 tokens/秒\n- 生成速度：4.1 tokens/秒\n- 输出质量：连贯、可用\n\n虽然生成速度相比 Apple Silicon 或 NVIDIA GPU 仍有差距，但相比 CPU 推理已提升数倍，且输出质量稳定可靠。\n\n## 系统架构与组件\n\nQuenchForge 采用 supervisor-worker 架构，主要包含以下组件：\n\n### 核心服务（quenchforge serve）\n\n作为系统的核心进程，负责：\n\n- 检测并管理一个或多个 llama-server 子进程\n- 将子进程绑定到检测到的 AMD GPU\n- 提供 Ollama 兼容的 HTTP 网关（127.0.0.1:11434）\n- 同时支持 OpenAI 风格的 API 接口\n\n这种设计使得任何已支持 Ollama 或 OpenAI API 的客户端都可以无缝迁移到 QuenchForge，无需修改代码。\n\n### 诊断工具（quenchforge doctor）\n\n提供硬件画像和 Metal 日志捕获功能，格式化输出便于一键粘贴到 bug 报告。对于需要社区支持的新硬件组合，这是获取诊断信息的标准工具。\n\n### 迁移助手（quenchforge migrate-from-ollama）\n\n通过符号链接将 ~/.ollama/models/ 中的现有 GGUF 模型导入 QuenchForge 缓存，避免用户重复下载数 GB 的模型文件。\n\n### 预检脚本（quenchforge-preflight）\n\n一键 curl 脚本，在安装前检查硬件兼容性，避免用户在不受支持的配置上浪费时间。\n\n### 基准测试（quenchforge bench）\n\n首次启动时运行微基准测试，自动确定适合当前 VRAM 容量的 --n-gpu-layers 参数，实现开箱即用的体验。\n\n## 硬件支持矩阵\n\nQuenchForge 对不同硬件组合的支持程度如下：\n\n| 配置 | 支持级别 | 说明 |\n|------|----------|------|\n| Intel Mac + AMD Vega II / Vega II Duo | 主要目标 | 项目存在的核心原因 |\n| Intel Mac + AMD W6800X / W6900X | 主要目标 | Apple 官方支持的 MPX 模块 |\n| Intel Mac + AMD RDNA1/RDNA2 消费级 | 支持 | 相同补丁表面，较小显存 |\n| Apple Silicon (M1/M2/M3/M4/M5) | 支持（无降级） | 补丁运行时门控，等效于原生 llama.cpp |\n| Intel Mac + Intel iGPU | 支持（CPU 级） | Metal 可用但显存极小，自动回退 CPU |\n| Linux / Windows | 超出范围 | 使用原生 Ollama + CUDA/ROCm/DirectML |\n| Hackintosh + AMD | 社区尽力 | 标记为非正版，无 SLA 承诺 |\n\n这种清晰的支持边界声明避免了用户期望管理问题，也明确了项目的专注领域。\n\n## 隐私与遥测策略\n\nQuenchForge 在隐私方面采取了用户友好的设计：\n\n本地网络访问提示：首次运行时，macOS Sonoma+ 会弹出 TCC 提示，询问是否允许 QuenchForge 发现本地网络设备。这是为了 mDNS/Bonjour 服务发现（_quenchforge._tcp.local.）。允许后，局域网内的 cerid-ai 等客户端可以自动发现服务；如仅需本地回环访问，可选择拒绝。\n\n遥测同意机制：首次启动时显示单屏同意流程。错误报告（Sentry）和匿名基准测试仪表板（bench.quenchforge.dev）默认关闭，需用户明确 opt-in 后才启用。即使启用，也仅发送硬件画像、tokens/秒和延迟数据。\n\nGatekeeper 兼容性：二进制文件经过签名和公证，符合 macOS 安全要求。首次运行时出现的"从互联网下载"提示是正常行为，Gatekeeper 会在线验证公证状态一次并记住结果。\n\n## 项目背景与治理\n\nQuenchForge 由 Cerid AI 赞助开发，但采用 Apache 2.0 许可证开源，遵循社区友好的治理模式。项目的诞生源于上游项目 cerid-ai 的实际需求：需要在 2019 Mac Pro + Radeon Pro Vega II 上获得可用的推理性能，同时兼容 Apple Silicon 硬件。\n\n由于当时没有其他维护中的工具能填补这一空白，Cerid AI 选择将补丁和调优工作开源，让所有 Intel Mac + AMD GPU 用户都能受益，而不必依赖单一供应商。\n\n项目接受硬件画像贡献，特别是对于项目团队未拥有的 GPU 型号。用户可通过提交包含 quenchforge doctor 输出的 issue 来完善支持矩阵。\n\n## 安装与使用\n\n当前阶段（v0.0 pre-release），用户需要从源码构建：\n\nbash\ngit clone --recursive https://github.com/Cerid-AI/quenchforge\ncd quenchforge\n\n# 应用补丁并构建 llama-server\nbash scripts/apply-patches.sh\nbash scripts/build-llama.sh\n\n# 构建 supervisor 和 CLI\ngo build -o /usr/local/bin/quenchforge ./cmd/quenchforge\ngo build -o /usr/local/bin/quenchforge-preflight ./cmd/quenchforge-preflight\n\n# 验证\nquenchforge-preflight # 应输出 status=ok\nquenchforge doctor # 硬件画像\nquenchforge serve # 启动服务\n\n\nHomebrew 安装（brew install cerid-ai/homebrew-tap/quenchforge）正在等待 Apple Developer ID 配置完成后提供签名和公证的 bottles。\n\n## 价值与意义\n\nQuenchForge 的价值不仅在于解决了一个具体的技术问题，更在于它体现了开源社区对边缘用户群体的关注。在 AI 基础设施领域，资源往往集中在主流平台（NVIDIA GPU、Apple Silicon），而像 Intel Mac + AMD GPU 这样的"夹缝配置"容易被忽视。\n\n通过精准的问题定位和最小侵入性的补丁策略，QuenchForge 证明了：即使不是重写整个系统，针对性的修复也能为特定用户群体带来巨大价值。对于仍在使用 Intel Mac Pro 搭配 AMD 专业显卡的工作站用户来说，QuenchForge 让他们的硬件重新获得了运行本地大模型的能力，延长了设备的使用寿命，也降低了进入本地 AI 推理领域的门槛。

QuenchForge：为 Intel Mac + AMD GPU 打造的本地大模型推理解决方案\n\n问题背景：被忽视的硬件组合\n\n在 AI 推理工具的生态中，Apple Silicon Mac（M1/M2/M3/M4）因其统一的内存架构和出色的能效比获得了广泛关注，NVIDIA GPU 凭借 CUDA 生态统治了服务器端市场。然而，夹在两者之间的用户群体——Intel Mac 搭配 AMD 独立显卡——却长期处于被忽视的状态。\n\n这类用户面临的核心问题是：\n\n1. Ollama 的 GPU 支持缺失：在 2019 Mac Pro 搭配 AMD Radeon Pro Vega II 的配置上，Ollama 无法调用 GPU 加速， silently 回退到 CPU 推理，性能损失巨大。相关 issue（ollama/ollama#1016）自 2023 年提出至今未解决。\n\n2. llama.cpp 的 Metal 内核缺陷：即使手动编译 llama.cpp 并启用 Metal 支持，非 Apple Silicon 的 AMD GPU 也会遇到 simdgroup-reduction 和 bfloat 内核的编译错误，导致采样器输出无意义的乱码 token。\n\nQuenchForge 项目正是为解决这一特定硬件组合的痛点而生。\n\n技术方案：精准的补丁策略\n\nQuenchForge 的核心技术贡献并非重写整个推理引擎，而是提供了一个精心设计的补丁层，在保持与上游 llama.cpp 兼容的同时，修复 AMD GPU 在 Intel Mac 上的兼容性问题。\n\n补丁机制\n\n项目通过 scripts/apply-patches.sh 在构建时向 llama.cpp 注入运行时门控逻辑：\n\n- simdgroup-reduction 内核：仅在 Apple Silicon 架构上启用，避免 AMD GPU 上的编译错误\n- bfloat 数据类型支持：同样通过架构检测进行条件编译\n- Metal 设备枚举：确保 AMD GPU 能被正确识别和初始化\n\n这种"运行时门控"（runtime-gated）的设计确保了补丁不会影响 Apple Silicon 用户的体验，同时让 Intel Mac + AMD GPU 用户获得可用的 GPU 加速。\n\n验证结果\n\n根据项目文档，该补丁已在 Mac Pro 2019 + Radeon Pro Vega II（32GB HBM2）配置上进行端到端验证：\n\n- 模型：llama3.2:3b-Q4_K_M\n- Prompt 处理速度：72.6 tokens/秒\n- 生成速度：4.1 tokens/秒\n- 输出质量：连贯、可用\n\n虽然生成速度相比 Apple Silicon 或 NVIDIA GPU 仍有差距，但相比 CPU 推理已提升数倍，且输出质量稳定可靠。\n\n系统架构与组件\n\nQuenchForge 采用 supervisor-worker 架构，主要包含以下组件：\n\n核心服务（quenchforge serve）\n\n作为系统的核心进程，负责：\n\n- 检测并管理一个或多个 llama-server 子进程\n- 将子进程绑定到检测到的 AMD GPU\n- 提供 Ollama 兼容的 HTTP 网关（127.0.0.1:11434）\n- 同时支持 OpenAI 风格的 API 接口\n\n这种设计使得任何已支持 Ollama 或 OpenAI API 的客户端都可以无缝迁移到 QuenchForge，无需修改代码。\n\n诊断工具（quenchforge doctor）\n\n提供硬件画像和 Metal 日志捕获功能，格式化输出便于一键粘贴到 bug 报告。对于需要社区支持的新硬件组合，这是获取诊断信息的标准工具。\n\n迁移助手（quenchforge migrate-from-ollama）\n\n通过符号链接将 ~/.ollama/models/ 中的现有 GGUF 模型导入 QuenchForge 缓存，避免用户重复下载数 GB 的模型文件。\n\n预检脚本（quenchforge-preflight）\n\n一键 curl 脚本，在安装前检查硬件兼容性，避免用户在不受支持的配置上浪费时间。\n\n基准测试（quenchforge bench）\n\n首次启动时运行微基准测试，自动确定适合当前 VRAM 容量的 --n-gpu-layers 参数，实现开箱即用的体验。\n\n硬件支持矩阵\n\nQuenchForge 对不同硬件组合的支持程度如下：\n\n| 配置 | 支持级别 | 说明 |\n|------|----------|------|\n| Intel Mac + AMD Vega II / Vega II Duo | 主要目标 | 项目存在的核心原因 |\n| Intel Mac + AMD W6800X / W6900X | 主要目标 | Apple 官方支持的 MPX 模块 |\n| Intel Mac + AMD RDNA1/RDNA2 消费级 | 支持 | 相同补丁表面，较小显存 |\n| Apple Silicon (M1/M2/M3/M4/M5) | 支持（无降级） | 补丁运行时门控，等效于原生 llama.cpp |\n| Intel Mac + Intel iGPU | 支持（CPU 级） | Metal 可用但显存极小，自动回退 CPU |\n| Linux / Windows | 超出范围 | 使用原生 Ollama + CUDA/ROCm/DirectML |\n| Hackintosh + AMD | 社区尽力 | 标记为非正版，无 SLA 承诺 |\n\n这种清晰的支持边界声明避免了用户期望管理问题，也明确了项目的专注领域。\n\n隐私与遥测策略\n\nQuenchForge 在隐私方面采取了用户友好的设计：\n\n本地网络访问提示：首次运行时，macOS Sonoma+ 会弹出 TCC 提示，询问是否允许 QuenchForge 发现本地网络设备。这是为了 mDNS/Bonjour 服务发现（_quenchforge._tcp.local.）。允许后，局域网内的 cerid-ai 等客户端可以自动发现服务；如仅需本地回环访问，可选择拒绝。\n\n遥测同意机制：首次启动时显示单屏同意流程。错误报告（Sentry）和匿名基准测试仪表板（bench.quenchforge.dev）默认关闭，需用户明确 opt-in 后才启用。即使启用，也仅发送硬件画像、tokens/秒和延迟数据。\n\nGatekeeper 兼容性：二进制文件经过签名和公证，符合 macOS 安全要求。首次运行时出现的"从互联网下载"提示是正常行为，Gatekeeper 会在线验证公证状态一次并记住结果。\n\n项目背景与治理\n\nQuenchForge 由 Cerid AI 赞助开发，但采用 Apache 2.0 许可证开源，遵循社区友好的治理模式。项目的诞生源于上游项目 cerid-ai 的实际需求：需要在 2019 Mac Pro + Radeon Pro Vega II 上获得可用的推理性能，同时兼容 Apple Silicon 硬件。\n\n由于当时没有其他维护中的工具能填补这一空白，Cerid AI 选择将补丁和调优工作开源，让所有 Intel Mac + AMD GPU 用户都能受益，而不必依赖单一供应商。\n\n项目接受硬件画像贡献，特别是对于项目团队未拥有的 GPU 型号。用户可通过提交包含 quenchforge doctor 输出的 issue 来完善支持矩阵。\n\n安装与使用\n\n当前阶段（v0.0 pre-release），用户需要从源码构建：\n\nbash\ngit clone --recursive https://github.com/Cerid-AI/quenchforge\ncd quenchforge\n\n应用补丁并构建 llama-server\nbash scripts/apply-patches.sh\nbash scripts/build-llama.sh\n\n构建 supervisor 和 CLI\ngo build -o /usr/local/bin/quenchforge ./cmd/quenchforge\ngo build -o /usr/local/bin/quenchforge-preflight ./cmd/quenchforge-preflight\n\n验证\nquenchforge-preflight 应输出 status=ok\nquenchforge doctor 硬件画像\nquenchforge serve 启动服务\n\n\nHomebrew 安装（brew install cerid-ai/homebrew-tap/quenchforge）正在等待 Apple Developer ID 配置完成后提供签名和公证的 bottles。\n\n价值与意义\n\nQuenchForge 的价值不仅在于解决了一个具体的技术问题，更在于它体现了开源社区对边缘用户群体的关注。在 AI 基础设施领域，资源往往集中在主流平台（NVIDIA GPU、Apple Silicon），而像 Intel Mac + AMD GPU 这样的"夹缝配置"容易被忽视。\n\n通过精准的问题定位和最小侵入性的补丁策略，QuenchForge 证明了：即使不是重写整个系统，针对性的修复也能为特定用户群体带来巨大价值。对于仍在使用 Intel Mac Pro 搭配 AMD 专业显卡的工作站用户来说，QuenchForge 让他们的硬件重新获得了运行本地大模型的能力，延长了设备的使用寿命，也降低了进入本地 AI 推理领域的门槛。