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

# 1.5 配置模型与密钥

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

## 1. 打开模型配置

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

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

首次仅配置一个可用的模型提供方、原默认尚无密钥时，Teloa 会自动初始化默认模型，空白会话可以直接使用它。已有有效默认和本人明确选择的模型会保留；配置多个提供方时，请在会话模型选择器中确认当前选择。群内自动路由使用当前默认模型。

[![模型提供商的空白凭据表单；不表示已经连接或完成调用。](https://docs.teloa.ai/v/0.2.6/assets/screenshots/model-settings-024.0562e27d2b4e.png)](https://docs.teloa.ai/v/0.2.6/assets/screenshots/model-settings-024.0562e27d2b4e.png)

*0.2.4 真实界面，示例数据。模型提供商的空白凭据表单；不表示已经连接或完成调用。*

## 2. 验证一次回应

新建通用对话，输入：

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

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

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

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

## 本地聊天模型：Ollama

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

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

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

## 语音识别与播报

新安装默认使用本地 SenseVoice 进行语音识别，默认播报服务为 MiniMax；已保存的识别来源保持原选择。在 **设置 > 语音服务** 点击 **下载并准备本地识别**，进入原生准备页，核对下载来源和大小后再确认。准备页提供下载进度、取消、校验及失败重试；打开页面不会自动下载或录音。

MiniMax 播报需要在同页配置语音 API Key、模型与音色，再明确点击试听。语音凭据与聊天模型配置分别管理；保存播报配置不会切换识别来源。本地识别无需语音 API Key。首次通话还需要允许浏览器使用麦克风。

## 本地检索模型

检索模型负责把资料整理为可搜索的索引，不负责聊天回答。进入 **设置 > 本地模型**，在检索模型区域选择并准备；资料页的本地检索提示也可带你进入同一设置：

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

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

EmbeddingGemma 2 准备页提供 Ollama 官方安装入口。安装并启动后点击 **刷新状态**；若准备失败，检查服务、版本及模型，再点击 **重试准备** 并重新核对确认页。Teloa 不会代为启动系统中的 Ollama。

索引与嵌入在部署设备上完成，检索摘录仍可能发送给当前会话使用的远程聊天模型。可搜索范围与来源检查见[准备和使用资料](https://docs.teloa.ai/v/0.2.6/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 能连接 |
| 对话成功，工具任务失败 | 检查模型工具调用能力、员工授权与具体执行记录 |

会话使用已配置的所选模型。其他模型及内网模型应按当前智能体引擎实际支持的情况配置并单独验证；本指南不承诺任意兼容地址都能无改动工作。

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

[![本地模型与检索设置；图中 Ollama 尚未连接，检索尚未启用。](https://docs.teloa.ai/v/0.2.6/assets/screenshots/local-models-024.8ae5acc6dfb0.png)](https://docs.teloa.ai/v/0.2.6/assets/screenshots/local-models-024.8ae5acc6dfb0.png)

*0.2.4 真实界面，尚未准备模型或填写凭据。*

[![本地 SenseVoice 准备与 MiniMax 播报分别配置；图中未填写语音密钥。](https://docs.teloa.ai/v/0.2.6/assets/screenshots/voice-settings-024.8cf54b0fa87b.png)](https://docs.teloa.ai/v/0.2.6/assets/screenshots/voice-settings-024.8cf54b0fa87b.png)

*0.2.4 真实界面，尚未准备模型或填写凭据。*