> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/model-routing/local-ai.md).

# 本地 AI（可选）

OpenHuman 可以在你的机器上运行本地模型，用于那些数据留在设备上很重要的工作负载： **内存嵌入、总结树构建、后台推理循环，以及显式路由的聊天或推理工作负载**. 它是 **可选择启用的** 并将其 **发送到外部** 默认情况下。

这是有意的范围限定。之前的设计试图默认将每种模态都放到设备上运行，结果造成了沉重且对硬件敏感的占用。如今，本地 AI 保持显式：重复出现的、涉及隐私的工作可以在本地运行；当你把这些工作负载路由到本地提供方时，聊天/推理也可以在本地运行。

## 开启后本地运行的内容

| 工作负载        | 默认模型                     | 实现                                                                                                                      |
| ----------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **内存嵌入**    | `bge-m3`                 | `src/openhuman/inference/embeddings/ollama.rs` - 用于 [记忆树](/openhuman/zh/gong-neng/obsidian-wiki/memory-tree.md) 进行向量搜索。 |
| **总结树构建**   | `gemma3:1b-it-qat` （可配置） | `src/openhuman/tree_summarizer/ops.rs` - 用于内存树的源 / 主题 / 全局摘要构建器。                                                        |
| **心跳循环**    | 小型聊天模型                   | `src/openhuman/subconscious/heartbeat/` - 周期性的后台反思。                                                                     |
| **学习 / 反思** | 小型聊天模型                   | `src/openhuman/agent/learning/reflection.rs` - 用于整合所学内容的传递过程。                                                           |
| **潜意识**     | 小型聊天模型                   | `src/openhuman/subconscious/executor.rs` - 后台评估循环。                                                                      |
| **聊天**      | 已配置的本地聊天模型               | `Config::workload_local_model("chat")` 读取 `chat_provider`; `src/openhuman/routing/provider.rs` 处理提示路由。                  |
| **推理**      | 已配置的本地聊天模型               | `Config::workload_local_model("reasoning")` 读取 `reasoning_provider`；见 [选择加入](#opting-in).                               |

这些都是显式的选择加入。开启本地 AI 不会在不告知的情况下把所有内容都路由到它上面，而是由你来选择具体的工作负载。

## 默认情况下保留在云端的内容

| 工作负载     | 为什么使用云端                                                                            |
| -------- | ---------------------------------------------------------------------------------- |
| **聊天**   | 前沿级推理质量，除非 `chat_provider` 被显式设置为本地提供方。                                            |
| **推理**   | 更强的多步质量，除非 `reasoning_provider` 被显式设置为本地提供方。                                       |
| **视觉**   | 同样如此，除非 `vision_provider` 指向一个支持视觉的本地模型。见下文。                                       |
| **STT**  | 由后端代理的转写（`src/openhuman/voice/cloud_transcribe.rs`).                               |
| **TTS**  | 托管的 [文本转语音](/openhuman/zh/gong-neng/native-tools/voice.md) 在底层（`reply_speech.rs`). |
| **网页搜索** | 后端代理（你的机器上没有 API 密钥）。                                                              |

