> 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 提供动力的三种方式：托管订阅、你自己的提供方密钥（BYOK），或在你自己运行的运行时上的本地模型。它们各自对聊天、视觉和嵌入的支持情况，以及如何

OpenHuman 订阅是默认项，不是强制要求。推理可以来自三个位置中的任意一个，而且你可以针对每个工作负载混合使用它们。比如，你可以把嵌入本地运行，聊天用你自己的 Anthropic 密钥，而把视觉保留在托管路径上。

本页介绍如何配置这两个自有选项，以及每个选项实际能做什么。并不是每个本地模型都能看图。把仅聊天模型用于视觉工作，是最常见的“看起来已配置好、实际上却悄悄做错事”的情况。

## 三个路径一览

|                  | 托管（默认）           | BYOK 云端             | 本地（你运行的运行时）                |
| ---------------- | ---------------- | ------------------- | -------------------------- |
| **聊天与推理**        | 已包含              | 你的密钥，你的计费           | 是，质量随模型大小提升                |
| **视觉**           | 已包含              | 如果模型支持图像，则使用你的密钥    | 是，但仅限具备视觉能力的模型             |
| **嵌入**           | 已包含              | 如果提供商提供嵌入服务，则使用你的密钥 | 是， `bge-m3` 推荐             |
| **语音转文本**        | 已包含              | 你自己的密钥，通过语音提供商 slug | 没有本地 STT 引擎                |
| **文本转语音**        | 已包含              | 你自己的密钥，通过语音提供商 slug | Piper，如果你安装了它（`PIPER_BIN`) |
| **网页搜索**         | 已包含，无需密钥         | 使用你自己的 Exa 密钥       | 不适用                        |
| **推理数据离开你的机器**   | 是，到 OpenHuman 后端 | 是，到你选择的提供商          | 否                          |
| **需要管理的 API 密钥** | None             | 每个提供商一个             | None                       |

语音是独立于 LLM 工作负载字段进行配置的，这两部分很容易混淆。 `voice_providers` 保存第三方提供商定义（slug、端点、密钥、默认模型或语音）。编辑其中一个不会改变实际使用哪个提供商。活动路径单独设置：

* STT 读取 `stt_provider`，然后是旧的 `local_ai.stt_provider`，然后 `voice_server.stt_engine` ，当这两个都没有命名提供商时。
* TTS 读取 `tts_provider`，然后是旧的 `local_ai.tts_provider`，然后 `云端`.

没有本地 STT 引擎。语音转文本要么走托管代理，要么使用你自己的密钥调用第三方 API。TTS 有 Piper 这个本地选项。OpenHuman 不会安装 Piper。你需要自己安装二进制文件和语音，设置 `PIPER_BIN`，并设置 `tts_provider = "piper"`.

表格的最后一行只涉及推理数据。即使推理完全由你自己负责，登录、托管集成 OAuth、计费，以及媒体生成和托管网页搜索等托管功能，仍然会使用 OpenHuman 后端。仅仅运行本地模型，并不意味着没有任何内容会离开机器。如果你需要这个保证，请使用 [隐私模式](/openhuman/zh/gong-neng/privacy-and-security/privacy-mode.md)，它在 Rust 核心中强制走仅本地路径，而不是只依赖配置。

## 路径 A：本地模型

OpenHuman 不会安装运行时，也不会下载模型权重。你运行运行时（Ollama、LM Studio、MLX、OMLX 或其他兼容 OpenAI 的服务器），你拉取模型，然后 OpenHuman 调用该端点。下面的示例使用 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 维    |

两个陷阱：

* Gemma 3 按大小拆分。270M 和 1B 版本仅支持文本。视觉从 4B 开始。如果你选择 `gemma3:1b-it-qat` 用于视觉，你得到的是一个仅文本模型。
* `gemma3n` 不是 `gemma3`。尽管名字相似，Gemma 3n 在 Ollama 上是一个独立的、仅文本模型。它是一个不错的聊天模型，但不是好的视觉模型。

