BillionMail 怎么配置 AI 模型供应商（OpenAI 兼容接口）并验证可用性-二趣网

BillionMail 怎么配置 AI 模型供应商（OpenAI 兼容接口）并验证可用性

【免费下载链接】BillionMailBillionMail gives you open-source MailServer, NewsLetter, Email Marketing — fully self-hosted, dev-friendly, and free from monthly fees. Join the discord: https://discord.gg/asfXzBUhZr项目地址: https://gitcode.com/GitHub_Trending/bi/BillionMail

如果你的 BillionMail 已经自托管部署完成，接下来想接一个大模型来用它的 AI 能力（例如用 AI 创建邮件模板），需要先在管理端把 AI 模型供应商配置好并确认连接可用。BillionMail 的 AI 功能不内置任何厂商的 Key，而是让你自己提供 BaseURL 和 API Key；只要对方的服务暴露了 OpenAI 兼容的/models接口（请求带Authorization: Bearer <key>请求头、响应为data数组且每项含id字段），就可以作为供应商接入。本文覆盖从添加/配置供应商、执行连接测试，到确认模型列表可用的完整路径。

先了解供应商配置是怎么存储的

每个供应商在服务器上对应一个目录，配置文件为conf/supplier/<SupplierName>/config.json，同目录下的models.json保存该供应商的模型列表。仓库里conf/supplier/template/下预置了 OpenAI、DeepSeek、Gemini、Anthropic 等供应商模板，例如 OpenAI 模板配置，核心字段是：

{ "supplierTitle": "OpenAI", "supplierName": "OpenAI", "baseUrl": "", "baseUrlExample": "https://api.openai.com/v1", "isUseUrlExample": true, "apiKey": "", "status": true, "sort": 1 }

其中baseUrl和apiKey默认是空的，这正是你要填的两个值（supplier.go 中的SyncTemplateToConfig会在首次启动时把模板同步到conf/supplier/，之后管理端的修改写回的就是这份副本）。

一个供应商只有在status为true且baseUrl、apiKey都非空时才会被视为激活；模型列表里的每个模型也只有在供应商激活时才标记为可用。如果模型条目没写max_tokens，系统按 8192 处理。

在管理端添加或配置供应商

路径一：配置内置供应商（如 OpenAI）

选中 OpenAI，填写 BaseURL 和 ApiKey 后保存。前端会调用POST /api/askai/supplier/set_supplier_config，Body 为：

{ "supplier_name": "OpenAI", "base_url": "https://api.openai.com/v1", "api_key": "你的 API Key" }

base_url以 OpenAI 模板里的baseUrlExample（https://api.openai.com/v1）为参考格式；换成其他 OpenAI 兼容服务时，填该服务对应的 base 地址即可。保存成功后前端会自动把供应商状态置为开启，并刷新模型列表。

路径二：新增自定义供应商

点击 Add Provider，弹窗里四个字段全部必填：supplierTitle（显示标题）、supplierName（名称，同时决定conf/supplier/下的目录名）、BaseURL、ApiKey。点击 Confirm 时，前端会先调用连接测试接口，测试通过才会调用POST /api/askai/supplier/add_supplier落盘；测试失败则不会创建。

连接测试是怎么验证可用性的

所有路径最终的验证手段都是测试接口POST /api/askai/supplier/testing，Body 为supplier_name、base_url、api_key。按 supplier.go 中Testing函数的实现，它依次做三项检查：

协议检查：base_url必须能解析且使用http或https协议，否则返回invalid base URL format/base URL must use http or https protocol；
可达性检查：对base_url发一次 HEAD 请求（3 秒超时），请求失败则返回base URL accessibility test failed；
API Key 校验：向<base_url>/models发 GET 请求，请求头带Authorization: Bearer <api_key>（15 秒超时）。响应 200 或 404 都视为 Key 校验通过；401 返回invalid API key；其他状态码返回unexpected API response: <状态码> <状态文本>。

全部通过时接口返回成功消息Supplier connection successful。注意第 3 步里 404 也算通过——有些兼容服务的/models路径不同，只要不是 401 就不会被这一步拦下。

如果你想绕开界面直接用接口核对（例如排查问题），可以先登录管理端拿到访问令牌，再请求：

curl -X POST 'http://<管理端访问地址>/api/askai/supplier/testing' \ -H 'Content-Type: application/json' \ -H 'Authorization: <管理端登录后的访问令牌>' \ -d '{ "supplier_name": "OpenAI", "base_url": "https://api.openai.com/v1", "api_key": "你的 API Key" }'

其中<管理端访问地址>、<管理端登录后的访问令牌>、api_key换成你自己的实际值。所有/api/askai/路由都挂在 JWT 与 RBAC 中间件之后（见 cmd.go 中的/api路由组），未登录请求会被拦下。

验证模型列表是否就绪

连接测试通过后，请求POST /api/askai/supplier/models（Body 带supplier_name）获取模型列表，管理端页面上也会同步刷新。这里有一个自动拉取机制：如果该供应商的models.json为空且配置了 BaseURL 与 API Key，后端会直接请求<base_url>/models，把返回的data数组里每个id写成一个模型条目（默认max_tokens8192、能力标记llm、状态开启），保存进conf/supplier/<SupplierName>/models.json。

模型拉不到时，可以按上面的测试流程逐项对号：URL 协议不对、HEAD 请求不通、Key 返回 401，对应三种不同的报错信息。也可以在页面上用POST /api/askai/supplier/status查看整体配置状态（返回is_configured字段，有任一可用模型即为true）。

模型管理还有几个可选操作，都在前端控制器里对应到具体接口：手动添加模型（/api/askai/supplier/add_model，需给title、model_id、max_tokens、capability）、修改模型标题/能力/参数（set_model_title、set_model_capability、modify_model）、按模型启停（/api/askai/supplier/set_model_status）。自定义能力取值参考接口定义中的说明：llm,vision,tools,text-to-image。

确认 AI 功能真正可用

配置完成后有一个直接的判断方式：管理端里依赖大模型的功能（如 AI 模板）在未配置可用模型时会提示“当前并未配置AI大模型，您无法使用AI模型创建邮件模板”，以及“要使用此功能，您需要先集成AI模型”（见中文语言包中的aiConfigurationInvalid/aiIntegrationWarning）。当这个提示消失、对应功能能发起请求，说明供应商配置已经对业务生效。

最后两点边界：供应商的 BaseURL 或 API Key 任一为空时无法开启状态开关（set_supplier_status会直接报错supplier configuration is incomplete, cannot set status）；删除供应商（/api/askai/supplier/remove_supplier）会删掉整个conf/supplier/<SupplierName>/目录，但系统内置的模板供应商不允许删除，会返回Cannot delete the system's built-in model supplier.。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析