# 讓 pipeline 變聰明的那個 API，也是最容易卡死的那個點

- URL: https://justfly.idv.tw/%e8%ae%93-pipeline-%e8%ae%8a%e8%81%b0%e6%98%8e%e7%9a%84%e9%82%a3%e5%80%8b-api%ef%bc%8c%e4%b9%9f%e6%98%af%e6%9c%80%e5%ae%b9%e6%98%93%e5%8d%a1%e6%ad%bb%e7%9a%84%e9%82%a3%e5%80%8b%e9%bb%9e/
- 日期: 2026-06-09
- 分類: WEB&RIA
- 標籤: api, node.js, 神島

![讓 pipeline 變聰明的那個 API，也是最容易卡死的那個點]

##### 靜態到動態，那一步很小，風險很大

台灣早餐店阿姨五點多就開始備料，菜單大致固定，但今天食材有什麼就微調什麼。市場不開的話她不會關店，就照昨天的做。這個邏輯其實比很多 pipeline 設計都成熟。

##### 技術環境

Node.js pipeline，主路徑中段插入一個對外部文化事件 HTTP API 的即時呼叫，目的是撈素材給後續 LLM 節點用。API 回應以 stream 分段傳回，需用 `Buffer.concat` 逐 chunk 拼接後解析 JSON。原始設計未設 `timeout`，也未實作 fallback 路徑——呼叫懸掛或格式損壞，後續節點直接等或拿到爛 input。問題模式與框架無關，任何在主路徑同步等待外部服務、且沒有隔離設計的節點都會複現。

原本的流水線靠靜態 prompt 控制輸出場景。每次跑出來的結果類似，久了可預測，穩定但無聊。為了讓輸出多變，在流水線中段加了一個對外部服務的即時 API 呼叫，目的是撈最新的在地文化事件當素材——輸出確實鮮活了，但同時多了一個可以卡死整條 pipeline 的節點。

這個改動本身沒有問題。問題是在加入「聰明」的同時，沒有同步設計「不聰明時怎麼辦」。

##### 外部服務的本質：你不控制它

外部服務不受控。網路慢、服務暫停、回應格式突然改版，都不是你能預防的事。把一個你不控制的節點直接嵌進 pipeline 主路徑，等於把系統的穩定性部分委託給別人。

這個呼叫如果沒有 timeout，慢回應會讓 pipeline 在這個節點懸掛，後面所有工作都等著。分段回傳的資料如果沒有正確用 `Buffer.concat` 拼接，靜默地拿到的可能是截斷或損壞的內容，錯誤不會明顯報出來，只會讓輸出莫名其妙。最糟的情況是：你以為 pipeline 在跑，其實它卡在那個 API 呼叫等到超時。

##### 錯誤傳染鏈（時序）

```
— 場景 A：無 timeout，服務慢或無回應 —

Pipeline Runner         External Event API         LLM Node
      |                        |                      |
      |── GET /cultural-events >|                      |
      |                        |                      |
      |  (未設 timeout)         | ← 服務無回應 / 極慢   |
      |  ... 懸掛等待 ...       |                      |
      |  後續所有節點阻塞        |                      |
Pipeline 狀態：看起來在跑 ✓ / 實際：卡住等外部服務 ✗

— 場景 B：stream 分段 + Buffer 拼接有誤 —

Pipeline Runner         External Event API         LLM Node
      |                        |                      |
      |── GET /cultural-events >|                      |
      ||                      |
      |                        |                      |
      |  (no timeout set)      | |                      |
      |