External Memory 語法¶

External Memory 語法（.%）用於引用儲存在變數資源或 External Memory 中的資料。當處理大型資料集（約超過 256 KB）或需要在多個工作流程執行間共享的持久性設定時，這是必要的。

語法格式¶

{
  "field.%": {
    "type": "variable",
    "id": "var-abc123",
    "jsonpath": "$.path.to.value"
  }
}

關鍵要求： 欄位名稱必須使用 .% 後綴，且物件必須包含 type、id（或 id.$）和 jsonpath 欄位。

兩種引用類型¶

Variable Resource¶

變數資源儲存可以在不更改工作流程定義的情況下更新的持久性設定。

{
  "config.%": {
    "type": "variable",
    "id": "var-abc123",
    "jsonpath": "$.settings"
  }
}

External Memory¶

External Memory 在勾選「Enable External Memory」時儲存來自任務輸出的大型資料。

{
  "large_data.%": {
    "type": "external_memory",
    "id.$": "$.previous_action.external_memory_id",
    "jsonpath": "$"
  }
}

注意： 當 ID 來自前一個任務的輸出時，使用 id.$ 搭配 JSONPath。

何時使用 External Memory 語法¶

使用 .% 語法當：

• ✅ 資料對於工作流程狀態來說太大（>256 KB）
• ✅ 設定應在不更改工作流程定義的情況下更新
• ✅ 多個工作流程需要共享相同資料
• ✅ 資料需要在工作流程執行間持久化

使用 $. 語法當：

• ❌ 資料較小且特定於當前執行
• ❌ 資料隨著每次工作流程執行而改變
• ❌ 在相同執行內存取前一個任務輸出

設定指南¶

在任務中啟用 External Memory¶

若要為任務輸出啟用 External Memory：

1. 開啟任務設定表單
2. 展開「Execution Settings」
3. 啟用「Upload Output to External Memory」
4. 可選擇設定：
5. State Memory Input Selector - 控制哪部分輸入資料被儲存
6. State Memory Output Selector - 控制哪部分輸出資料保留在 inline

常見場景¶

場景 1：大型 Workflow 輸入¶

當你的工作流程接收大型輸入資料（文件、報告、大型 JSON）：

• 在工作流程執行層級啟用「Use External Memory Input」
• 或在 workflow-execution 任務中啟用「Upload Input to External Memory」
• 使用「State Memory Input Selector」引用所需的資料區段

場景 2：大型任務輸出¶

對於產生大量內容的任務（檢索結果、解析文件、大型 API 回應）：

• 在任務的 Execution Settings 中啟用「Upload Output to External Memory」
• 使用「State Memory Output Selector」只保留必要欄位在 inline
• 使用 .% 語法在後續任務中存取完整內容

場景 3：父子 Workflow 執行¶

使用 Start Workflow Execution 或 Start Sync Workflow Execution 時：

• 在執行任務中啟用「Upload Input to External Memory」
• 設定「State Memory Input Selector」讓子工作流程只讀取需要的資料
• 避免在父子工作流程間重複大型資料

故障排除¶

問題：下游任務收到空值或 null¶

可能原因：

• Selector 路徑與實際執行時的資料結構不符
• External Memory ID 未正確傳遞給後續任務

解決方法：

• 從執行日誌驗證任務輸出結構
• 檢查 id.$ 是否正確引用 external_memory_id 欄位
• 更新 selector 路徑以符合實際資料結構

問題：Inline 輸出的資料仍然太大¶

可能原因：

• 未啟用「Upload Output to External Memory」
• Output selector 太廣泛，包含大型欄位

解決方法：

• 在 Execution Settings 中啟用上傳選項
• 精簡 State Memory Output Selector，排除大型欄位
• 只在 inline 保留必要的 metadata

問題：父子 Workflow 資料不匹配¶

可能原因：

• 父工作流程傳遞完整物件，而子工作流程預期巢狀欄位
• 父子工作流程之間的 Selector 不一致

解決方法：

• 對齊工作流程之間的 State Memory Input/Output Selector
• 驗證子工作流程的輸入 schema 預期
• 使用範例資料測試以驗證資料流

實用範例¶

範例 1：從 Variable 載入設定¶

建立名為「api-config」的變數資源，內容為：

{
  "base_url": "https://api.example.com",
  "timeout": 30,
  "retry_count": 3
}

傳遞任務設定：