对于嵌入，优先选择 `bge-m3` （1024 维）。 `embeddings_provider` 为 `ollama:bge-m3` 会把 OpenHuman 自己的嵌入调用路由到你的机器。它不会迁移记忆，因为记忆引擎是在其自身一侧进行嵌入，因此召回仍会在记忆引擎运行的位置执行。这里涉及三个独立设置。这个字段负责路由 OpenHuman 的嵌入。 [隐私模式](/openhuman/zh/gong-neng/privacy-and-security/privacy-mode.md) 规定推理可以去往何处。你选择的记忆引擎决定记忆存放在哪里。

### 3. 将 OpenHuman 指向它

在桌面应用中，打开 **连接 > LLM > 添加提供商** ，并在 **本地运行时**下选择 Ollama（或 LM Studio 或 OMLX），或者添加自定义的 OpenAI 兼容端点。OpenHuman 会保存端点，开启本地运行时，并列出运行时报告的模型。你尚未拉取的模型不会显示。参见 [本地 AI](/openhuman/zh/gong-neng/model-routing/local-ai.md#adding-a-local-runtime-in-the-app).

如需手动配置，请使用 `[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. 将工作负载路由到它

添加本地提供商并不会把所有内容都搬到设备上。你要针对每个工作负载选择一个提供商字符串，例如 `ollama:<model>` （或 `lmstudio:`, `mlx:`, `omlx:`, `local-openai:`):

```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` 和 `learning_provider`。未设置、为空或 `云端` 会保持在默认路径。

#### 在聊天中附加图像还需要一个额外开关

`vision_provider` 路由视觉工作负载：图像摘要，以及 OCR 和描述路径。它本身并不会让你在聊天或 agent 回合中附加图像。

只有当聊天模型已知支持图像时，某个回合才会传递图像附件。对于本地模型，这种已知信息来自逐模型注册表，而不是来自 `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) 用于端点覆盖，以及其他运行时和故障排除。

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

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

### 1. 添加提供商

在桌面应用的 LLM 设置中添加你的密钥。它会存储在操作系统的钥匙串中，而不是明文配置里。OpenHuman 为这些 slug 提供预设，所以你不需要提供端点：

`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 和端点注册它，它就会以相同方式路由。

对于由私有或企业 CA 签名的 HTTPS 端点，请在自定义提供商编辑器中上传其 PEM CA 证书。OpenHuman 会信任该证书，用于此提供商的模型列表和推理请求。你也可以把 CA 安装到操作系统的信任库中；在 macOS 和 Linux 上， `SSL_CERT_FILE` 向核心进程提供一个 PEM 证书包。

在无头核心（`openhuman-core serve`）上，只有在存在后端会话或 TinyHumans API 密钥时，才会构建自定义云提供商。如果你运行核心时没有账户，请将端点设置为 `local-openai` 运行时：设置 `LOCAL_OPENAI_URL`，把密钥放入 `local_ai.api_key`，并将工作负载固定到 `local-openai:<model>`。参见 [没有 TinyHumans 账户的无头模式](/openhuman/zh/gong-neng/cloud-deploy.md#headless-without-a-tinyhumans-account).

### 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"
learning_provider = "ollama:gemma3:1b-it-qat"

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

## 故障排除

**你想要的模型没有提供，或者请求提示模型缺失。** 运行时没有它。执行 `ollama pull <model>` （或在 LM Studio 中加载它），然后重试。OpenHuman 不会拉取模型。

**视觉答案看起来合理，但描述的是错误的图像。** 你几乎肯定使用的是仅聊天模型。检查 `vision_model_id` 与上面的能力表。当前构建会拒绝这种路由并回退到具备视觉能力的模型，因此这说明你用的是较旧的构建，或是本地路径之外的提供商。

## 另请参见

* [本地 AI](/openhuman/zh/gong-neng/model-routing/local-ai.md)：受支持的运行时、端点和启用标志。
* [模型路由](/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)：在启用时，哪些内容会转到设备上。