跳轉到

External Memory

你需不需要這頁？先看這裡

如果你的資料是短問答、單次掛號、幾句對話這種小資料，通常用不到 External Memory，用 JSONPath 就好。只有當你要把整份病歷、檢驗報告全文、大量檢索結果餵給 AI 時，才會需要它。先判斷自己屬於哪一種，再決定要不要往下讀。

用途

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

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

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

以下情境適合 External Memory：

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

External Memory 分寫入面（大型資料如何移出 state）與讀取面（之後 Action 怎麼讀回）。本頁處理寫入面；讀取面（.% 參考語法）請看 External Memory 語法。

為 Action 輸出啟用 External Memory

當一個 Action 預期會產生大型輸出時，打開該 Action 的「Execution Settings」並：

  1. 勾選「Upload Output to External Memory」。
  2. 視需要填寫「State Memory Output Selector」——一組「inline key → JSONPath」的對照，讓少數關鍵欄位留在 Workflow state 內，其餘大型內容移到 state 外。

範例 selector：

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

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

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

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

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

為 Workflow 輸入啟用 External Memory

啟動 Workflow 時若輸入資料偏大：

  1. 在啟動請求或 UI 表單上啟用「Use External Memory Input」。
  2. 視需要填寫「State Memory Input Selector」以 JSONPath map 保留小型 metadata（id、date、tenant…）在 state 內，供早期狀態做路由判斷，完整資料則在後續 Action 才抓回。

範例 selector：

{
  "month": "$.month"
}

這在批次任務中特別常見：driver 只需要一兩個欄位決定路徑，其他資料到後段 Action 才會用到。

外部系統預先上傳

這一段需要透過 API 操作，平台介面（UI）目前無法照做

以下「預先上傳」流程是給工程／系統整合情境用的，需要呼叫平台 API；目前無法只靠平台網頁介面完成，且實際的請求／回應格式仍在整理（將寫在 API Reference）。如果你是一般使用者、只在介面上操作，可略過本段，改用前面「為 Workflow 輸入啟用 External Memory」的方式，或請工程同事協助。

若大型 payload 是在平台外產生（從本地 pipeline 上傳、由其他團隊的工作產出…），就不需要整份推過平台 API。平台提供了預先上傳流程，讓你拿到一個短效上傳入口，加上一個接受預上傳參考的啟動執行變體。

整體流程：

  1. 向平台請求一個上傳入口，取回一個不透明的參考與短效上傳 URL。
  2. 由你的側邊把 JSON 內容直接上傳到該 URL。
  3. 啟動 Workflow 執行時，帶上剛才取回的參考。

上傳 URL 有時效，建議臨近執行時再上傳。實際的請求 / 回應格式未來會寫在 API Reference。

讀回 External Memory

下游 Action 以 .% 在 input 定義中引用 External Memory。可寫死 ID，或用 JSONPath 從前一個 Action 的輸出動態取：

.% 目前在介面上沒有像 .$ 那樣的引導式入口

一般欄位的 .$（JSONPath）有「JSONPath 核取方塊／編輯參考路徑」這種引導式 UI；但 .% 讀回目前找不到對應的引導表單。實務上，下面這段 .% 物件目前需要在編輯器的「程式碼」分頁（ASL 編輯器）裡手動寫入定義。若你不熟悉這個格式，建議請工程同事協助。

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

完整語法（含從 Variable 資源讀取、與 $. 混用、常見錯誤）見 External Memory 語法。

生命週期與保留

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

故障排除

啟用 External Memory 後仍因大小限制而失敗。 請確認設定在正確層級。「Upload Output to External Memory」只處理該 Action 自己的輸出；大型 Workflow 輸入需要在執行啟動時啟用「Use External Memory Input」。

下游 Action 讀到 null。 常見原因：

  • State Memory Output Selector 把你之後要讀的欄位過濾掉。
  • .% 中的 jsonpath 指向上傳物件裡不存在的路徑。

用一個空轉 Action 先讀回完整物件看實際結構，再調整 selector 或 JSONPath。

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

延伸閱讀