如何在 macOS 上用 llama.cpp 或 MLX 搭建本地 OpenAI 兼容 LLM 服务器并接入 Hermes Agent

如何在 macOS 上用 llama.cpp 或 MLX 搭建本地 OpenAI 兼容 LLM 服务器并接入 Hermes Agent【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent在 macOS 上运行 Hermes Agent 时如果你想让模型完全跑在本地——没有 API key、没有按 token 计费、对话不出机器——就需要先手动搭一个 OpenAI 兼容的 LLM 服务器再让 Hermes 把它当成一个自定义端点接入。这篇文章覆盖两条后端路线llama.cppGGUF 格式brew install即可用首 token 延迟最低和 MLX via omlxMLX safetensors 格式Metal 原生优化token 生成速度最快。两条路线最终都暴露 OpenAI 兼容的/v1/chat/completions接口接法完全一样。适用前提来自 Run Local LLMs on Mac面向 Apple Silicon 机型M1 及以后。Intel Mac 可以用 llama.cpp但没有 GPU 加速性能显著变慢。Hermes 要求模型上下文窗口至少64,000 tokens64K本地服务器必须显式设置上下文大小否则 Hermes 会在启动时拒绝该模型。先按内存预算选模型和后端文档给出的内存经验公式是模型体积 KV cache。以 9B 的 Q4 模型为例模型本身约 5 GB128K 上下文下 Q4 量化的 KV cache 再加约 4–5 GB如果 KV cache 用默认 f16会膨胀到约 16 GB。llama.cpp 的量化 KV cache 参数就是内存紧张时的关键手段。文档推荐起步模型是Qwen3.5-9B量化的版本可以放进 8 GB 以上统一内存变体磁盘占用内存需求128K 上下文后端Qwen3.5-9B-Q4_K_M (GGUF)5.3 GB约 10 GB量化 KV cachellama.cppQwen3.5-9B-mlx-lm-mxfp4 (MLX)约 5 GB约 12 GBomlx更大的模型27B、35B需要 32 GB 统一内存9B 是 8–16 GB 机型的甜点。两个后端怎么选文档给出的对照表使用场景推荐交互式聊天、低延迟工具llama.cpp长文生成、批量处理MLX (omlx)内存受限8–16 GBllama.cpp量化 KV cache同时服务多个模型omlx内置多模型支持最大兼容性Linux 也可llama.cpp文档在 Apple M5 Max128 GB 统一内存上对同一模型Qwen3.5-9B做了实测llama.cppQ4_K_MTTFT 平均 67 msMLXmxfp4289 mstoken 生成速度 llama.cpp 70 tok/sMLX 96 tok/s512 token 总耗时 7.3s vs 5.5s。也就是说 llama.cpp 赢在首 token 延迟MLX 赢在生成吞吐。如果用的是 Hermes 桌面应用还有一条一键路径Settings → Providers → Local Models点Install runtime让 Hermes 下载并托管 llama.cpp然后从模型目录选模型 Download 再点UseHermes 会自动处理上下文大小和显存放置。这条路径的详细行为见 Local Models。本文只讲手动搭建。路径 Allama.cpp命令行主路径安装与模型下载brew install llama.cpp这会全局提供llama-server命令。接着安装 Hugging Face 的下载工具并拉取 GGUF 模型约 5.3 GB 下载量注意磁盘空间brew install huggingface-cli huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models如果下载时遇到 401 或 404说明模型需要认证先运行huggingface-cli login。启动服务器llama-server -m ~/models/Qwen3.5-9B-Q4_K_M.gguf \ -ngl 99 \ -c 131072 \ -np 1 \ -fa on \ --cache-type-k q4_0 \ --cache-type-v q4_0 \ --jinja \ --host 0.0.0.0各参数作用--jinja一项来自 providers 集成文档其余来自 Mac 本地 LLM 指南参数用途-ngl 99把所有层卸载到 GPUMetal用大数值确保没有层留在 CPU-c 131072上下文窗口128K tokens内存不足时调小-np 1并行 slot 数单人用保持 1更多 slot 会分摊内存-fa onFlash attention降低内存占用并加速长上下文推理--cache-type-k q4_0把 key cache 量化到 4-bit最重要的省内存项--cache-type-v q4_0把 value cache 量化到 4-bit两者合计比 f16 省约 75% KV 内存--jinjaHermes 的工具调用依赖它llama-server 不加--jinja会直接忽略tools参数模型会把工具调用写成回复里的原始 JSON--host 0.0.0.0监听所有网卡不需要局域网访问时改用127.0.0.1关于-c近期构建的 llama.cpp 默认-c 0即从 GGUF 元数据读取模型训练上下文对 128k 训练上下文的模型这会尝试分配完整 KV cache 导致 OOM所以必须显式设置。并行 slot 会平分上下文——-c 64000 -np 4每个 slot 只有 16K低于 Hermes 的 64K 下限。内存受限时的量级参考128K 上下文、9B 模型KV cache 类型KV cache 内存f16默认约 16 GBq8_0约 8 GBq4_0约 4 GB文档给出的分档建议8 GB Mac 用q4_0KV cache 并选择更小但仍能满足 64K 下限的模型16 GB 可以舒服地跑 128K 上下文32 GB 可以跑更大模型或多 slot。仍然 OOM 时只在不低于 64K 下限的前提下降上下文否则换更小的模型或更低的量化如 Q3_K_M 代替 Q4_K_M。服务器就绪的判定终端出现以下输出即表示就绪文档示例输出main: server is listening on http://0.0.0.0:8080 srv update_slots: all slots are idle路径 A 验证curl -s http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3.5-9B-Q4_K_M.gguf, messages: [{role: user, content: Hello!}], max_tokens: 50 } | jq .choices[0].message.content返回里能看到模型回复文本即通过。忘了模型名时查一下模型列表curl -s http://localhost:8080/v1/models | jq .data[].id路径 BMLX via omlx可选分支omlx 是 macOS 原生应用负责管理和服务 MLX 模型MLX 是 Apple 自家框架针对统一内存架构优化。从 omlx 官网下载并安装应用。在 omlx 应用内搜索并下载Qwen3.5-9B-mlx-lm-mxfp4模型默认存放在~/.omlx/models/。在应用 UI 里启动服务omlx 默认服务在http://127.0.0.1:8000。验证方式与路径 A 相同只是端口和模型名不同curl -s http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3.5-9B-mlx-lm-mxfp4, messages: [{role: user, content: Hello!}], max_tokens: 50 } | jq .choices[0].message.contentomlx 支持同时服务多个模型用同样的方式查列表curl -s http://127.0.0.1:8000/v1/models | jq .data[].id接入 Hermes Agent本地服务器跑起来之后用hermes model接入两条路径通用hermes model选择Custom endpoint按提示输入 base URL 和模型名——llama.cpp 用http://localhost:8080/v1omlx 用http://localhost:8000/v1模型名填上一步/v1/models里查到的值上下文长度至少 64000且要与你服务器实际设置的窗口保持一致。API key 本地服务器不需要跳过即可。选择会写入~/.hermes/config.yaml的model.provider与model.default跨会话持久生效。也可以直接编辑~/.hermes/config.yaml参考 FAQ 的写法model: default: Qwen3.5-9B-Q4_K_M.gguf # 换成你 /v1/models 查到的模型名 provider: custom base_url: http://localhost:8080/v1接入后跑一条真实对话让 Hermes 列一下当前目录的文件工具调用正常执行就说明链路通了。超时行为与首轮“静默”Hermes 会自动识别本地端点localhost、局域网 IP并放宽流式超时多数情况无需配置超时项默认值本地端点自动调整环境变量覆盖Stream readsocket 级120s提升到 1800sHERMES_STREAM_READ_TIMEOUTStale stream 检测180s完全禁用HERMES_STREAM_STALE_TIMEOUTAPI 调用非流式1800s无需改动HERMES_API_TIMEOUT如果在大上下文 慢硬件上仍遇到超时在~/.hermes/.env里显式覆盖HERMES_STREAM_READ_TIMEOUT1800另外一个必须知道的现象Hermes 每次调用都会发送系统提示词和全部工具 schema慢硬件上首轮可能要静默数分钟——这是 prefill预填充在工作不是会话卡死。缓解手段见 Ollama 本地部署指南的 prefill 一节保持模型常驻、用hermes prompt-size查看固定提示词的字节构成并裁剪。常见故障速查huggingface-cli下载报 401/404模型需要认证先huggingface-cli login。工具调用以原始 JSON 出现在回复里如{name: web_search, ...}服务器没开工具调用支持。llama.cpp 缺--jinja就会这样加上后可以用http://localhost:8080/props检查chat_template字段是否存在来确认支持已生效。内存不足OOM换q4_0KV cache在不跌破 64K 的前提下降上下文仍不够就换更小模型或更低量化Q3_K_M。流式超时先确认端点是 localhost/局域网 IP 以便自动放宽生效再用HERMES_STREAM_READ_TIMEOUT覆盖。参考资料Run Local LLMs on Mac — 本文主路径的完整来源模型选型、后端基准、超时表Local Models — 桌面应用托管运行时、内存管理与local_runtime配置Provider 集成文档 — llama.cpp 段的--jinja、-c与/props验证说明FAQ — Custom endpoint 的config.yaml写法【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考