外部記憶體¶

用途¶

用一句生活化的比喻：太大的資料先寄放在旁邊的置物櫃，工作流程裡只傳一張「領取單」；需要用到完整內容的步驟，再拿領取單去把資料取回來。 這個「置物櫃」就是外部記憶體 (External Memory)。

為什麼需要它？因為工作流程在各步驟之間傳遞的資料（稱為「狀態」）有大小上限（約 256 KB）。如果你的資料很大（例如整份文件），硬塞進狀態會讓執行失敗。改用外部記憶體，工作流程裡只會傳一個簡短的參考（領取單），真正的大資料放在狀態之外，就不會撐爆上限。

更技術一點地說，外部記憶體是平台處理「大資料但不塞進工作流程狀態」的旁路儲存。平台會把大資料放到狀態外、只在工作流程中傳一個簡短的參考；下游步驟需要完整內容時再透過該參考讀回來。

以下情境適合外部記憶體：

• 工作流程輸入資料偏大（文件、逐字稿、批次紀錄、向量）
• 任務輸出偏大（檢索結果、解析後文件、冗長 API 回應）
• 同一份大型資料要進多個子工作流程，不想每次都複製

外部記憶體分寫入面（大型資料怎麼移出狀態）與讀取面（之後任務怎麼讀回）。本頁處理寫入面；讀取面（.% 參考語法）請看 外部記憶體語法。

為任務輸出啟用外部記憶體¶

當一個任務預期會產生大型輸出時，在編輯器點該任務節點打開設定面板，在「設定」分頁最下方展開「執行設定」摺疊區：

1. 打開「上傳輸出至外部記憶體」開關。

   

2. 開關打開後，底下會多出「狀態記憶體輸出選擇器」欄位（關著時不會顯示）。視需要填寫——它是一組「保留在狀態內的欄位名稱 → 要從原始輸出的哪裡取值」對照，讓少數關鍵欄位留在工作流程狀態內，其餘大型內容移到狀態外。

範例「狀態記憶體輸出選擇器」（以大型語言模型任務為例）：

{
  "message": "$.message",
  "error": "$.errors"
}

怎麼讀這段對照？每一行是「留在狀態內的欄位名稱 → 要從這個任務的輸出的哪裡取值」：

• "message": "$.message"：把輸出裡 $.message 的內容，留一份在狀態內、欄位叫 message。
• "error": "$.errors"：把輸出裡 $.errors 的內容，留一份在狀態內、欄位叫 error。

左邊是你自己取的欄位名，右邊的 $.xxx 是「從這個任務的輸出裡撈值」的 JSONPath。沒被列進選擇器的大型內容，就會被移到狀態外（之後用 .% 讀回）。

這一輪結束後，下游任務在狀態內看到的是一份精簡摘要（含外部記憶體的參考），需要完整內容時以 .% 語法讀回。

為工作流程輸入啟用外部記憶體¶

輸入資料偏大時，這個設定有兩個入口，兩邊的欄位名稱一樣：

• 只讓這一次執行套用：在執行畫面「新的執行」表單展開「進階設定」，打開「上傳輸入至外部記憶體」開關。
• 讓這條流程每次執行都套用：在編輯器點「開始」節點，面板上同樣有「上傳輸入至外部記憶體」開關（見開始與結束節點）。

開關打開後，底下會多出「狀態記憶體輸入選擇器」，用同樣的「欄位名稱 → JSONPath」對照保留小型欄位（id、date、month…）在狀態內，供前段步驟做路由判斷，完整資料則在後續任務才抓回。

範例「狀態記憶體輸入選擇器」：

{
  "month": "$.month"
}

這在批次任務中特別常見：前段步驟只需要一兩個欄位決定往哪走，其他資料到後段任務才會用到。逐步填寫說明見執行與查看結果。

外部系統預先上傳¶

若大型資料是在平台外產生（本地 pipeline 的產出、其他團隊交付的檔案…），可以不必整份推過平台介面：先向平台要一個短效的上傳入口，把資料直接傳上去，啟動執行時只帶那張「領取單」。這需要呼叫平台 API 才能完成，請洽工程同事協助。

讀回外部記憶體¶

下游任務用 .% 在輸入定義裡引用外部記憶體。id 可以寫死，也可以用 JSONPath 從前一個任務的輸出動態帶入：

{
  "full_context.%": {
    "type": "external_memory",
    "id.$": "$.LLMActionResult.external_memory_id",
    "jsonpath": "$"
  }
}

完整語法（含從「變數」資源讀取、與 $. 混用、常見錯誤）見 外部記憶體語法。

生命週期與保留¶

• 外部記憶體的物件由平台管理，不需要手動清理。
• 預先上傳流程所回的 URL 僅在短時間內有效（約 1 小時），請盡早上傳。
• 執行中的工作流程引用的物件至少會被保留到執行結束；長期保留由平台管理者設定。

故障排除¶

開了外部記憶體卻仍因大小限制而失敗。 請確認設定在正確的層級：任務「執行設定」裡的「上傳輸出至外部記憶體」只處理那一個任務自己的輸出；如果是整條流程一開始收到的輸入太大，要改在執行時（或「開始」節點）打開「上傳輸入至外部記憶體」，見為工作流程輸入啟用外部記憶體。

下游任務讀到 null。 常見原因：

• 「狀態記憶體輸出選擇器」把你之後要讀的欄位過濾掉了。
• .% 中的 jsonpath 指向上傳物件裡不存在的路徑。

先用一個「傳遞資料（Pass）」節點把完整物件整包讀回來看實際結構（做法見傳遞資料），再調整選擇器或 JSONPath。

上傳到預先上傳 URL 被拒。 URL 已過期（時效很短），或上傳用了錯誤的內容型別。請用 application/json，必要時重新申請一張 URL。

延伸閱讀¶

• 外部記憶體語法 — .% 參考格式
• JSONPath 語法
• 變數資源指南