多步管道把单一 event_name 流程扩展为初始 AI 调用之后最多 6 个事件 的有序序列。
流程
- 你的应用对管道工作流调用
POST /v1/ai/async（模型页 = 初始 AI）。 - ModelRiver 自动推进已配置的事件：
- 后端步骤 — Webhook + 等待
POST /v1/callback/:channel_id - Callback AI 步骤 — 内联运行另一个工作流的模型与设置
- 后端步骤 — Webhook + 等待
- 最终后端步骤完成后 → WebSocket
status: completed
步骤数据约定
latest_data 合并规则
| 之后 | 规则 |
|---|---|
| 初始 AI | latest_data = ai_response.data |
| 后端回调 | latest_data = Map.merge(latest_data, callback.data) |
| Callback AI 步骤 | latest_data = target_workflow_ai_response.data（替换） |
customer_data
从原始异步请求设置一次，之后不会被覆盖。会包含在每一次 Webhook 中。
目标工作流输入
带有关联工作流的中间步骤会收到一条 JSON 用户消息：
JSON
1{2 "pipeline_input": { "...": "当前步骤的 latest_data" },3 "customer_data": { "...": "..." },4 "event_name": "summarize",5 "step_index": 16}请把目标工作流（例如 ticket_summarizer）配置为解析 pipeline_input。
Hello 管道示例
| 组件 | 名称 | 作用 |
|---|---|---|
| 管道工作流 | ticket_pipeline | 主 AI 分流 |
| 辅助工作流 | ticket_summarizer | 总结结构化输出 |
| 事件 1 | enrich | 后端 — 丰富工单数据 |
| 事件 2 | summarize | Callback AI → ticket_summarizer |
| 事件 3 | finalize | 后端 — WebSocket 前的最终回调 |
Webhook 信封（附加字段）
JSON
1{2 "type": "task.ai_generated",3 "event": "enrich",4 "channel_id": "...",5 "step_index": 0,6 "total_steps": 3,7 "step_type": "backend",8 "pipeline": { "workflow_name": "ticket_pipeline", "step_name": "enrich" },9 "ai_response": { "data": { "...": "latest_data" } },10 "callback_url": "https://api.modelriver.com/v1/callback/...",11 "callback_required": true,12 "customer_data": { "ticket_id": "123" }13}回调响应
中间步骤：
JSON
1{2 "status": "step_received",3 "step_index": 0,4 "next_step": "summarize"5}最终步骤：
JSON
1{2 "status": "completed",3 "channel_id": "..."4}WebSocket 状态
| 状态 | 含义 |
|---|---|
ai_generated | 初始 AI 完成 |
step_ready | 正在等待第 N 步后端回调 |
step_completed | 已收到后端回调，继续推进 |
callback_ai_completed | 关联工作流 AI 步骤完成 |
completed | 管道结束 |
配额
每个生产环境的 callback_ai 步骤会计入组织配额（通过 primary_req_id 挂在主请求日志下）。测试模式与演练场请求不计入。
错误码
| 代码 | 何时出现 |
|---|---|
step_already_completed | 幂等重复回调（200） |
step_index_mismatch | 回调步骤不匹配（409） |
pipeline_quota_exceeded | 管道中途配额超限（WS） |
step_ai_failed | Callback AI 提供商错误（WS） |
callback_timeout | 后端步骤超时（WS） |
仅有 event_name、没有 workflow_events 行的旧工作流仍可照常使用。