---
title: 配置模型与密钥
description: 连接模型服务，验证真正完成一次模型调用。
lastVerified: 2026-10-18
---

# 1.3 配置模型与密钥

开始前，完成[本机启动](https://docs.teloa.ai/v/0.2.1/markdown/start/quickstart.md)。使用远程模型时，准备你有权使用的 API 密钥；使用本地模型时，准备相应运行服务与设备资源。远程调用费用由用户自行承担，社区版软件许可不包含模型额度。

## 1. 打开模型配置

进入 **设置 > 模型**，找到对应的模型提供方。Teloa 管理业务和员工关系，底层 DSH 配置页管理模型、密钥和运行环境。

在对应模型服务商下填写并保存密钥，再检查模型提供方、模型名称和运行配置是否匹配。不要将密钥写进员工职责、群消息、技能正文或普通资料。

[![模型设置中的 DeepSeek 提供方与空白 API 密钥输入框](https://docs.teloa.ai/v/0.2.1/assets/screenshots/model-settings.63c4d26e996a.png)](https://docs.teloa.ai/v/0.2.1/assets/screenshots/model-settings.63c4d26e996a.png)

*0.2.0-beta.3 界面，尚未填写密钥。填入你自己的密钥并保存；截图中的空白状态不代表模型已连接。*

## 2. 验证一次回应

新建通用对话，输入：

```text
请只回复“模型连接正常”。不使用工具，不访问资料。
```

收到回应后，再测试员工任务。页面能够打开、密钥已保存和模型能够执行任务，是三个不同的验证结果。

## 3. 检查员工使用的配置

若普通对话可用但员工任务失败，检查该员工的运行配置及错误提示。修改员工定义或工具授权前，先暂停员工；保存后恢复在岗，再用一项小任务验证。

## 本地聊天模型：Ollama

1. 在运行模型的设备上安装并启动 [Ollama](https://ollama.com/download)，进入 **设置 > 模型 > 本地模型**，检查服务状态与版本要求。
2. 核对目标 Ollama 地址、模型大小、磁盘与内存提示及许可，再点击 **下载** 并确认。可以查看进度或取消；Teloa 不会替你安装或启动 Ollama。
3. 下载并完成接入后，在会话或员工的模型配置中选择该模型，先按上文验证一次回应，再验证实际工具任务。已有但未收录的模型可选择 **作为未收录模型接入**，其能力仍需单独验证。

高级地址设置指向实际执行下载和推理的 Ollama 服务；填写其他设备地址时，模型与上下文会交给该设备。Docker 部署中的“本地”是部署服务器或容器可访问的服务，不能把容器内的回环地址当作浏览器所在电脑。根据部署方式配置可达地址。

**移除** 会断开模型接入，并删除确认框所示 Ollama 服务中的模型文件。员工可明确选择远程备用模型；仅在符合切换条件的故障下，最多尝试一次已选远程备用模型，未选备用则提示失败，不会自动改用其他模型。服务就绪、模型文件存在与实际完成任务是不同的结果；内存提示也是估算。

## 本地检索模型

检索模型负责把资料整理为可搜索的索引，不负责聊天回答。进入 **资料 > 本地文件** 的检索区域，打开 **检索设置**，选择模型并按提示准备：

| 模型 | 准备方式 |
| --- | --- |
| Qwen3 Embedding 0.6B | 核对模型、分词器及运行组件的下载信息，选择可用来源并明确确认下载；由 Teloa 在部署设备上运行，无需 Ollama |
| EmbeddingGemma 2 | 先在运行 Teloa 的设备安装并启动符合页面版本要求的 Ollama，再确认拉取并准备模型；设备不支持时改选其他检索模型 |

仅启用检索或打开设置不会自动下载；按确认页完成准备后选择 **使用此模型**，再将需要的资料加入本地检索。首次准备需要网络和磁盘空间，过程可取消或失败后重试。Docker 或服务器部署时，这些文件和计算位于部署环境，不在浏览器中运行。

索引与嵌入在部署设备上完成，检索摘录仍可能发送给当前会话使用的远程聊天模型。可搜索范围与来源检查见[准备和使用资料](https://docs.teloa.ai/v/0.2.1/markdown/guides/knowledge.md#%E5%BC%80%E5%90%AF%E6%9C%AC%E5%9C%B0%E7%B4%A2%E5%BC%95%E4%B8%8E%E6%A3%80%E7%B4%A2)。

## 常见问题

| 现象 | 处理方式 |
| --- | --- |
| 认证失败 | 检查已保存的密钥是否有效、是否属于当前服务商；重新保存后重试 |
| 模型不存在或不支持 | 使用该提供方实际开放的模型标识；检查运行配置是否仍引用旧模型 |
| 额度不足或限流 | 到模型服务商确认额度和调用限制；Teloa 许可不会自动补充 Token |
| 网络失败 | 从运行 Teloa 的设备检查模型服务连接；浏览器能联网不等于 Teloa 能连接 |
| 对话成功，工具任务失败 | 检查模型工具调用能力、员工授权与具体执行记录 |

默认组合面向 DeepSeek 服务。其他模型及内网模型应按当前智能体引擎实际支持的情况配置并单独验证；本指南不承诺任意兼容地址都能无改动工作。

外部模型会接收任务所需的授权上下文。关于数据位置，见[隐私与权限](https://docs.teloa.ai/v/0.2.1/markdown/deploy/privacy.md)。