> 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-and-byok-models.md).

# 本地模型与自带密钥

OpenHuman 订阅是 **默认**，不是硬性要求。推理可以来自三个地方中的任意一个，而且你可以按工作负载混用它们：本地运行嵌入、使用你自己的 Anthropic 密钥进行聊天，以及让视觉继续走托管路线，三者可同时进行。

本页介绍如何设置两个自有选项，以及，重要的是， **每一个到底能做什么**。并不是每个本地模型都能看图，而在视觉工作中选用仅聊天模型，是最常见的导致配置看似正确却悄悄做错事的原因。

## 三条路线一览

|                  | **托管（默认）**         | **BYOK 云端**       | **本地（Ollama / LM Studio）** |
| ---------------- | ------------------ | ----------------- | -------------------------- |
| **聊天与推理**        | 已包含                | 你的密钥，你的计费         | 是的，质量会随模型大小提升              |
| **视觉**           | 已包含                | 如果模型支持图像，则使用你的密钥  | 是，但仅限支持视觉的模型               |
| **嵌入**           | 已包含                | 如果提供方提供嵌入，则使用你的密钥 | 是， `bge-m3` 推荐             |
| **语音转文字**        | 已包含                | 不通过 BYOK 路由       | 可用本地 Whisper               |
| **文字转语音**        | 已包含                | 不通过 BYOK 路由       | 可用本地 Piper                 |
| **网页搜索**         | 已包含，无需密钥           | 使用你自己的 Exa 密钥     | 不适用                        |
| **推理数据会离开你的机器**  | 是，发送到 OpenHuman 后端 | 是，发送到你选择的提供方      | 否                          |
| **需要管理的 API 密钥** | None               | 每个提供方一个           | None                       |

最后一行特意指的是 **仅推理数据**。登录、托管集成 OAuth、计费，以及会议代理等托管功能，即使推理完全由你掌控，仍然会使用 OpenHuman 后端，因此仅仅运行本地模型并不能保证没有任何内容离开机器。如果你想要硬性保证推理绝不离开机器，请使用 [隐私模式](/openhuman/zh/gong-neng/privacy-and-security/privacy-mode.md)，它在 Rust 核心中强制执行仅本地路径，而不是仅依赖配置。

## 路线 A：使用 Ollama 的本地模型

### 1. 安装 Ollama 并拉取一个模型

