<!-- Canonical URL: https://ask.atlascloud.ai/zh-TW/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 提供檔案。

### 遷移測試應涵蓋哪些故障？

涵蓋重複與遺漏事件、速率限制、暫時錯誤、取消競態、輸出過期、承載內容格式錯誤和處理期間工作程序重新啟動。