什么是事件驱动 AI？
事件驱动 AI 的核心是把“AI 生成”与“结果交付”拆开。你不再同步等待 AI 返回结果，而是发起一条异步请求，由 ModelRiver 在结果准备好后通知你的后端。随后你的后端执行自定义逻辑，例如写数据库、调用外部 API、做校验与增强，再回调 ModelRiver，最后由 ModelRiver 通过 WebSocket 把最终结果实时推送给前端。
整个流程分三步：
- AI 生成：你的应用调用
POST /v1/ai/async，并使用带有event_name的工作流。ModelRiver 在后台处理请求。 - 你的后端处理：ModelRiver 把 AI 结果发送到你的 Webhook 端点。你的代码执行数据库写入、外部 API 调用、校验、增强等业务逻辑。
- ModelRiver 交付结果：你的后端把增强后的数据发送到
callback_url。ModelRiver 再把最终结果实时广播给已连接的 WebSocket 客户端。
为什么使用事件驱动方式？
| 优势 | 说明 |
|---|---|
| 非阻塞 | 前端无需同时等待 AI 生成和后端处理，用户可以立刻看到“处理中”的状态。 |
| 先处理再交付 | 在用户看到结果之前，你可以先验证 AI 输出、补充数据库数据、触发副作用。 |
| 可靠交付 | ModelRiver 负责 Webhook 的重试、超时和死信队列处理。 |
| 可观测 | 每一步都会记录在 Timeline 中：AI 请求、Webhook 投递、后端回调。 |
| 易扩展 | 可以同时处理成千上万条并发 AI 请求，而不会阻塞 Web 服务器。 |
它如何工作
┌──────────┐ POST /v1/ai/async ┌──────────────┐│ 你的应用 │ ─────────────────────────▶ │ ModelRiver ││ │ { workflow, messages } │ (AI 引擎) ││ │ ◀───────────────────────── │ ││ │ { channel_id, ws_token } │ │└──────────┘ └──────┬───────┘ │ │ │ 建立 WebSocket 连接 │ AI 在后台处理 │ (ai_response:{project}:{channel}) │ │ ▼ │ ┌──────────────┐ │ │ Webhook 投递 │ │ └──────┬───────┘ │ │ │ ▼ │ ┌──────────────┐ │ │ 你的后端 │ │ │ (webhook) │ │ └──────┬───────┘ │ │ │ │ POST callback_url │ │ { data, task_id } │ ▼ │ ┌──────────────┐ │ WebSocket 推送 │ ModelRiver │ │ ◀─────────────────────────────── │ (callback) │ │ { status: "completed", data } └──────────────┘ ▼┌──────────┐│ 前端界面 │ 渲染最终结果└──────────┘快速开始
- 创建一个启用了
event_name的工作流。 - 为项目配置 Webhook 端点。
- 前端调用异步 AI API，并使用返回的
channel_id与ws_token连接 WebSocket。 - 后端接收 Webhook，执行自定义逻辑后调用
callback_url。 - 前端通过 WebSocket 收到最终结果。
适合的场景
- AI 结果需要经过数据库查找或业务规则增强后才能展示
- 需要在人类审批之后再把内容交付给终端用户
- 想把 AI 生成与后续自动化流程拆开，以提高吞吐和可靠性
- 需要实时更新前端状态，但又不想让 HTTP 请求长时间阻塞
下一步
- 后端框架指南：查看 Next.js、Phoenix、FastAPI 等接入方式
- Webhooks：理解签名校验、投递和重试策略
- Client SDK：学习前端 WebSocket 实时接收方式