安装 [Ollama](https://ollama.com)，然后拉取你需要的内容。本页列出的每个模型都可以直接从公开的 Ollama 库中拉取，无需额外设置：

```bash
ollama pull gemma3:1b-it-qat      # 小型聊天模型
ollama pull bge-m3                # 嵌入
ollama pull moondream:1.8b-v2-q4_K_S   # 视觉，小型
```

### 2. 了解每个模型支持什么

这就是最容易出问题的地方。一个只处理文本的模型在 Ollama 中仍然会 **接受** 图像请求：它会悄悄丢弃图像，只根据提示文本作答，读起来像是一个很自信、但完全是编造的描述。OpenHuman 会通过拒绝将视觉请求路由到仅聊天模型来防止这种情况，但了解哪个是什么仍然很有必要。

| 模型                         | 下载      | 聊天  | 视觉    | 嵌入                       |
| -------------------------- | ------- | --- | ----- | ------------------------ |
| `gemma3:270m-it-qat`       | 0.2 GB  | 是   | 否     | 否                        |
| `gemma3:1b-it-qat`         | 1.0 GB  | 是   | 否     | 否                        |
| `gemma3:4b-it-qat`         | 4.0 GB  | 是   | **是** | 否                        |
| `gemma3n:e4b-it-q8_0`      | 9.5 GB  | 是   | 否     | 否                        |
| `gemma4:e4b-it-q8_0`       | 11.6 GB | 是   | **是** | 否                        |
| `moondream:1.8b-v2-q4_K_S` | 1.7 GB  | 最小版 | **是** | 否                        |
| `llava:7b`                 | 4.7 GB  | 最小版 | **是** | 否                        |
| `bge-m3`                   | 1.2 GB  | 否   | 否     | **是**，1024 维             |
| `all-minilm:latest`        | 0.05 GB | 否   | 否     | 384 维，太小，不适合 Memory Tree |

有两个坑值得特别指出：

* **Gemma 3 按尺寸分成不同版本。** 270M 和 1B 构建版是仅文本的。视觉从 4B 开始。用于视觉会得到一个仅文本模型。 `gemma3:1b-it-qat` 用于视觉会得到一个仅文本模型。
* **`gemma3n` 不是 `gemma3`.** 尽管名字如此，Gemma 3n 在 Ollama 中是一个独立的仅文本模型。它是不错的聊天模型，但不是好的视觉模型。

对于嵌入，优先选择 **`bge-m3`**。Memory Tree 以固定的 1024 维磁盘格式存储向量，因此像 `all-minilm` 这样的 384 维模型，或者像 `nomic-embed-text` 这样的 768 维模型，都会在嵌入时的维度检查中失败。

### 3. 将 OpenHuman 指向它

最快的路径是桌面应用： **设置 → AI 与技能 → 本地 AI** 提供 RAM 档位预设，会为你设置每个模型 ID 并拉取权重。这些档位是：

| 级别       | 聊天                   | 视觉                         | 嵌入                       | 下载        |
| -------- | -------------------- | -------------------------- | ------------------------ | --------- |
| 1 GB     | `gemma3:270m-it-qat` | 已禁用                        | `all-minilm:latest` （见注） | 约 0.3 GB  |
| 2-4 GB   | `gemma3:1b-it-qat`   | 已禁用                        | `bge-m3`                 | 约 2.3 GB  |
| 4-8 GB   | `gemma3:1b-it-qat`   | `moondream:1.8b-v2-q4_K_S` | `all-minilm:latest` （见注） | 约 2.8 GB  |
| 8-16 GB  | `gemma3:4b-it-qat`   | `gemma3:4b-it-qat`         | `bge-m3`                 | 约 5.2 GB  |
| 16 GB 以上 | `gemma4:e4b-it-q8_0` | `gemma4:e4b-it-q8_0`       | `bge-m3`                 | 约 12.8 GB |

最高的两个档位对聊天和视觉都使用同一个多模态模型，因此你只需下载一套权重，而不是一个聊天模型再加一个单独的视觉副件。

{% hint style="warning" %}
**1 GB 和 4-8 GB 档位附带 `all-minilm:latest`，而 Memory Tree 无法使用它。** 它输出 384 维向量，而 Memory Tree 的磁盘格式固定为 1024，因此 memory embedding 会在嵌入时的维度检查中失败。这两个档位可用于本地聊天，并且在 4-8 GB 档位上可用于视觉，但如果你想要本地 Memory Tree 嵌入，请在应用预设后显式设置 `embedding_model_id = "bge-m3"` ，或者选择 2-4 GB 档位及以上。对齐这些预设已作为后续事项跟踪。
{% endhint %}

若要手动配置，这些键位于 `[local_ai]` 在 `config.toml`:

```toml
[local_ai]
runtime_enabled = true
opt_in_confirmed = true
provider = "ollama"                       # 或 "lm_studio"
chat_model_id = "gemma3:4b-it-qat"
vision_model_id = "gemma3:4b-it-qat"      # 必须支持视觉
embedding_model_id = "bge-m3"
```

将 `vision_model_id` 留空表示“无本地视觉”，这是一个有效配置。随后视觉请求会返回一条告诉你该设置什么的消息，而不是静默失败。

### 4. 将工作负载路由到它

开启本地 AI 并不会把所有东西都搬到设备上。你可以按工作负载选择提供方，格式如下 `ollama:<model>`:

```toml
chat_provider = "ollama:gemma3:4b-it-qat"
vision_provider = "ollama:gemma3:4b-it-qat"
embeddings_provider = "ollama:bge-m3"
```

完整的工作负载字段如下 `chat_provider`, `reasoning_provider`, `agentic_provider`, `coding_provider`, `vision_provider`, `memory_provider`, `embeddings_provider`, `heartbeat_provider`, `learning_provider`，以及 `subconscious_provider`。任何未设置、留空或设为 `云端` 的字段都会保留在默认路线。

#### 在聊天中附加图片还需要一个额外标志

`vision_provider` 会路由 **视觉工作负载** ——图片摘要以及 OCR/描述路径。它本身并不能让你在聊天或代理轮次中附加图片。

只有在解析出的聊天模型已知可以接受图片附件时，轮次才会重新载入这些附件；而对于本地模型，这个信息来自按模型登记表，而不是来自 `vision_provider`。在设置 → AI（自定义模型对话框）中设置模型的 **视觉** 标志，这会将其记录到 `model_registry`:

```toml
[[model_registry]]
id = "gemma3:4b-it-qat"
provider = "ollama"
vision = true
```

如果没有这个标志，图像会在发送前被剥离，模型只会根据文本作答——流畅自如，而且完全不会提示它其实从未见过那张图片。

另见 [本地 AI（可选）](/openhuman/zh/gong-neng/model-routing/local-ai.md) 用于更深入的运行时细节、LM Studio 设置和故障排除。

## 路线 B：使用你自己的密钥

BYOK 会保持路由、记忆、工具和代理框架完全不变，只是更换由谁来提供 token。你的密钥、你的账户、你的计费，没有 OpenHuman 推理费用。

### 1. 添加提供方

在桌面应用的 LLM 设置下添加你的密钥，它会把密钥存入操作系统的密钥环，而不是明文配置中。OpenHuman 为这些 slug 提供了预设，所以你不需要提供 endpoint：

`openai`, `anthropic`, `google`, `openrouter`, `orcarouter`, `groq`, `mistral`, `deepseek`, `together`, `fireworks`, `cerebras`, `xai`, `moonshot`, `gmi`, `huggingface`, `nvidia`, `zai`, `minimax`, `stepfun`, `kilocode`, `deepinfra`, `novita`, `venice`, `vercel-ai-gateway`, `sumopod`, `modelscope`

任何其他支持 OpenAI 兼容 API 的服务也同样可用：用你自己的 slug 和 endpoint 注册，它会以相同方式路由。

### 2. 将工作负载路由到它

提供方字符串遵循 `<slug>:<model>`，使用与本地路线相同的工作负载字段：

```toml
chat_provider = "anthropic:claude-sonnet-4"
reasoning_provider = "openai:gpt-5.1"
coding_provider = "deepseek:deepseek-coder"
vision_provider = "openai:gpt-5.1"
```

若要让一个提供方成为所有未固定项的默认值，请将 `primary_cloud` 设为它的 slug。所有留在 `云端` 上的工作负载都会解析到该提供方，而不是 OpenHuman 后端。

### 3. 检查模型是否支持该工作负载

BYOK 继承的是你的提供方能力，而不是 OpenHuman 的能力。在固定 `vision_provider`之前，请确认你指定的模型接受图像输入；在固定 `embeddings_provider`之前，请确认该提供方提供嵌入端点。并非每个聊天提供方都有。

## 混合路由

工作负载字段彼此独立，因此一种常见的隐私优先配置是让持续的后台工作留在设备上，而把需要高质量的轮次留给强大的云端模型：

```toml
# 本地：所有持续处理个人数据的内容
embeddings_provider = "ollama:bge-m3"
memory_provider = "ollama:gemma3:1b-it-qat"
heartbeat_provider = "ollama:gemma3:1b-it-qat"
subconscious_provider = "ollama:gemma3:1b-it-qat"

# 你自己的密钥：那些质量很重要的轮次
chat_provider = "anthropic:claude-sonnet-4"
reasoning_provider = "anthropic:claude-sonnet-4"
```

## 故障排除

**“no local vision model is configured”** 表示 `local_ai.vision_model_id` 是空的。将其设为支持视觉的模型并拉取，或者改指向 `vision_provider` 云端模型。

**“local vision model ... is not available”** 表示模型已配置但尚未拉取。运行消息中的 `ollama pull` 命令。

**视觉回答看起来合理，但描述的是错误的图片。** 你几乎肯定是在用仅聊天模型。请对照上面的能力表检查 `vision_model_id` 。当前版本会拒绝这种路由并回退到支持视觉的模型，所以这说明要么是旧版本，要么是本地路径之外的提供方。

**你选择的模型一直被重置回去。** 本地聊天模型 ID 会与受支持列表进行检查，未识别的 ID 会回退到默认值。请使用档位表中的某个 ID。

**嵌入因维度错误而失败。** Memory Tree 需要 1024 维向量。请使用 `bge-m3`.

## 另请参阅

* [本地 AI（可选）](/openhuman/zh/gong-neng/model-routing/local-ai.md)。运行时细节、LM Studio，以及选择加入标志。
* [自动模型路由](/openhuman/zh/gong-neng/model-routing.md)。提示如何按任务选择模型。
* [隐私模式](/openhuman/zh/gong-neng/privacy-and-security/privacy-mode.md)。在核心中强制仅本地推理。
* [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)。在你选择加入后，哪些内容会移到设备上。