模型服务接入原理：三种原生 API 格式与通用套路

机器人必须有模型才能说话。这一页讲清楚接入机制的底层逻辑，弄懂之后接任何服务商都是同一套动作。

三种原生格式

系统适配了三种 API 格式，这是全部接入体系的基石：

1. OpenAI 格式：事实上的行业标准。除了 OpenAI 自家，DeepSeek、Moonshot、GLM、Qwen、MiniMax、OpenRouter 以及绝大多数聚合服务都提供 OpenAI 兼容接口
2. Google GenAI 格式：接 Gemini 系列模型用
3. Anthropic 格式：接 Claude 系列模型用

推论：一个服务商只要提供这三种格式之一的接口，就能接进来。反过来，界面里那些「OpenAI Compatible」选项，就是给所有兼容服务准备的通用入口。

一个服务商的三样东西

不管接哪家，配置表单要填的核心就三样：

• API Base URL：服务的基础地址，通常在服务商文档的「接口文档」或「OpenAI 兼容」章节能找到。注意很多服务的地址要带 /v1 结尾
• API Key：在服务商控制台创建，相当于密码
• 模型名称：要调用的具体模型 ID，部分服务支持拉取列表自动选

配置入口与生效逻辑

WebUI 左侧「模型提供商」→「对话」标签页，点「新增」选格式类型。填写保存后点「保存并获取模型」拉取模型列表，给想用的模型点 + 启用。

模型接进来不等于机器人用它——还要到「配置文件」页，在「AI → 模型 → 对话模型」里把刚添加的模型设为当前使用项，保存配置。提供商是弹药库，配置文件才是枪。这个双层结构后面反复用到：换模型只动配置文件，弹药库里可以囤一堆候选。

Key 的两种进阶用法

• 环境变量加载（v4.13.0 起支持）：API Key 一栏填 $环境变量名称，如 $DEEPSEEK_API_KEY，程序从环境里读真实值。密钥不落配置文件，适合部署脚本化或多人协作的场景
• 连通性测试：模型旁有测试按钮，保存后先测一发，省得去群里发消息才发现 Key 是错的

填错了会怎样

最常见报错是 API 返回的 completion 无法解析，九成源于 Base URL 少了 /v1、Key 失效或余额用尽。逐项排查清单在模型 API 报错。下一页用 DeepSeek 完整走一遍全流程。