<!-- Canonical URL: https://ask.atlascloud.ai/zh/replace-replicate-prediction-polling-and-webhooks -->

# 如何在现有应用中替换 Replicate 预测轮询和 Webhook？

> 在产品与模型 API 之间增加与服务商无关的异步任务记录。让经过验证的 webhook 或有边界的轮询工作进程更新同一个幂等终结器，统一生命周期状态，并把完成文件复制到应用的持久存储。

要替换 Replicate 的轮询和 webhook，可在应用与推理 API 之间加入与服务商无关的任务层。统一创建、状态、取消、完成事件和输出持久化，使产品其他部分不再依赖 Replicate 的预测对象或 URL。

不要只在产品代码里替换回调 URL。应先定义应用真正需要的异步契约。

## 记录现有行为

Replicate 的异步创建会返回预测 ID、生命周期状态和便捷 URL。应用可能轮询 `urls.get`、接收 webhook POST，或在支持时使用服务器发送事件。记录每条工作流所用路径，以及产品在各状态转换时的行为。

| Replicate 概念 | 应用层替代方案 |
|---|---|
| 预测 ID | 服务商任务 ID 加内部任务 ID |
| `starting`、`processing` | `queued`、`running` |
| `succeeded` | `completed` |
| `failed`、`canceled` | `failed`、`canceled` |
| `urls.get` | 适配器状态方法 |
| Webhook 载荷 | 统一完成事件 |
| 输出 URL | 应用拥有的持久化资产 |

将服务商原始状态与统一状态分开保存，以便在服务商生命周期细节不同时保留调试证据。

## 引入内部任务记录

调用新服务商之前先创建数据库记录：

```json
{
  "job_id": "job_01J...",
  "provider": "target",
  "provider_job_id": null,
  "state": "creating",
  "attempt": 1,
  "output_assets": []
}
```

在 UI、队列和通知中使用内部 `job_id`。创建成功后再附加服务商任务 ID。幂等键或创建令牌应防止网络重试启动两个付费任务。

## 用有边界的工作进程替代轮询

若目标 API 提供任务查询但没有 webhook，把轮询移到后台工作进程。使用带抖动的指数退避、截止时间和最大间隔。遇到任何终态都停止，取消状态也必须结束循环。

不要从浏览器轮询。服务端工作进程不受标签页关闭影响，也能集中管理速率限制并以事务方式保存状态变化。

## 用已验证事件替代 Webhook

若目标支持 webhook，处理器应保持精简：

* 解析前验证签名或共享密钥；
* 按事件 ID 或服务商任务 ID 加状态去重；
* 快速确认并把处理放入队列；
* 载荷不完整时查询权威任务对象；
* 接受乱序与重复投递。

Replicate 支持 start、output、logs 和 completed 等事件过滤器，目标服务商可能只发送终态事件。只在进度确有意义时重建进度展示，不要从稀疏状态中虚构精度。

## 使用同一条完成路径

轮询与 webhook 都应调用同一个幂等终结器。终结器锁定内部任务，确认服务商 ID，记录终态，把输出文件复制到持久存储，并只发送一次应用事件。

这样可避免 webhook 与最终轮询同时到达时重复通知。

## 在文件消失前持久化

Replicate 说明，通过 API 创建的预测输入和输出文件会在有限时间后自动删除。新服务商可能使用不同保留期或签名 URL 有效期。应把所有服务商 URL 当成交付方式，而非永久存储。

及时下载成功输出，验证内容类型和大小，按需扫描，存入应用控制的键，并保存校验和。向客户端提供你自己的稳定资产 URL。

## 测试故障与恢复

契约测试应覆盖创建响应延迟、重复或遗漏 webhook、轮询遇到 429 与 5xx、取消竞态、输出 URL 过期、载荷格式错误，以及任务执行中工作进程重启。

对安全输入以影子模式运行两个适配器，比较终态与资产数量，再逐步迁移少量生产流量。

## 总结

替代 Replicate 轮询和 webhook 的可靠方案，是内部异步任务契约，而不是散落在应用中的服务商回调。统一状态、保证终结幂等、立即持久化文件，并让已验证 webhook 或有边界的轮询器驱动同一条完成路径。

## FAQ

### 浏览器代码应直接轮询替代 API 吗？

建议使用服务端工作进程。它不受浏览器关闭影响，可以统一管理速率限制与重试，并一致地更新内部任务状态。

### 应如何映射 Replicate 的预测状态？

将服务商状态映射为 creating、queued、running、completed、failed 和 canceled 等精简内部生命周期，同时保留原始状态用于调试。

### 如何避免重复处理 webhook？

验证来源，按事件身份或任务加状态去重，并让 webhook 与轮询完成都经过同一个事务化幂等终结器。

### 新服务商没有 webhook 怎么办？

使用带指数退避、抖动、截止时间和全部终态处理的后台轮询器。

### 可以永久向用户公开服务商输出 URL 吗？

不要假设这些 URL 持久有效。应及时下载输出，并通过带有自有访问控制的应用资产 URL 提供文件。

### 迁移测试应覆盖哪些故障？

覆盖重复与遗漏事件、速率限制、临时错误、取消竞态、输出过期、载荷格式错误和处理期间工作进程重启。