AI 渠道、场景与任务生命周期
服务商、服务商场景与场景如何组合,积分价格如何解析,以及任务与对话从请求到结算的运行过程。
Kernlift 中的 AI 通过配置接入。你在管理后台描述上游 API,把命名场景暴露给产品,每次调用都以积分定价并在账本中结算。配置方法见接入 AI 服务商和路由场景并设置定价。
三层配置
| 概念 | 是什么 | 示例 |
|---|---|---|
| 服务商(渠道) | 一个上游 API 账号:基础 URL、API Key、请求模板、结果返回方式以及响应解析方式 | openai |
| 服务商场景 | 服务商下的一个具体模型或端点,带有自己的请求覆盖项和价格 | OpenAI 协议下的 gpt-4o-mini |
| 场景 | 产品按代码请求的对象,带有输出类型,路由到一个服务商场景 | chat、image-creation |
调用方只指明场景。由于场景路由到一个服务商场景,你可以更换 image-creation 背后的模型而不改动任何调用方。对话默认使用 chat 场景,除非请求指定其他场景。任务通过 POST /api/<scene>/generate 发起。
场景只能路由到输出类型相同、处于启用且就绪状态的服务商场景,输出类型为 text、image、video 或 audio。服务商场景在缺少其设置所需的端点、定价、协议与模型 ID、轮询 URL 或 Webhook 密钥时,不算就绪。
价格如何解析
每个服务商场景有一种定价模式:
| 模式 | 计费依据 | 典型用途 |
|---|---|---|
fixed | 每次调用的成本 | 固定尺寸的单张图片 |
rules | 请求参数,按组合或数值步长 | 图片尺寸、视频时长 |
tokens | Token 用量,统一费率或输入、输出分开的费率 | 文本模型与对话 |
成本以你的币种填写,并按积分单价换算为积分。用户支付的价格是积分成本乘以加价后向上取整,且不低于成本。加价依次取自服务商场景、服务商、默认规则。
换算发生在保存服务商场景时,结果会被保存下来。之后修改积分单价不会重新定价已有的服务商场景,除非逐个重新保存。
任务如何运行
- 任务由服务端函数或
POST /api/<scene>/generate发起,受ai.tasks.create限流约束。未指定场景时由任务类型选择。 - 解析场景、其路由的渠道以及该媒体类型下启用的服务商场景,并计算积分价格。
- 根据模板渲染请求 URL、请求头和请求体。
- 在积分账本中冻结价格,任务以
queued状态保存,并附带渠道、价格和脱敏请求的快照。 - 调用服务商,并用渠道的解析器和状态映射读取响应。
- 结果决定冻结如何结算:
| 服务商状态 | 任务 | 积分 | 另外 |
|---|---|---|---|
| 成功 | succeeded | 扣除 | 输出 URL 被复制到用户的 /generated 存储目录;写入一条 pass 安全报告 |
| 失败 | failed | 退还 | 写入一条 warn 安全报告 |
| 排队或运行中 | running | 保持冻结 | 等待 Webhook 或轮询 |
每次状态变化都会在任务时间线上追加一条事件。用户只能读取自己的任务。管理后台可以看到全部任务。
结果模式
图片、视频和音频服务商往往稍后才完成,所以每个渠道要选择结果如何到达。
| 模式 | 结果如何到达 |
|---|---|
sync | 在调用的响应中。文本始终是 sync |
polling | 客户端通过 GET /api/status 读取任务且已过轮询间隔时,查询状态 URL。没有后台定时器 |
webhook | 服务商或其前置中转服务向 /api/ai/channels/webhook/<provider code> 推送 |
schema 还接受 webhook_or_polling,但后台表单只提供直接响应、状态轮询和 Webhook 推送三种方式。
Webhook 必须指明任务,并带有 x-ai-signature 请求头:用渠道的 Webhook 密钥对原始请求体计算的十六进制 HMAC-SHA256。大多数服务商并不这样签名,所以通常的做法是放一个小型中转服务,校验服务商自己的签名后重新签名。渠道或场景与任务不匹配的回调会被拒绝。配置方法见接收异步结果。
对话如何运行
POST /api/chat接收 AI SDK UI 消息,并以流式返回包含文本和推理部分的回复。- 保存会话和用户消息。
- 解析价格、冻结预估金额,并通过服务商场景的协议运行模型。
- 流结束后,按上报的 Token 用量重新定价并扣除。出错时退还冻结,并以
error状态保存助手消息。
| 协议 | 说明 |
|---|---|
openai | 兼容 OpenAI 的 chat completions。API Key 是服务商请求头中的 bearer token |
gemini | Google Generative AI。Key 取自 x-goog-api-key、x-api-key 或 bearer token |
edge_inference | 通过 AI 绑定调用 Cloudflare Workers AI;没有该绑定时不可用 |
image_generation | 仅用于任务;对话路径会拒绝 |
任务直接调用渲染后的请求 URL,所以协议和模型 ID 只影响对话。
为什么这样设计
- 每个服务商无需写代码。 任何返回 JSON 的 HTTP API 都可以用模板、JSON 路径和状态映射来描述。只有新增对话协议才需要代码。
- 不使用环境变量中的密钥。 环境中的
OPENAI_API_KEY等变量会被忽略。只使用保存在服务商上的密钥。 - 未配置就不运行。 模板不自带任何服务商或场景。在场景路由到就绪的服务商场景之前,任务会以不可用错误失败、不扣任何积分,
/setup中 AI 渠道显示未就绪。