> 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/zhi-nan/guides/local-model.md).

# 使用本地模型的 OpenHuman

**目标：** 将 OpenHuman 的部分或全部模型工作迁移到你自己的电脑上，使这些工作负载使用的数据永远不会离开这台机器。

本地 AI 是 **可选择启用的** 并将其 **发送到外部**。开启它不会悄悄把所有内容改道。你可以选择哪些工作负载走本地。

关于配置级参考（每个标志和提供方字段），请参见 [本地 AI（可选）](/openhuman/zh/gong-neng/model-routing/local-ai.md)。本指南是面向任务的版本：先让它运行起来，并确认它正常工作。

***

## 前提条件

* [**Ollama**](https://ollama.com) 已安装。OpenHuman 通过其默认地址与它通信 `http://localhost:11434`。（LM Studio 也支持 `http://localhost:1234/v1`；请参见 [参考页面](/openhuman/zh/gong-neng/model-routing/local-ai.md#lm-studio-troubleshooting).)
* **8 GB 以上内存** 才能真正发挥价值。少于 8 GB 的机器会按设计回退到云端摘要，因为小型本地模型没有足够余量。
* 权重所需磁盘空间：一个小型聊天模型加一个嵌入模型大约需要几 GB。OpenHuman 不会随附权重；Ollama 会按需下载。

## 隐私影响

* 你路由到本地的工作负载（嵌入、摘要构建、后台循环，以及如果你选择的话，聊天/推理）会 **完全在设备上**运行。这些工作的任何内容都不会被发送出去。
* 你保留在默认路由上的任何内容仍然会经过 OpenHuman 的 [模型路由器](/openhuman/zh/gong-neng/model-routing.md)。本地 AI 是增量式的；它不会改变你没有迁移的内容。
* 如果本地提供方在会话中途变得不可达，请求会 **透明地回退** 到远程提供方。这意味着崩溃的 Ollama 可能会把该数据发送到云端路径。如果严格要求本地性，请查看诊断信息（见下文）。

***

## 步骤

### 1. 启动 Ollama

安装并启动 Ollama，使其本地服务器运行起来。你可以在终端中确认它已启动：

```bash
curl http://localhost:11434/api/tags
```

一个 JSON 模型列表（即使是空的）也表示服务器可达。这是 OpenHuman 用来检测 Ollama 的确切探测方式。

### 2. 在 OpenHuman 中开启本地 AI

打开 **设置 → AI 与技能 → 本地 AI**。在这里选择之前它是关闭的。请选择 **模型档位** ，使其匹配你机器的内存（例如， `ram_2_4gb` 档位适合一台典型笔记本电脑）。OpenHuman 会为你选择合适的设备端模型，例如 `gemma3:1b-it-qat` 用于聊天，以及 `bge-m3` 用于嵌入。

默认情况下，该档位会将 **嵌入和记忆** 保留在设备上，而聊天和推理仍走云端路径。若要把这些工作负载也迁移到本地，请使用 **自定义路由** 把聊天和推理工作负载指向本地提供方，然后测试消息是否留在本机上。

### 3. 让它拉取模型

当某个工作负载需要一个尚未安装的模型时，OpenHuman 会通过 Ollama 拉取它，并显示 **下载进度**。你也可以手动拉取：

```bash
ollama pull gemma3:1b-it-qat
ollama pull bge-m3
```

### 4. 测试它是否真的会回答

不要猜；要验证。Local AI 设置提供一个 **测试操作** ，它会向已配置的本地提供方发送一个简短提示，并显示回复。如果你收到了连贯的响应，就表示整条路径端到端可用（检测 → 模型加载 → 推理）。

***

## 成功检查

当满足以下条件时，本地 AI 即可正常工作：

* [ ] **设置 → AI 与技能 → 本地 AI** 显示 Ollama 可达，且你选择的模型可用（不是“下载中”或“缺失”）。
* [ ] 测试操作返回了本地模型的真实回复。
* [ ] 推理状态显示 **`就绪`** （不是 `降级`, `下载中`，也不是 `已禁用`).
* [ ] 对于仅嵌入的设置：在下一次记忆同步后，只要 Ollama 仍在运行，新的摘要就会继续出现在 **记忆** 选项卡中。这证实嵌入是在本地生成的。

{% hint style="info" %}
**在内部查看的位置。** OpenHuman 会为本地运行时提供一个实时诊断视图（Ollama 可达吗？运行器正常吗？已安装的模型与预期一致吗？有什么问题？）。如果某项检查失败，诊断会指出具体问题。在更改配置之前先从这里开始。
{% endhint %}

## 常见故障

以下是运行时报告的实际故障状态，以及各自含义：

| 你看到的内容                                        | 含义                                  | 修复方法                                                                                  |
| --------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------- |
| **“Ollama 服务器未运行或无法访问”** （状态 `降级`)            | 应用无法通过其基础 URL 连接到 Ollama            | 启动 Ollama；确认 `curl http://localhost:11434/api/tags` 可用；如果你使用非默认端口，请在本地 AI 设置中设置基础 URL |
| **“……可达，但无法执行模型。重启外部运行时并重试。”**                | Ollama 有响应，但其模型运行器已损坏（fork/exec 失败） | 完全退出并重新启动 Ollama 本身，然后重试                                                              |
| **“聊天模型‘……’未安装”**                             | 配置的模型尚未被拉取                          | 让 OpenHuman 拉取它，或者运行 `ollama pull <模型>`                                               |
| **“……在全新安装后仍无法访问。请手动启动 `ollama serve` 并重试。”** | Ollama 刚安装好，但服务器尚未启动                | 运行 `ollama serve` （或启动 Ollama 应用）并重试                                                  |
| 嵌入模型因 **上下文窗口太小而被拒绝**                         | 所选嵌入模型无法为记忆层容纳足够的 token             | 请选择更大上下文的嵌入模型，例如 **`bge-m3`**                                                         |
| 状态卡在 **`下载中`**，随后出现重试消息                       | 模型拉取流被中断                            | 它会自动重试；如果一直失败，请检查磁盘空间和网络，然后手动拉取                                                       |
| 它“能用”，但回答感觉像云端质量                              | 本地提供方不可达，而 OpenHuman **已回退到远程**     | 请修复上面的可达性；严格本地用户应先确认状态为 `就绪` 再依赖它                                                     |

## 恢复

* **一步回到云端：** 在 **设置 → AI 与技能 → 本地 AI**中重新关闭本地 AI。工作负载会立即返回默认路由；不会丢失任何数据。
* **释放卡住的运行时：** 完全退出 Ollama 并重新启动，然后重新打开本地 AI 设置，让 OpenHuman 重新探测。
* **磁盘压力：** 中断的拉取通常是因为磁盘空间不足。清理空间并让拉取继续，或者 `ollama pull` 手动拉取该模型。

***

## 关于哪些内容仍然留在云端的说明

即使设置为“全部本地”，某些工作负载默认仍在云端，除非你显式路由它们：语音转文本、文本转语音和网页搜索会通过后端代理。请参见 [哪些内容仍留在云端](/openhuman/zh/gong-neng/model-routing/local-ai.md#what-stays-in-the-cloud-by-default).

## 另请参阅

* [本地 AI（可选）](/openhuman/zh/gong-neng/model-routing/local-ai.md)：完整配置参考。
* [保护敏感数据的隐私](/openhuman/zh/zhi-nan/guides/privacy-sensitive-data.md)：本地与外部的通俗版本。
* [自动模型路由](/openhuman/zh/gong-neng/model-routing.md)：任务如何与模型匹配。