接入 AI 服务商
完成后,上游 AI 账号及其模型保存在后台,可以路由到你的场景。
Provider 对应一个上游 API 账号,例如 OpenAI、Gemini、Cloudflare Workers AI,或任何返回 JSON 的 HTTP API。Provider 场景是 Provider 下的一个具体模型或接口。两者都在 设置 → AI 配置 中配置,不需要改代码,也不需要环境变量。
准备工作
- 供应商账号、API Key,以及从供应商文档中查到的 API Base URL 和模型 ID。
- 拥有
ai.read和ai.write的管理员账号。
按供应商提供的能力选择接入方式:
| 供应商 | 输出类型 | 需要配置 |
|---|---|---|
| OpenAI 或兼容 OpenAI 的对话 API | text | OpenAI 协议、Base URL、API Key、模型 ID |
| Google Gemini | text | Gemini 协议、Base URL、API Key、模型 ID |
| Cloudflare Workers AI | text | 边缘推理 和模型 ID;只在配置了 ai 绑定的 Workers 上可用 |
| 返回 JSON 的 HTTP API(图片、视频、音频) | image、video、audio | 接口地址、请求参数、结果获取方式和响应解析 |
在模型服务商准备凭据
| 厂商 | 适用场景 |
|---|---|
| OpenAI | OpenAI 协议文本生成 |
| Google Gemini | Gemini 协议文本生成 |
| Cloudflare Workers AI | 通过 Workers 绑定运行文本模型 |
自定义 HTTP 图片、音频或视频接口按下文配置端点和结果解析。先从服务商取得真实响应,再填写解析路径。
添加 Provider
打开表单
进入 设置 → AI 配置(/admin/config/ai),打开 Provider,点击 添加 Provider。
标识 Provider
填写 显示名称 和 编码(例如 openai)。编码保存为小写加连字符,并会出现在 webhook 回调 URL 中。状态 选 启用。
设置基础请求
- 方法 和 Base URL:一般为
POST,以及 API 基础地址。OpenAI 协议下,对话接口路径会拼接在它后面。 - API key 密钥:供应商控制台里的 Key。以密钥形式存储,并在 请求 Headers 中自动添加一行引用它的 Authorization。之后编辑时留空即保留原密钥。
- 请求 Headers 和 请求参数:可选,每次调用都带上的请求头和请求体字段。值中可以使用
{{prompt}}、{{input}}和{{metadata.<name>}}。不要把 Key 直接写进请求头的值里。
选择结果获取和解析方式
文本始终是 直接返回。图片、视频、音频等稍后才出结果的供应商,选择 状态轮询 或 Webhook 推送,见 接收异步结果。
这类供应商还需要填写 上游任务 ID 路径、状态路径、结果路径、错误路径 和 事件 ID 路径(默认 $.id、$.status、$.output、$.error),并在 状态映射 中用英文逗号分隔列出哪些供应商状态值分别对应 排队中、运行中、成功、失败 和 已取消。粘贴一段真实响应,点击 测试解析 检查。
保存
保持勾选 使用系统默认价格,或取消勾选后为该 Provider 设置 基础成本积分 和 加价率。点击 保存,Provider 出现在列表中。
添加模型
描述模型
在 Provider 所在行点击 Provider 场景,再点击 添加 Provider 场景。在 Provider 场景 区块填写 Provider 场景编码、Provider 场景名称、输出类型 和 状态。
设置请求
在 Provider 场景请求 区块:
- 文本:选择 调用协议(OpenAI 协议、Gemini 协议 或 边缘推理),按供应商的命名填写 模型 ID,例如
gpt-4o-mini或gemini-2.5-flash。请求发往 Provider 的 Base URL。 - 图片、视频、音频:填写完整的 Provider 场景 endpoint,留空则使用 Provider 的 Base URL。只在这里补充该模型独有的请求头或参数,留空的区块继承 Provider。可在 请求预览 中点击 预览 查看渲染后的请求。
Provider 场景结果获取 保持 继承,除非这个模型的结果获取方式与该 Provider 的其他模型不同。
定价并保存
按 为 Provider 场景定价 在 Provider 场景计费 中选择 计费模式,然后点击 保存。
环境变量中的 Key 不会被读取
只使用 Provider 上保存的 Key,OPENAI_API_KEY 等环境变量不会被读取。
验证
在 Provider 场景列表中,路由状态 显示 可路由,或列出缺少的项:缺少 endpoint、缺少计费、缺少协议或模型 ID、缺少轮询 URL、缺少 Webhook secret。可路由的 Provider 场景就能在 场景路由 中选择了。pnpm validate:ai-channel 会检查渠道结构、响应解析和定价。
常见问题
对话报错 "AI channel ... is not configured"
Provider 的请求头中没有 API Key。在 Provider 上保存 API key 密钥。Gemini Provider 也可以添加 x-goog-api-key 请求头。对话对 OpenAI 读取 Bearer 令牌,对 Gemini 读取 x-goog-api-key、x-api-key 或 Bearer 令牌。
对话报错 "Provider scene chat protocol is not configured"
对话场景路由到的 Provider 场景没有设置调用协议或模型 ID。在该 Provider 场景上补齐。
边缘推理不可用
Workers AI 绑定只在 Cloudflare Workers 上、且 wrangler.jsonc 配置了 ai 绑定时存在。其他运行环境请使用 OpenAI 或 Gemini 协议,见 部署到 Cloudflare Workers。
场景路由中找不到该 Provider 场景
下拉框只列出输出类型与场景相同、已启用且可路由的 Provider 场景。检查 路由状态、状态 和 输出类型。