文档

后端管道工作流

在 AI 生成与最终响应之间执行自定义业务逻辑。在交付前对 AI 输出进行增强、校验和转换。

三段式流程

后端管道工作流会形成一个强大的处理管道：

  1. AI 生成：ModelRiver 使用你配置的供应商处理请求
  2. 你来处理：你的后端收到 AI 输出后执行自定义逻辑，例如数据库更新、工具调用、校验或增强
  3. 最终响应：你回调 ModelRiver，ModelRiver 再把最终结果广播到 WebSocket 频道

什么时候使用

  • 根据 AI 输出执行工具 / 函数调用
  • 用数据库数据验证或增强 AI 响应
  • 实现带审批节点的多步工作流
  • 在返回用户之前触发通知、数据库写入等副作用

配置方式

1. 为工作流添加事件名

在控制台创建或编辑工作流时，设置 Event name 字段。

2. 处理 webhook 载荷

当带有 event_name 的工作流完成 AI 生成后，ModelRiver 会发送常规的 webhook 信封（callback_url、channel_id、data、timestamp）。其中 data 下的事件载荷与标准 webhook 有以下不同：

  • type 为 task.ai_generated（标准工作流的事件没有 type 字段）
  • event 为你自定义的事件名
  • ai_response 包含 AI 原始结果，位于 ai_response.data
  • callback_url 用于回调 ModelRiver
  • callback_required: true 表示 ModelRiver 正在等待你的回调

处理载荷前，请先校验 x-modelriver-signature 请求头。它签名的是 <x-modelriver-timestamp>.<data>，其中 <data> 是原始请求体中 data 值的原始 JSON 文本；详见签名验证。

3. 处理并回调

你的后端执行业务逻辑后，把增强后的数据回传给 ModelRiver。随后 ModelRiver 会把最终结果发回 WebSocket 客户端。

4. 前端接收最终结果

ModelRiver 会把最终结果推送到 WebSocket 频道。其中的 data 是 AI 输出与你回调 data 中字段合并后的结果，因此前端既能拿到 AI 生成的字段，也能拿到你补充的数据，适合构建多阶段处理体验。

超时处理

如果你的后端在 10 分钟 内没有完成回调，ModelRiver 会：

  1. 向 WebSocket 频道发送 callback_timeout 错误
  2. 在该请求的时间线中将后端回调记录为超时
  3. 关闭该频道，之后迟到的回调会被拒绝（返回 404 channel_not_found 或 410 channel_expired）

原始 AI 请求在日志中仍保持成功状态，只有回调这一步会被标记为超时。在多步骤管道中，每进入新的一步，这个 10 分钟窗口都会重新计时。

在 Playground 中测试

对于设置了 event_name 的工作流，Playground 会自动模拟完整后端管道流程。大约 1.5 秒后系统会生成一个模拟回调结果，便于你在正式上线前验证逻辑。

下一步