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请求参数,按组合或数值步长图片尺寸、视频时长
tokensToken 用量,统一费率或输入、输出分开的费率文本模型与对话

成本以你的币种填写,并按积分单价换算为积分。用户支付的价格是积分成本乘以加价后向上取整,且不低于成本。加价依次取自服务商场景、服务商、默认规则。

换算发生在保存服务商场景时,结果会被保存下来。之后修改积分单价不会重新定价已有的服务商场景,除非逐个重新保存。

任务如何运行

  1. 任务由服务端函数或 POST /api/<scene>/generate 发起,受 ai.tasks.create 限流约束。未指定场景时由任务类型选择。
  2. 解析场景、其路由的渠道以及该媒体类型下启用的服务商场景,并计算积分价格。
  3. 根据模板渲染请求 URL、请求头和请求体。
  4. 在积分账本中冻结价格,任务以 queued 状态保存,并附带渠道、价格和脱敏请求的快照。
  5. 调用服务商,并用渠道的解析器和状态映射读取响应。
  6. 结果决定冻结如何结算:
服务商状态任务积分另外
成功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。大多数服务商并不这样签名,所以通常的做法是放一个小型中转服务,校验服务商自己的签名后重新签名。渠道或场景与任务不匹配的回调会被拒绝。配置方法见接收异步结果。

对话如何运行

  1. POST /api/chat 接收 AI SDK UI 消息,并以流式返回包含文本和推理部分的回复。
  2. 保存会话和用户消息。
  3. 解析价格、冻结预估金额,并通过服务商场景的协议运行模型。
  4. 流结束后,按上报的 Token 用量重新定价并扣除。出错时退还冻结,并以 error 状态保存助手消息。
协议说明
openai兼容 OpenAI 的 chat completions。API Key 是服务商请求头中的 bearer token
geminiGoogle 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 渠道显示未就绪。

相关文件

src/server/services/ai-workspace.service.ts
src/server/db/repositories/ai-workspace.repository.ts
src/routes/{-$locale}/admin/config/ai.tsx
src/components/ai/admin-ai-operations-workspace.tsx

下一步