> 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 保持显式：可重复的隐私敏感工作可以在本地运行，而当你把这些工作负载路由到本地提供方时，聊天/推理也可以在本地运行。

## 开启后哪些内容会在本地运行

| 工作负载        | 默认模型                     | 实现                                                                                                           |
| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| **内存嵌入**    | `all-minilm:latest`      | `src/openhuman/embeddings/ollama.rs` ——由 [记忆树](/openhuman/zh/gong-neng/obsidian-wiki/memory-tree.md) 用于向量搜索。 |
| **摘要树构建**   | `gemma3:1b-it-qat` （可配置） | `src/openhuman/tree_summarizer/ops.rs` ——用于 Memory Tree 的源 / 主题 / 全局摘要构建器。                                   |
| **心跳循环**    | 小型聊天模型                   | `src/openhuman/heartbeat/` ——定期的后台反思。                                                                        |
| **学习 / 反思** | 小型聊天模型                   | `src/openhuman/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` 被显式设置为本地提供方。                                       |
| **视觉**         | 同上。                                                                                |
| **语音转文本（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`）。未设置、空白、 `云端`, `openhuman`，或任何非`ollama:` 的值都会让该工作负载保持在云端/默认路由。将提供方字符串设置为例如 `ollama:all-minilm:latest` 或 `ollama:qwen2.5:14b` 会在以下条件下将该工作负载路由到设备端： `local_ai.runtime_enabled = true` 并且提供方健康检查通过。

旧版的 `local_ai.usage.*` 布尔值保留用于预设和迁移兼容性；迁移后它们不会覆盖统一的提供方字段。要实现确定性路由，要么显式设置工作负载提供方字段，要么将其留空 / 设为 `云端` 以强制默认的云端路由。相同的提供方字符串模式也用于 `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`.
* 未设置、空白或 `云端` `embeddings_provider` 即使如此也会让嵌入保持在云端/默认路由 `local_ai.usage.embeddings = true`.

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

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

## 何时开启

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

* 在摄入大量电子邮件 / 聊天记录时保持嵌入在本地。
* 启用 **摘要树构建** 以便离线工作。
* 将后台反思（“潜意识”）循环保留在设备上，以处理隐私敏感工作。

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

## 你需要准备

* [**Ollama**](https://ollama.com) 已安装并在本地运行，或者 [**LM Studio**](https://lmstudio.ai) 并启用了本地服务器。
* 有足够的磁盘空间存放模型（`gemma3:1b-it-qat` \~700 MB， `all-minilm:latest` \~23 MB）。
* 有足够的 RAM 让模型常驻（建议 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/obsidian-wiki/memory-tree.md)。本地嵌入 + 摘要能力。
* [自动模型路由](/openhuman/zh/gong-neng/model-routing.md)。轻量聊天提示如何优先使用本地提供方。
* [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)。在你选择启用后，哪些内容会迁移到设备端。