{
  "parameters": {
    "api_settings.%": {
      "type": "variable",
      "id": "var-api-config-id",
      "jsonpath": "$"
    }
  }
}

輸出：

{
  "api_settings": {
    "base_url": "https://api.example.com",
    "timeout": 30,
    "retry_count": 3
  }
}

範例 2：從 External Memory 檢索大型資料集¶

啟用 External Memory 的 LLM 任務輸出：

{
  "action_type": "llm_action",
  "external_memory_id": "mem-xyz789",
  "text": "Summary of document"
}

傳遞任務檢索完整內容：

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

範例 3：從 Variable 提取特定欄位¶

變數內容：

{
  "database": {
    "host": "db.example.com",
    "port": 5432,
    "name": "production"
  },
  "api_keys": {
    "service_a": "key-123",
    "service_b": "key-456"
  }
}

只提取資料庫設定：

{
  "db_config.%": {
    "type": "variable",
    "id": "var-config-id",
    "jsonpath": "$.database"
  }
}

輸出：

{
  "db_config": {
    "host": "db.example.com",
    "port": 5432,
    "name": "production"
  }
}

了解 jsonpath 欄位¶

jsonpath 欄位使用 JSONPath 語法來選擇要從變數或 External Memory 內容中提取哪個部分。

常見模式：

處理任務 External Memory¶

當任務勾選「Enable External Memory」時，其輸出會儲存在 External Memory 中：

任務輸出：

{
  "action_type": "llm_action",
  "external_memory_id": "mem-abc123",
  "text": "Summary"
}

external_memory_id 儲存在任務的 ResultPath（例如 $.LLMActionResult.external_memory_id）。

存取完整內容：

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

→ 了解更多關於 Path Parameter

結合 JSONPath 語法¶

你可以在同一個任務中同時使用 .% 和 .$：

{
  "config.%": {
    "type": "variable",
    "id": "var-settings",
    "jsonpath": "$"
  },
  "user_input.$": "$.question",
  "previous_result.$": "$.LLMActionResult.text"
}

此任務接收：

• 來自變數資源的持久性設定
• 來自工作流程狀態的使用者輸入
• 來自工作流程狀態的前一個任務輸出

最佳實踐¶

對設定使用變數資源：

• API 端點和憑證
• 模型參數和設定
• Template 和 Prompt
• 功能標記和開關

對大型資料使用 External Memory：

• 長文件和轉錄稿
• 大型 API 回應
• Embedding 和向量
• 搜尋結果和資料集

記錄相依性：

• 在工作流程文件中列出所需的變數資源
• 註記哪些任務使用 External Memory
• 包含預期資料結構的範例

為變數資源建立版本：

• 追蹤變數資源的變更
• 在部署前使用更新的變數測試工作流程
• 考慮為開發/測試/正式環境使用不同的變數

常見錯誤¶

❌ 遺漏 .% 後綴

{
  "config": {  // 錯誤！
    "type": "variable",
    "id": "var-abc123",
    "jsonpath": "$"
  }
}

✅ External Memory 語法一律使用 .%

{
  "config.%": {  // 正確
    "type": "variable",
    "id": "var-abc123",
    "jsonpath": "$"
  }
}

❌ 對動態值使用靜態 id

{
  "data.%": {
    "type": "external_memory",
    "id": "$.Action.external_memory_id",  // 錯誤！應該是 id.$
    "jsonpath": "$"
  }
}

✅ 對 JSONPath 引用使用 id.$

{
  "data.%": {
    "type": "external_memory",
    "id.$": "$.Action.external_memory_id",  // 正確
    "jsonpath": "$"
  }
}

❌ 遺漏 jsonpath 欄位

{
  "config.%": {
    "type": "variable",
    "id": "var-abc123"  // 錯誤！遺漏 jsonpath
  }
}

✅ 一律包含 jsonpath

{
  "config.%": {
    "type": "variable",
    "id": "var-abc123",
    "jsonpath": "$"  // 正確
  }
}

大小限制¶

工作流程狀態（使用 $.）：

• 每次執行最多 256 KB
• 包含所有任務輸出和工作流程變數
• 超過限制會導致執行失敗

External Memory（使用 .%）：

• 無實際大小限制
• 適合文件、資料集和大型回應
• 由平台自動管理

相關主題¶

• JSONPath 語法 - 用於存取工作流程執行資料
• Path Parameter - 了解 External Memory ID 的 ResultPath
• 變數資源指南 - 建立和管理變數