better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/local-llm-on-mac.md

@@ -0,0 +1,240 @@
+---
+sidebar_position: 2
+title: "在 Mac 上运行本地 LLM"
+description: "使用 llama.cpp 或 MLX 在 macOS 上搭建兼容 OpenAI 的本地 LLM 服务器，涵盖模型选择、内存优化以及 Apple Silicon 上的实测基准数据"
+---
+
+# 在 Mac 上运行本地 LLM
+
+本指南介绍如何在 macOS 上运行一个兼容 OpenAI API 的本地 LLM 服务器。你将获得完整的隐私保护、零 API 费用，以及 Apple Silicon 上出乎意料的出色性能。
+
+我们涵盖两个后端：
+
+| 后端 | 安装方式 | 优势 | 格式 |
+|---------|---------|---------|--------|
+| **llama.cpp** | `brew install llama.cpp` | 首 token 延迟最低，量化 KV 缓存节省内存 | GGUF |
+| **omlx** | [omlx.ai](https://omlx.ai) | token 生成速度最快，原生 Metal 优化 | MLX (safetensors) |
+
+两者均暴露兼容 OpenAI 的 `/v1/chat/completions` 端点。Hermes 支持任意一个——只需将其指向 `http://localhost:8080` 或 `http://localhost:8000`。
+
+:::info 仅限 Apple Silicon
+本指南面向搭载 Apple Silicon（M1 及更新）的 Mac。Intel Mac 可使用 llama.cpp，但无 GPU 加速——性能会明显更慢。
+:::
+
+---
+
+## 选择模型
+
+入门推荐 **Qwen3.5-9B**——这是一个强推理模型，量化后可在 8GB+ 统一内存上轻松运行。
+
+| 变体 | 磁盘占用 | 所需内存（128K 上下文） | 后端 |
+|---------|-------------|---------------------------|---------|
+| Qwen3.5-9B-Q4_K_M (GGUF) | 5.3 GB | ~10 GB（含量化 KV 缓存） | llama.cpp |
+| Qwen3.5-9B-mlx-lm-mxfp4 (MLX) | ~5 GB | ~12 GB | omlx |
+
+**内存估算规则：** 模型大小 + KV 缓存。9B Q4 模型约 5 GB。128K 上下文下 Q4 量化的 KV 缓存额外占用约 4–5 GB。若使用默认（f16）KV 缓存，则会膨胀至约 16 GB。llama.cpp 中的量化 KV 缓存参数是内存受限系统的关键技巧。
+
+对于更大的模型（27B、35B），你需要 32 GB+ 的统一内存。9B 是 8–16 GB 机器的最佳选择。
+
+---
+
+## 方案 A：llama.cpp
+
+llama.cpp 是移植性最强的本地 LLM 运行时。在 macOS 上，它开箱即用地通过 Metal 进行 GPU 加速。
+
+### 安装
+
+```bash
+brew install llama.cpp
+```
+
+安装后即可全局使用 `llama-server` 命令。
+
+### 下载模型
+
+你需要 GGUF 格式的模型。最简便的来源是通过 `huggingface-cli` 从 Hugging Face 下载：
+
+```bash
+brew install huggingface-cli
+```
+
+然后下载：
+
+```bash
+huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models
+```
+
+:::tip 受限模型
+Hugging Face 上的部分模型需要身份验证。如果遇到 401 或 404 错误，请先运行 `huggingface-cli login`。
+:::
+
+### 启动服务器
+
+```bash
+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 \
+  --host 0.0.0.0
+```
+
+各参数说明：
+
+| 参数 | 用途 |
+|------|---------|
+| `-ngl 99` | 将所有层卸载到 GPU（Metal）。设置较大的数值以确保没有层留在 CPU 上。 |
+| `-c 131072` | 上下文窗口大小（128K token）。内存不足时可减小此值。 |
+| `-np 1` | 并行槽数量。单用户使用时保持为 1——更多槽会分摊内存预算。 |
+| `-fa on` | Flash attention。减少内存占用并加速长上下文推理。 |
+| `--cache-type-k q4_0` | 将 key 缓存量化为 4-bit。**这是最大的内存节省手段。** |
+| `--cache-type-v q4_0` | 将 value 缓存量化为 4-bit。与上一项合用，相比 f16 可将 KV 缓存内存减少约 75%。 |
+| `--host 0.0.0.0` | 监听所有网络接口。若不需要网络访问，可改为 `127.0.0.1`。 |
+
+当你看到以下输出时，服务器已就绪：
+
+```
+main: server is listening on http://0.0.0.0:8080
+srv  update_slots: all slots are idle
+```
+
+### 内存受限系统的优化
+
+`--cache-type-k q4_0 --cache-type-v q4_0` 参数是内存有限系统最重要的优化手段。以下是 128K 上下文下的影响对比：
+
+| KV 缓存类型 | KV 缓存内存（128K 上下文，9B 模型） |
+|---------------|--------------------------------------|
+| f16（默认） | ~16 GB |
+| q8_0 | ~8 GB |
+| **q4_0** | **~4 GB** |
+
+在 8 GB Mac 上，使用 `q4_0` KV 缓存并将上下文缩减为 `-c 32768`（32K）。在 16 GB 上，可以轻松使用 128K 上下文。在 32 GB+ 上，可以运行更大的模型或多个并行槽。
+
+如果仍然内存不足，优先减小上下文大小（`-c`），然后尝试更小的量化级别（Q3_K_M 代替 Q4_K_M）。
+
+### 测试
+
+```bash
+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
+```
+
+### 获取模型名称
+
+如果忘记了模型名称，可查询 models 端点：
+
+```bash
+curl -s http://localhost:8080/v1/models | jq '.data[].id'
+```
+
+---
+
+## 方案 B：通过 omlx 使用 MLX
+
+[omlx](https://omlx.ai) 是一款 macOS 原生应用，用于管理和提供 MLX 模型服务。MLX 是 Apple 自研的机器学习框架，专为 Apple Silicon 统一内存架构优化。
+
+### 安装
+
+从 [omlx.ai](https://omlx.ai) 下载并安装。它提供图形界面用于模型管理，并内置服务器。
+
+### 下载模型
+
+使用 omlx 应用浏览并下载模型。搜索 `Qwen3.5-9B-mlx-lm-mxfp4` 并下载。模型存储在本地（通常位于 `~/.omlx/models/`）。
+
+### 启动服务器
+
+omlx 默认在 `http://127.0.0.1:8000` 上提供服务。通过应用 UI 启动服务，或在可用时使用 CLI。
+
+### 测试
+
+```bash
+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.content
+```
+
+### 列出可用模型
+
+omlx 可同时提供多个模型的服务：
+
+```bash
+curl -s http://127.0.0.1:8000/v1/models | jq '.data[].id'
+```
+
+---
+
+## 基准测试：llama.cpp vs MLX
+
+两个后端在同一台机器（Apple M5 Max，128 GB 统一内存）上测试，使用相同模型（Qwen3.5-9B），量化级别相当（GGUF 使用 Q4_K_M，MLX 使用 mxfp4）。五个不同 prompt，每个运行三次，后端顺序测试以避免资源竞争。
+
+### 结果
+
+| 指标 | llama.cpp (Q4_K_M) | MLX (mxfp4) | 胜者 |
+|--------|-------------------|-------------|--------|
+| **TTFT（首 token 延迟，均值）** | **67 ms** | 289 ms | llama.cpp（快 4.3 倍） |
+| **TTFT（p50）** | **66 ms** | 286 ms | llama.cpp（快 4.3 倍） |
+| **生成速度（均值）** | 70 tok/s | **96 tok/s** | MLX（快 37%） |
+| **生成速度（p50）** | 70 tok/s | **96 tok/s** | MLX（快 37%） |
+| **总耗时（512 token）** | 7.3s | **5.5s** | MLX（快 25%） |
+
+### 含义解读
+
+- **llama.cpp** 在 prompt 处理上表现突出——其 flash attention + 量化 KV 缓存流水线可在约 66ms 内返回第一个 token。如果你在构建对响应速度敏感的交互式应用（聊天机器人、自动补全），这是显著优势。
+
+- **MLX** 一旦开始生成，token 速度快约 37%。对于批量任务、长文本生成，或任何更关注总完成时间而非初始延迟的场景，MLX 完成得更快。
+
+- 两个后端都**极为稳定**——多次运行间的方差可忽略不计。这些数据可作为可靠参考。
+
+### 如何选择？
+
+| 使用场景 | 推荐 |
+|----------|---------------|
+| 交互式聊天、低延迟工具 | llama.cpp |
+| 长文本生成、批量处理 | MLX (omlx) |
+| 内存受限（8–16 GB） | llama.cpp（量化 KV 缓存无可匹敌） |
+| 同时提供多个模型服务 | omlx（内置多模型支持） |
+| 最大兼容性（含 Linux） | llama.cpp |
+
+---
+
+## 连接 Hermes
+
+本地服务器启动后：
+
+```bash
+hermes model
+```
+
+选择 **Custom endpoint**，按提示操作。系统会询问 base URL 和模型名称——使用你所配置的后端对应的值即可。
+
+---
+
+## 超时设置
+
+Hermes 会自动检测本地端点（localhost、局域网 IP）并放宽其流式传输超时限制。大多数情况下无需额外配置。
+
+如果仍然遇到超时错误（例如在慢速硬件上使用超大上下文），可以覆盖流式读取超时：
+
+```bash
+# 在 .env 中——将默认的 120s 提高到 30 分钟
+HERMES_STREAM_READ_TIMEOUT=1800
+```
+
+| 超时类型 | 默认值 | 本地自动调整 | 环境变量覆盖 |
+|---------|---------|----------------------|------------------|
+| 流式读取（socket 级别） | 120s | 提升至 1800s | `HERMES_STREAM_READ_TIMEOUT` |
+| 停滞流检测 | 180s | 完全禁用 | `HERMES_STREAM_STALE_TIMEOUT` |
+| API 调用（非流式） | 1800s | 无需调整 | `HERMES_API_TIMEOUT` |
+
+流式读取超时最容易引发问题——它是接收下一个数据块的 socket 级别截止时间。在大上下文的预填充（prefill）阶段，本地模型可能在处理 prompt 时数分钟内没有任何输出。自动检测机制会透明地处理这一情况。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/local-ollama-setup.md

@@ -0,0 +1,317 @@
+---
+sidebar_position: 9
+title: "使用 Ollama 在本地运行 Hermes — 零 API 费用"
+description: "使用 Ollama 和 Gemma 4 等开放权重模型在本机完整运行 Hermes Agent 的分步指南，无需云端 API 密钥或付费订阅"
+---
+
+# 使用 Ollama 在本地运行 Hermes — 零 API 费用
+
+## 问题所在
+
+云端 LLM API 按 token（令牌）计费。一次高强度的编程会话可能花费 5–20 美元。对于个人项目、学习或隐私敏感的工作，费用会不断累积——而且你的每一段对话都会发送给第三方。
+
+## 本指南解决什么
+
+你将在自己的硬件上完整运行 Hermes Agent，使用 [Ollama](https://ollama.com) 作为模型后端。无需 API 密钥，无需订阅，数据不会离开你的机器。配置完成后，Hermes 的使用体验与 OpenRouter 或 Anthropic 完全一致——终端命令、文件编辑、网页浏览、任务委派——只是模型在本地运行。
+
+完成后，你将拥有：
+
+- Ollama 提供一个或多个开放权重模型的服务
+- Hermes 通过自定义端点连接到 Ollama
+- 一个可以编辑文件、执行命令、浏览网页的本地 agent
+- 可选：由你自己的硬件驱动的 Telegram/Discord 机器人
+
+## 所需条件
+
+| 组件 | 最低配置 | 推荐配置 |
+|-----------|---------|-------------|
+| **内存** | 8 GB（适用于 3B 模型） | 32+ GB（适用于 27B+ 模型） |
+| **存储** | 5 GB 可用空间 | 30+ GB（适用于多个模型） |
+| **CPU** | 4 核 | 8+ 核（AMD EPYC、Ryzen、Intel Xeon） |
+| **GPU** | 非必需 | 配备 8+ GB 显存的 NVIDIA GPU 可显著提速 |
+
+:::tip 仅 CPU 可用，但响应速度较慢
+Ollama 可在纯 CPU 服务器上运行。现代 8 核 CPU 运行 9B 模型约可达 ~10 tokens/sec。31B 模型在 CPU 上更慢（~2–5 tokens/sec）——每次响应需要 30–120 秒，但可以正常工作。GPU 能大幅改善这一情况。对于纯 CPU 环境，通过环境变量（而非 `config.yaml` 键）放宽 API 超时时间：
+
+```bash
+# ~/.hermes/.env
+HERMES_API_TIMEOUT=1800   # 30 分钟 — 为慢速本地模型留出充裕时间
+```
+:::
+
+## 第一步：安装 Ollama
+
+```bash
+curl -fsSL https://ollama.com/install.sh | sh
+```
+
+验证是否正在运行：
+
+```bash
+ollama --version
+curl http://localhost:11434/api/tags   # 应返回 {"models":[]}
+```
+
+## 第二步：拉取模型
+
+根据你的硬件选择：
+
+| 模型 | 磁盘占用 | 所需内存 | 工具调用 | 适用场景 |
+|-------|-------------|------------|:------------:|----------|
+| `gemma4:31b` | ~20 GB | 24+ GB | 支持 | 最佳质量——工具使用和推理能力强 |
+| `gemma2:27b` | ~16 GB | 20+ GB | 不支持 | 对话任务，不支持工具使用 |
+| `gemma2:9b` | ~5 GB | 8+ GB | 不支持 | 快速问答——无法调用工具 |
+| `llama3.2:3b` | ~2 GB | 4+ GB | 不支持 | 仅适合轻量级快速回答 |
+
+:::warning 工具调用至关重要
+Hermes 是一个**agentic（智能体）**助手——它通过工具调用来编辑文件、执行命令和浏览网页。不支持工具调用的模型只能进行对话，无法执行操作。要体验完整的 Hermes 功能，请使用支持工具的模型（如 `gemma4:31b`）。
+:::
+
+拉取你选择的模型：
+
+```bash
+ollama pull gemma4:31b
+```
+
+:::info 多个模型
+你可以拉取多个模型，并在 Hermes 中使用 `/model` 切换。Ollama 按需将活跃模型加载到内存，并自动卸载空闲模型。
+:::
+
+验证模型是否正常工作：
+
+```bash
+curl http://localhost:11434/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gemma4:31b",
+    "messages": [{"role": "user", "content": "Say hello"}],
+    "max_tokens": 50
+  }'
+```
+
+你应该看到包含模型回复的 JSON 响应。
+
+## 第三步：配置 Hermes
+
+运行 Hermes 设置向导：
+
+```bash
+hermes setup
+```
+
+当提示选择提供商时，选择 **Custom Endpoint**，并输入：
+
+- **Base URL：** `http://localhost:11434/v1`
+- **API Key：** 留空或输入 `no-key`（Ollama 不需要密钥）
+- **Model：** `gemma4:31b`（或你拉取的模型）
+
+也可以直接编辑 `~/.hermes/config.yaml`：
+
+```yaml
+model:
+  default: "gemma4:31b"
+  provider: "custom"
+  base_url: "http://localhost:11434/v1"
+```
+
+## 第四步：开始使用 Hermes
+
+```bash
+hermes
+```
+
+就这样。你现在运行的是一个完全本地化的 agent。试试看：
+
+```
+You: List all Python files in this directory and count the lines of code in each
+
+You: Read the README.md and summarize what this project does
+
+You: Create a Python script that fetches the weather for Ho Chi Minh City
+```
+
+Hermes 将使用终端工具、文件操作和你的本地模型——无需任何云端调用。
+
+## 第五步：为任务选择合适的模型
+
+并非每个任务都需要最大的模型。以下是实用指南：
+
+| 任务 | 推荐模型 | 原因 |
+|------|-------------------|-----|
+| 文件编辑、代码、终端命令 | `gemma4:31b` | 唯一具备可靠工具调用能力的模型 |
+| 快速问答（无需工具调用） | `gemma2:9b` | 对话任务响应速度快 |
+| 轻量级聊天 | `llama3.2:3b` | 最快，但能力非常有限 |
+
+:::note
+对于完整的 agentic 工作（编辑文件、执行命令、浏览网页），`gemma4:31b` 目前是支持工具调用的最佳本地选项。请关注 [Ollama 的模型库](https://ollama.com/library) 以获取更新模型——工具调用支持正在快速扩展。
+:::
+
+在会话中即时切换模型：
+
+```
+/model gemma2:9b
+```
+
+## 第六步：优化速度
+
+### 增大 Ollama 的上下文窗口
+
+默认情况下，Ollama 使用 2048 token 的上下文。对于 agentic 工作（工具调用、长对话），需要更大的上下文：
+
+```bash
+# 创建一个扩展上下文的 Modelfile
+cat > /tmp/Modelfile << 'EOF'
+FROM gemma4:31b
+PARAMETER num_ctx 16384
+EOF
+
+ollama create gemma4-16k -f /tmp/Modelfile
+```
+
+然后将 Hermes 配置中的模型名称更新为 `gemma4-16k`。
+
+### 保持模型常驻内存
+
+默认情况下，Ollama 在模型空闲 5 分钟后将其卸载。对于持久化的 gateway 机器人，保持模型常驻：
+
+```bash
+# 将 keep-alive 设置为 24 小时
+curl http://localhost:11434/api/generate \
+  -d '{"model": "gemma4:31b", "keep_alive": "24h"}'
+```
+
+或在 Ollama 的环境变量中全局设置：
+
+```bash
+# /etc/systemd/system/ollama.service.d/override.conf
+[Service]
+Environment="OLLAMA_KEEP_ALIVE=24h"
+```
+
+### 使用 GPU 卸载（如有）
+
+如果你有 NVIDIA GPU，Ollama 会自动将层卸载到 GPU。通过以下命令检查：
+
+```bash
+ollama ps   # 显示已加载的模型及 GPU 层数
+```
+
+对于 12 GB 显存 GPU 上的 31B 模型，你将获得部分卸载（约 40 层在 GPU 上，其余在 CPU 上），仍能带来显著的速度提升。
+
+## 第七步：作为 Gateway 机器人运行（可选）
+
+一旦 Hermes 在 CLI 中本地运行正常，你可以将其作为 Telegram 或 Discord 机器人对外提供服务——仍完全运行在你的硬件上。
+
+### Telegram
+
+1. 通过 [@BotFather](https://t.me/BotFather) 创建机器人并获取 token
+2. 添加到 `~/.hermes/config.yaml`：
+
+```yaml
+model:
+  default: "gemma4:31b"
+  provider: "custom"
+  base_url: "http://localhost:11434/v1"
+
+platforms:
+  telegram:
+    enabled: true
+    token: "YOUR_TELEGRAM_BOT_TOKEN"
+```
+
+3. 启动 gateway：
+
+```bash
+hermes gateway
+```
+
+现在在 Telegram 上给你的机器人发消息——它将使用你的本地模型进行响应。
+
+### Discord
+
+1. 在 [discord.com/developers](https://discord.com/developers/applications) 创建 Discord 应用
+2. 添加到配置：
+
+```yaml
+platforms:
+  discord:
+    enabled: true
+    token: "YOUR_DISCORD_BOT_TOKEN"
+```
+
+3. 启动：`hermes gateway`
+
+## 第八步：设置回退方案（可选）
+
+本地模型在处理复杂任务时可能力不从心。设置一个仅在本地模型失败时激活的云端回退：
+
+```yaml
+model:
+  default: "gemma4:31b"
+  provider: "custom"
+  base_url: "http://localhost:11434/v1"
+
+fallback_providers:
+  - provider: openrouter
+    model: anthropic/claude-sonnet-4
+```
+
+这样，90% 的使用是免费的（本地），只有困难任务才会调用付费 API。
+
+## 故障排查
+
+### 启动时出现"Connection refused"
+
+Ollama 未在运行。启动它：
+
+```bash
+sudo systemctl start ollama
+# 或
+ollama serve
+```
+
+### 响应缓慢
+
+- **检查模型大小与内存：** 如果模型所需内存超过可用内存，会发生磁盘交换。请使用更小的模型或增加内存。
+- **检查 `ollama ps`：** 如果没有 GPU 层被卸载，响应受 CPU 限制。这对于纯 CPU 服务器是正常现象。
+- **减少上下文：** 长对话会降低推理速度。定期使用 `/compress`，或在配置中设置更低的压缩阈值。
+
+### 模型不遵循工具调用
+
+不支持工具调用的模型会输出纯文本，而非结构化的函数调用。解决方案：
+
+- **使用支持工具调用的模型** —— 在上面列出的模型中，只有 `gemma4:31b` 具备可靠的工具调用能力。
+- **Hermes 具备自动修复功能** —— 它能检测格式错误的工具调用并自动尝试修复。
+- **设置回退方案** —— 如果本地模型连续失败 3 次，Hermes 将回退到云端提供商。
+
+### 上下文窗口错误
+
+Ollama 默认上下文（2048 token）对于 agentic 工作来说太小。请参阅[第六步](#step-6-optimize-for-speed)了解如何增大上下文。
+
+## 费用对比
+
+以下是与云端 API 相比，本地运行的节省情况，基于典型编程会话（约 10 万 token 输入，约 2 万 token 输出）：
+
+| 提供商 | 每次会话费用 | 每月费用（每日使用） |
+|----------|-----------------|---------------------|
+| Anthropic Claude Sonnet | ~$0.80 | ~$24 |
+| OpenRouter（GPT-4o） | ~$0.60 | ~$18 |
+| **Ollama（本地）** | **$0.00** | **$0.00** |
+
+你唯一的成本是电费——根据硬件不同，每次会话约 $0.01–0.05。
+
+## 本地运行效果好的场景
+
+- **文件编辑和代码生成** —— 9B+ 模型处理效果良好
+- **终端命令** —— Hermes 封装命令、执行并读取输出，与模型无关
+- **网页浏览** —— 浏览器工具负责抓取内容，模型只需解读结果
+- **定时任务（Cron job）和计划任务** —— 与云端设置完全一致
+- **多平台 gateway** —— Telegram、Discord、Slack 均可与本地模型配合使用
+
+## 云端模型更具优势的场景
+
+- **非常复杂的多步推理** —— 70B+ 或 Claude Opus 等云端模型明显更强
+- **长上下文窗口** —— 云端模型提供 10 万–100 万 token；本地模型通常为 8K–32K
+- **大篇幅响应的速度** —— 对于长文本生成，云端推理比纯 CPU 本地运行更快
+
+最佳策略：日常任务使用本地模型，困难任务设置云端回退。