External Memory 語法¶

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

語法格式¶

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

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

兩種引用類型¶

Variable Resource¶

Variable Resource 儲存可以在不更改 Workflow 定義的情況下更新的持久性設定。

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

External Memory¶

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

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

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

何時使用 External Memory 語法¶

使用 .% 語法當：

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

使用 $. 語法當：

• ❌ 資料較小且特定於當前執行
• ❌ 資料隨著每次 Workflow 執行而改變
• ❌ 在相同執行內存取前一個 Action 輸出

設定指南¶

在 Action 中啟用 External Memory¶

若要為 Action 輸出啟用 External Memory：

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

常見場景¶

場景 1：大型 Workflow 輸入¶

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

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

場景 2：大型 Action 輸出¶

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

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

場景 3：父子 Workflow 執行¶

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

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

故障排除¶

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

可能原因：

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

解決方法：

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

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

可能原因：

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

解決方法：

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

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

可能原因：

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

解決方法：

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

實用範例¶

範例 1：從 Variable 載入設定¶

建立名為「api-config」的 Variable Resource，內容為：

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

Pass Action 設定：

{
  "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 輸出：

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

Pass Action 檢索完整內容：

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

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

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 語法來選擇要從 Variable 或 External Memory 內容中提取哪個部分。

常見模式：

處理 Action External Memory¶

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

Action 輸出：

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

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

存取完整內容：

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

→ 了解更多關於 Path Parameter

結合 JSONPath 語法¶

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

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

此 Action 接收：

• 來自 Variable Resource 的持久性設定
• 來自 Workflow 狀態的使用者輸入
• 來自 Workflow 狀態的前一個 Action 輸出

最佳實踐¶

對設定使用 Variable Resource：

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

對大型資料使用 External Memory：

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

記錄相依性：

• 在 Workflow 文件中列出所需的 Variable Resource
• 註記哪些 Action 使用 External Memory
• 包含預期資料結構的範例

為 Variable Resource 建立版本：

• 追蹤 Variable Resource 的變更
• 在部署前使用更新的 Variable 測試 Workflow
• 考慮為開發/測試/正式環境使用不同的 Variable

常見錯誤¶

❌ 遺漏 .% 後綴

{
  "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": "$"  // 正確
  }
}

大小限制¶

Workflow 狀態（使用 $.）：

• 每次執行最多 256 KB
• 包含所有 Action 輸出和 Workflow 變數
• 超過限制會導致執行失敗

External Memory（使用 .%）：

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

相關主題¶

• JSONPath 語法 - 用於存取 Workflow 執行資料
• Path Parameter - 了解 External Memory ID 的 ResultPath
• Variable Resource 指南 - 建立和管理 Variable