# 本地 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`）会像包装远程 OpenAI 风格提供方一样包装 Ollama，没有特殊分支代码路径。
* 提供方路由器在启动时会创建一个 *健康检查门控的* 本地提供方。如果 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.local_ai_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）。
* 足够的内存以保持模型驻留（建议 8 GB 以上，理想为 16 GB 以上）。

OpenHuman 会处理其余部分：生命周期（`src/openhuman/local_ai/service/`）、API 客户端（`ollama_api.rs`, `lm_studio_api.rs`）、健康检查，以及当本地提供方消失时优雅回退到远程。

### 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)。选择启用后哪些内容会转移到设备端。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/model-routing/local-ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.