配置模型与接入能力
区分模型连接、工具调用和宿主接口的适用范围。
本页目录
区分三个独立环节#
- 软件账号授权：决定用户是否能使用对应软件和组件。
- 模型连接配置：决定请求发给哪个服务、使用什么模型和凭证。
- 组件业务接入：决定当前插件如何使用目标宿主已经开放的能力。
登录软件成功不代表模型连接完成，软件授权也不代表外部模型用量无限或费用已包含。
在设置中建立模型连接#
| 字段 | 核对内容 |
|---|---|
| 配置名称 | 便于区分用途，例如日常研究或测试连接；不要使用密钥作为名称 |
| Base URL | 服务提供的基础地址，核对协议、主机和路径前缀 |
| API Key | 服务凭证的有效期、额度与允许访问的模型 |
| 模型 ID | 请求中的准确 ID，不仅是界面展示名称 |
| 接入方式 | API、受支持的账号授权或其他实际入口；不可混用凭证 |
名称：测试模型连接
Base URL：https://api.example.com/v1
API Key：在本机软件设置中填写
模型 ID：按服务实际提供的标识填写以上是占位示例。不要把网页聊天地址填成 API 地址，也不要未经核对重复拼接 /v1 或消息路径。
分三层验证#
服务能否连通#
先检查域名、TLS、代理和网络。使用短请求验证，不拿完整比赛项目做第一次连接测试。
基础对话能否返回#
确认认证、模型权限和流式响应。基础聊天成功不等于工具、图片或长上下文都已经支持。
实际工具流程能否完成#
用一个最小测试项目验证读取材料、执行简单计算、保存结果和预览。工具调用协议不完整时，应该报告实际失败阶段，不能把缺少能力笼统显示为网络超时。
插件如何接入#
清单中的 ai 是能力需求声明，不会自动生成通用 api.chat()。第三方组件应核对目标宿主实际开放的调用方法、参数、事件和取消机制。
内置代码或研究组件可能依赖自己的业务 IPC，不能只复制一个名字到第三方插件里就认为可用。新增系统桥接时，应配套修改主进程、preload 和组件调用，确定最低宿主版本。
如果没有受支持的接入方法，组件要明确提示能力尚不可用，并向维护者提交接口需求；不能在公开源码中塞入作者自己的服务密钥代替用户配置。
失败分层处理#
| 表现 | 优先核对 | 处理方向 |
|---|---|---|
| 认证错误 | 凭证、填写位置和服务账号 | 核对配置，错误日志脱敏 |
| 权限或模型不可用 | 模型 ID、访问范围 | 确认目标账号支持该模型 |
| 频率或额度限制 | 服务余额、并发和限流 | 降低并发，按服务说明重试 |
| 路径不存在 | Base URL 和协议 | 一次调整一个因素 |
| 流式中断 | 代理、网络、上下文 | 保留已收到内容，先复现短请求 |
| 本地工具超时 | 环境、工作目录和启动阶段 | 按本地工具排查，不混同模型连接 |
日志、取消和数据保护#
记录模型 ID、阶段、状态码、耗时和经过脱敏的错误；不要记录 Key、Cookie、密码或完整敏感材料。取消后让旧运行身份失效，同时调用实际请求的取消机制。
切换模型不能让上一轮流式响应继续写入新任务。断网或调用失败时保留项目和已有产出，只更新本次操作的状态。