对于 **轻量级或中等聊天提示** (`hint:reaction`, `hint:classify`, `hint:format`, `hint:sentiment`, `hint:summarize`, `hint:medium`, `hint:tool_lite`）， [路由器](/openhuman/zh/gong-neng/model-routing.md) 只有在 `local_ai.runtime_enabled = true` 且已配置的本地提供方可达时，才会优先使用本地提供方。

重型提示（`hint:reasoning`, `hint:agentic`, `hint:coding`）默认仍留在云端，除非相应工作负载提供方字段被显式配置为本地。

## 工作原理

在底层，OpenHuman 支持两条本地提供方路径：

* [Ollama](https://ollama.com)用于捆绑模型生命周期、嵌入，以及现有的模型资产流程。
* [LM Studio](https://lmstudio.ai)，通过其本地兼容 OpenAI 的服务器进行聊天式本地推理。

对于 Ollama，OpenHuman 尽可能与其兼容 OpenAI 的 `/v1` 端点交互。这意味着：

* 这个 `OpenAiCompatibleProvider` (`src/openhuman/providers/compatible.rs`）包装 Ollama 的方式与包装远程 OpenAI 风格提供方完全相同。没有特殊分支代码路径。
* 提供方路由器会在启动时创建一个 *健康检查门控的* 本地提供方。如果 Ollama 不可达，请求会透明地回退到远程提供方，不会出现损坏状态。
* 模型由 Ollama 按需拉取，并缓存在它自己的存储中。OpenHuman 本身不随附这些权重。

对于 LM Studio，设置 `local_ai.provider = "lm_studio"` 并确保 LM Studio 的本地服务器正在运行。OpenHuman 默认使用 `http://localhost:1234/v1`，探测 `GET /v1/models`，并将聊天请求发送到 `POST /v1/chat/completions`。你可以使用 `local_ai.base_url`, `OPENHUMAN_LM_STUDIO_BASE_URL`，或 `LM_STUDIO_BASE_URL`.

## 选择加入

本地运行时的启动在核心配置中受控（`src/openhuman/config/schema/local_ai.rs`):

| 标志                                   | 默认       | 含义                                                    |
| ------------------------------------ | -------- | ----------------------------------------------------- |
| `local_ai.runtime_enabled`           | `false`  | 总开关。 `false` ⇒ 根本不会创建本地提供方。                           |
| `local_ai.opt_in_confirmed`          | `false`  | 显式选择加入标记。引导过程会强制 `false` ，除非你重新选择加入。                  |
| `local_ai.provider`                  | `ollama` | 本地提供方： `ollama` 或 `lm_studio`.                        |
| `local_ai.base_url`                  | 未设置      | 可选的提供方 URL。LM Studio 默认使用 `http://localhost:1234/v1`. |
| `local_ai.usage.embeddings`          | `false`  | 用于内存嵌入的旧预设/迁移标志。                                      |
| `local_ai.usage.heartbeat`           | `false`  | 用于心跳循环的旧预设/迁移标志。                                      |
| `local_ai.usage.learning_reflection` | `false`  | 用于学习传递过程的旧预设/迁移标志。                                    |
| `local_ai.usage.subconscious`        | `false`  | 用于潜意识循环的旧预设/迁移标志。                                     |

统一的工作负载提供方字段控制聊天/推理路由。当你希望这些路径在设备上运行时，将它们设置为 Ollama 提供方字符串：

```toml
chat_provider = "ollama:llama3.1:8b"
reasoning_provider = "ollama:qwen2.5:14b"
```

在当前配置中， `*_provider` 字段是工作负载路由的事实来源（`Config::workload_local_model(...)` 在 `src/openhuman/config/schema/types.rs`）。未设置、为空， `cloud`, `openhuman`，或任何非`ollama:` 的值都会使该工作负载保持在云端/默认路由。将提供方字符串设置为类似 `ollama:all-minilm:latest` 或 `ollama:qwen2.5:14b` 这样的值会在 `local_ai.runtime_enabled = true` 且提供方健康检查通过时，将该工作负载路由到设备上。

旧的 `local_ai.usage.*` 布尔值仅为预设和迁移兼容性而保留；迁移后它们不会覆盖统一的提供方字段。为了确定性路由，请直接设置工作负载提供方字段，或者保持未设置 / 设置为 `cloud` 以强制使用默认云端路由。相同的提供方字符串模式也用于 `agentic_provider`, `coding_provider`, `memory_provider`, `embeddings_provider`, `heartbeat_provider`, `learning_provider`，以及 `subconscious_provider`.

### 旧标志行为

这个 `local_ai.usage.*` 布尔值仅在应用预设和初始迁移期间被读取。在那之后， `Config::workload_local_model(...)` 会将对应的 `*_provider` 字段视为最终的路由控制：

* `embeddings_provider = "ollama:all-minilm"` 会将嵌入路由到设备上，即使 `local_ai.usage.embeddings = false`.
* 未设置、为空，或 `cloud` `embeddings_provider` 也会将嵌入保持在云端/默认路由，即使 `local_ai.usage.embeddings = true`.

手动编辑配置时，建议直接设置 `*_provider` 字段。

在桌面应用中， **设置 → AI 与技能 → 本地 AI** 提供预设，选择一个（“仅嵌入”、“内存 + 反思”、“全部本地”），系统会为你设置正确的标志组合。状态（Ollama 可达性、模型可用性、各子系统启用情况）会通过 `openhuman.inference_status`.

## 何时开启

如果以下任一情况成立，开启本地 AI 就很值得：

* 在导入大量邮件 / 聊天记录时，将嵌入保留在本地。
* 启用 **总结树构建** 以便离线工作。
* 将后台反思（“潜意识”）循环保留在设备上，以处理涉及隐私的工作。

它是 **不** 值得开启，如果你只连接了少量来源，云端路径更快，而且隐私收益很小。此外还有硬件成本：Ollama 和一个小型 Gemma 模型需要几 GB 内存，并会拉取几 GB 的权重。

## 本地视觉

视觉与聊天是不同的能力，而 **大多数小型本地模型都无法做到**。Ollama 不会拒绝发送给纯文本模型的图片：它会丢弃图片，只根据提示文本作答，这会导致模型对自己从未见过的内容给出流畅的描述。因此，OpenHuman 会通过能力检查来解析视觉模型，并拒绝把视觉请求路由到仅支持聊天的模型。

这在实践中意味着：

* `local_ai.vision_model_id` 必须指定一个支持视觉的模型。 `moondream:1.8b-v2-q4_K_S` （约 1.7 GB）是最小的选项； `gemma3:4b-it-qat` 以及 `gemma4:e4b-it-q8_0` 使用一组权重同时处理聊天和视觉。
* Gemma 3 在 270M 和 1B 时仅支持文本，从 4B 起支持多模态。 **Gemma 3n 是不同的模型，并且在所有尺寸上都仅支持文本**，因此它虽然是一个强大的聊天模型，但不能用于视觉。
* 将 `vision_model_id` 留空是一个有效的“无本地视觉”配置。此时视觉请求会返回一条消息，说明要设置哪个配置键以及要拉取哪些模型，而不是静默失败。
* 如果已配置的视觉模型最终发现只是聊天模型，核心会记录警告并回退到支持视觉的默认模型，而不是把图片发送给会忽略它们的模型。

完整的逐模型能力表位于 [本地模型与自带密钥](/openhuman/zh/gong-neng/model-routing/local-and-byok-models.md).

## 你需要准备的内容

* [**Ollama**](https://ollama.com) 已安装并在本地运行，或 [**LM Studio**](https://lmstudio.ai) 并启用了本地服务器。
* 模型所需的磁盘空间足够（`gemma3:1b-it-qat` 约 1.0 GB， `bge-m3` 约 1.2 GB，如果再添加用于视觉的 Moondream 则再加约 1.7 GB）。
* 足够的内存以保持模型常驻（建议 8 GB+，理想为 16 GB+）。

OpenHuman 负责其余部分：生命周期（`src/openhuman/inference/local/service/`）、API 客户端、健康检查，以及本地提供方消失时平滑回退到远程。

### LM Studio 故障排查

* 确认 LM Studio 本地服务器已启用，并且可通过 `http://localhost:1234/v1`.
* 在调用 OpenHuman 之前先在 LM Studio 中加载所选模型。诊断会在 `load_lm_studio_model` 当已配置的 `local_ai.chat_model_id` 不在 `/v1/models`.
* 如果 LM Studio 使用不同端口，请设置 `local_ai.base_url` 或 `OPENHUMAN_LM_STUDIO_BASE_URL`.
* LM Studio 的模型下载由 LM Studio 内部管理。OpenHuman 不会通过本地资产下载控制来拉取 LM Studio 模型。

## 另请参阅

* [本地模型与自带密钥](/openhuman/zh/gong-neng/model-routing/local-and-byok-models.md)。逐模型能力表和 BYOK 设置。
* [记忆树](/openhuman/zh/gong-neng/obsidian-wiki/memory-tree.md)。本地嵌入 + 汇总的轻量能力。
* [自动模型路由](/openhuman/zh/gong-neng/model-routing.md)。轻量聊天提示如何优先使用本地提供方。
* [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)。选择加入后哪些内容会转到设备上。