> 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（可选）

通过 Ollama 或 LM Studio 提供的可选本地 AI。支持记忆嵌入、摘要树构建、学习轮次，以及在设备上显式路由的聊天/推理工作负载。

OpenHuman 可以在你的机器上运行本地模型，用于那些需要将数据保留在设备上的工作负载： **记忆嵌入、摘要树构建、学习与反思流程，以及显式路由的聊天或推理工作负载**。它是 **需主动启用** 并且默认 **关闭** 。

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

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

| 工作负载        | 默认模型                     | 实现                                                                                                                                                                                          |
| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **记忆嵌入**    | `bge-m3`                 | `OllamaEmbeddingModel`，由 `crates/tinyinference-embeddings/src/factory.rs` 在 `vendor/tinyagents/vendor/tinyinference` —由 [记忆树](/openhuman/zh/gong-neng/obsidian-wiki/memory-tree.md) 用于向量检索。 |
| **摘要树构建**   | `gemma3:1b-it-qat` （可配置） | `crates/tinymemory-core/src/tree/summarise.rs` 在 `vendor/tinymemory` —用于记忆树的来源 / 主题 / 全局摘要构建器。                                                                                              |
| **学习 / 反思** | 小型聊天模型                   | `crates/openhuman-core/src/agent/learning/reflection.rs` —用于整合已学内容的流程。                                                                                                                      |
| **聊天**      | 已配置的本地聊天模型               | `Config::workload_local_model("chat")` 读取 `chat_provider`; `crates/openhuman-core/src/inference/provider/factory/routing.rs` 处理提示路由。                                                        |
| **推理**      | 已配置的本地聊天模型               | `Config::workload_local_model("reasoning")` 读取 `reasoning_provider`；参见 [选择启用](#opting-in).                                                                                                  |

这些都需要显式选择启用。开启本地 AI 不会在不告知你的情况下把所有内容都路由到本地，你可以自行选择工作负载。

## 默认保留在云端的内容

| 工作负载      | 为什么使用云端                                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| **聊天**    | 前沿级推理质量，除非 `chat_provider` 明确设置为本地提供方。                                                                       |
| **推理**    | 更强的多步推理质量，除非 `reasoning_provider` 明确设置为本地提供方。                                                                |
| **视觉**    | 同样如此，除非 `vision_provider` 指向一个支持视觉的本地模型。见下文。                                                                 |
| **语音转文本** | 通过后端代理进行转录，借助 `tinyinference-voice`，认证绑定在 `crates/openhuman-core/src/voice/cloud_transcribe.rs`。没有本地 STT 引擎。 |
| **文本转语音** | 托管的 [文本转语音](/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` 端点（如可能）进行通信。这意味着：

* OpenAI 兼容提供方（`crates/openhuman-core/src/inference/provider/crate_openai.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`.

## 选择启用

本地运行时启动由核心配置中的以下项控制（`crates/openhuman-core/src/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(...)` 在 `crates/openhuman-core/src/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 的权重。

## 本地视觉

视觉是与聊天分开的独立能力，而且 **大多数小型本地模型都无法胜任**。因此，尽管它是一个能力不错的聊天模型，但它并不适用于视觉。

这在实践中意味着：

* `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 处理：生命周期（`crates/openhuman-core/src/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)。选择启用后哪些内容会转到设备本地。