接入 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 的对话 APItextOpenAI 协议、Base URL、API Key、模型 ID
Google GeminitextGemini 协议、Base URL、API Key、模型 ID
Cloudflare Workers AItext边缘推理 和模型 ID;只在配置了 ai 绑定的 Workers 上可用
返回 JSON 的 HTTP API(图片、视频、音频)image、video、audio接口地址、请求参数、结果获取方式和响应解析

在模型服务商准备凭据

厂商适用场景
OpenAIOpenAI 协议文本生成
Google GeminiGemini 协议文本生成
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 场景。检查 路由状态、状态 和 输出类型。

参考

下一步