# 模型服务与默认模型

连接 Provider、添加模型，配置对话、视觉、生图与后台用途。

## 本文要完成什么

把一个模型服务接入 Nexus，选定可用模型，再完成一次包含文件操作的任务。整个过程分为保存服务、添加模型、分配用途和验证任务四步。每一步都有自己的检查结果，前一步成功不等于后面全部可用。

如果管理员已经提供共享模型，先在模型列表中检查可用项。能选择模型但不能编辑服务时，向管理员确认配置，不必再创建同名服务。

## 准备三项信息

| 信息 | 从哪里取得 | 用来做什么 |
| --- | --- | --- |
| API 基础地址 | 模型服务的接口文档 | 指定请求发送到哪个服务 |
| API Key 或访问令牌 | 该服务的账号控制台 | 标识调用账号和计费范围 |
| 模型 ID | 该服务提供的模型列表 | 指定实际调用的模型 |

Nexus 登录账号与模型服务账号分开管理。网页聊天订阅也不等于已经取得 API 凭据。不要把登录密码、网页地址或模型的宣传名称填入上述字段。

Web 版由服务器调用模型。若模型只在你电脑的回环地址监听，服务器无法用自己的 `localhost` 访问它。先明确服务运行在哪台机器，再决定地址。

## 选择预设和接口协议

进入 **设置 → 供应商**，选择对应服务。预设已经提供固定端点时，沿用预设地址；使用自建网关或兼容服务时，按服务文档填写自定义配置。

| 接口协议 | 适用情况 | 不能据此推断的能力 |
| --- | --- | --- |
| Chat Completions | 服务明确提供此格式的聊天接口 | 名称兼容不代表支持全部工具参数 |
| Responses | 服务明确提供 Responses 格式 | 不代表当前运行引擎支持任意扩展字段 |
| Anthropic Messages | 服务提供 Messages 格式 | 模型名相似不代表与其他协议互换 |
| 图片生成协议 | 对应的图片生成服务 | 不能作为普通聊天模型使用 |

按接口格式选择，不按模型品牌猜测。一个网关可能同时提供多种协议，每种协议的基础地址或模型列表路径也可能不同。

## 填写并保存服务

| 字段 | 如何填写 | 修改时要注意 |
| --- | --- | --- |
| 服务名称与显示名称 | 使用能区分账号或网关的名字 | 显示名称用于识别，不是模型 ID |
| 基础地址 | 填写服务文档给出的 Base URL | 不要把完整聊天请求路径当作基础地址 |
| 模型列表路径 | 仅在当前预设允许自定义时填写 | 这是发现模型的接口，不是聊天接口 |
| 访问令牌 | 填入该服务签发的凭据 | 编辑时空白通常表示保留旧值 |
| 启用 | 决定服务是否参与后续使用 | 停用前检查正在使用它的 Agent 和任务 |

示例中的地址仅用于说明字段对应关系，不能直接调用。

```text
显示名称    团队测试网关
接口协议    Chat Completions
基础地址    https://models.example.com/v1
模型 ID     由这个网关实际提供的模型名称
```

保存后重新打开服务，核对地址、协议和启用状态。令牌不回显是正常的。只修改显示名称时，不需要把旧令牌重新填一遍。

## 发现模型或手动添加

服务提供模型发现接口时，可以同步模型列表。没有列出目标模型时，先确认该账号是否有权限使用，再用 **添加模型** 填写准确的 Model ID。手动添加窗口可选择添加后是否启用。

同步列表与手动添加解决的是“有哪些模型”。在列表中看到条目，仍需进行模型调用测试。若列表接口失败而服务支持手动指定模型，可以先按提供方给出的 ID 添加，再验证调用，不要反复修改聊天地址来修复模型发现接口。

## 模型能力和限制怎么填

模型设置中可以调整能力标记、上下文长度、最大输出长度和服务参数。

| 配置 | 含义 | 常见误解 |
| --- | --- | --- |
| 视觉输入 | 模型是否能接收图像 | 勾选不会让文本模型获得看图能力 |
| 工具调用 | 模型是否支持请求工具 | 一次文本测试不能证明工具流程可用 |
| 图片输出 | 模型是否能生成图片 | 与理解上传图片不同 |
| 推理能力 | 声明模型支持对应能力 | 不应替不支持的服务打开 |
| 上下文长度 | 单次上下文容量的配置值 | 不是整段历史永久保留的承诺 |
| 最大输出长度 | 一次输出的限制 | 不是目标篇幅，也不能超过服务限制 |
| 服务参数 | 传递服务需要的额外选项 | 必须是 JSON 对象，不接受数组或普通文本 |

自动识别结果不正确时才覆盖能力，数值依据提供方说明。填写更大的上下文值不会增加服务真实容量。服务参数没有特殊要求时保留空对象，不照搬其他提供方的参数。

## 分配默认用途

![真实桌面版常规设置中的四类默认模型](/images/docs/settings-general.png)

在 **设置 → 常规** 中配置默认对话、生图、视觉理解和后台任务模型。先让对话模型工作，再配置需要的其他用途。

- 默认对话模型用于未明确指定模型的 Agent；Nexus 主智能体跟随此选择。
- 视觉理解模型用于主模型无法看图时所需的视觉处理。
- 默认生图模型用于未指定服务的图片生成。
- 后台任务模型供标题、摘要等基础任务优先使用。

普通 Agent 可以指定自己的模型，会话也可能有明确选择。更改全局默认后，检查实际会话显示的模型，在下一轮验证。不要用正在执行的一轮判断新配置是否生效。

## 完成三次验证

1. 在供应商页测试服务，确认网络和认证可用。
2. 对一个具体模型进行测试，确认 Model ID、授权和额度可用。
3. 打开目标 Agent，执行下面的小任务。

```text
在当前工作区创建 model-check.md，写入一行“模型与工具验证通过”。
再读取该文件，回复实际读到的内容和文件位置。
```

若任务等待审批，按卡片核对文件名后允许本次。打开生成文件，确认存在且内容正确。服务测试和任务都可能产生模型费用。

## 修改或停用前检查依赖

先看服务被哪些 Agent 使用，再检查默认模型和定时任务。替换服务时，先验证新服务，再迁移使用者。删除条目不能解决旧任务里的错误模型选择。

出现保存结果待确认时，先刷新读取状态。保存成功但测试失败，通常不意味着配置自动回滚。按[模型排错](/docs/model-troubleshooting)确定失败阶段后，每次只改一个因素。