常見問題¶

關於在 Headquarter.ai 建構和執行 Workflow 的常見問題。

入門¶

Resource 和 Workflow 有什麼不同？¶

Resource 是可重用的設定（如 LLM 提供者、資料庫連線），您設定一次後就能在多個 Workflow 中使用。

Workflow 是您透過連接 Action 所建立的實際流程。它們使用 Resource 來執行任務。

可以把 Resource 想像成工具箱中的工具，而 Workflow 是您使用這些工具建立的專案。

我需要程式設計經驗才能使用 Headquarter.ai 嗎？¶

不需要。視覺化 Workflow 建構器讓您透過拖放 Action 來建立 Workflow。不過，理解基本的 JSON 結構有助於設定 Action 參數。

對於進階使用情境（如 Lambda Action），Python 知識會有幫助，但大多數 Workflow 不需要。

我該如何開始？¶

遵循以下路徑：

閱讀平台總覽了解這個平台能幫你做什麼
遵循快速開始建立您的第一個 Workflow
探索最佳實踐改進您的 Workflow

變數與資料¶

什麼時候該用 `$.` vs `.%` vs `{{ }}`？¶

使用 $.（JSONPath） 用於當前 Workflow 執行的資料：

Workflow 輸入："field.$": "$.user_question"
前一個 Action 輸出："field.$": "$.LLMResult.text"

使用 .%（External Memory） 用於持久性或大型資料：

Variable Resource："config.%": {"type": "variable", "id": "var-id", ...}
External Memory："data.%": {"type": "external_memory", ...}

使用 {{ }}（Template） 用於文字渲染：

Text Action Template：Hello {{ name }}
LLM Prompt：Answer this: {{ question }}

→ 參見變數概覽

為什麼我的 `$.variable` 引用無效？¶

常見問題：

遺漏 .$ 後綴 - 使用 "field.$": "$.value" 而非 "field": "$.value"
錯誤的欄位名稱 - 欄位名稱區分大小寫
欄位不存在 - 檢查 Input Schema 或前一個 Action 輸出
Action 尚未執行 - 確保被引用的 Action 在此之前執行

如何存取前一個 Action 的資料？¶

使用 Action 的 ResultPath：$.ActionNameResult

例如，如果您有一個名為 "GenerateAnswer" 的 LLM Action：

{
  "answer.$": "$.GenerateAnswerResult.text"
}

→ 了解更多：Path Parameter

什麼是 256 KB Workflow 狀態限制？¶

Workflow 狀態限制為 256 KB。如果超過此限制：

使用 External Memory 處理大型資料（超過 256 KB）
啟用「上傳輸出至外部記憶體」（Upload Output to External Memory，在節點設定面板「設定」分頁中的「執行設定」區塊勾選）
只保留必要資料在狀態中（即 Output Selector）

→ 了解更多：External Memory 語法

Workflow¶

如何在執行前測試 Workflow？¶

測試個別 Action - 點選節點打開設定面板，使用右上角的「Test Action」按鈕獨立測試每個 Action（此按鈕在平台上維持英文顯示）
用範例輸入執行 - 使用「執行應用程式」（Run Application）搭配代表性測試資料
檢查執行結果 - 檢視每個步驟的輸出和狀態

可以在另一個 Workflow 中重用 Workflow 嗎？¶

可以！使用 Workflow 執行 Action：

Start Workflow Execution - 觸發非同步（即發即忘）
Start Sync Workflow Execution - 等待子 Workflow 完成

將資料傳遞給子 Workflow 並接收其輸出。

→ 了解更多：Start Sync Workflow Execution

如何處理 Workflow 中的錯誤？¶

在節點設定面板的「錯誤處理」分頁 →「重試」→「新增重試器」設定（不在「設定」分頁的「執行設定」區塊）：

最多重試次數（Max Retry Count）- 重試次數（建議 2-3 次）
間隔秒數（Retry Interval）- 重試間隔，預設 1 秒（單位是秒，不是毫秒）
退避倍率（Backoff Rate）- 指數退避倍數（2.0）

對於複雜的錯誤處理，使用帶有 try/catch 邏輯的 Lambda Action。

→ 了解更多：最佳實踐

為什麼我的 Workflow 執行這麼久？¶

常見原因：

長時間的 LLM 呼叫 - 改用更快的模型或縮小輸入
大型資料處理 - 使用 External Memory 或拆分成更小的步驟
低效的 Action 順序 - 平行化獨立的 Action
外部 API 緩慢 - 檢查 API 回應時間

→ 了解更多：最佳實踐

Resource¶

如何在 Workflow 間共享 Resource？¶

Resource 自動在您工作區的所有 Workflow 間共享。只需：

建立 Resource 一次（例如 LLM 設定）
在任何需要它的 Workflow 中選擇它
使用一致的命名以便識別

我需要為每個 Workflow 建立新的 LLM Resource 嗎？¶

不需要！為每個模型/設定建立一個 LLM Resource 並在 Workflow 間重用。這樣：

簡化管理
確保設定一致
更新更容易（改一次，處處適用）

Retriever 和 Knowledge Base 有什麼不同？¶

Knowledge Base 是您儲存文件的地方（資料）。

Retriever 是您搜尋該 Knowledge Base 的方式（搜尋設定）。

一個 Knowledge Base 可以有多個具有不同搜尋策略的 Retriever。

可以在一個 Workflow 中使用多個 LLM 提供者嗎？¶

可以！為每個提供者建立獨立的 LLM Resource：

llm-gpt4（OpenAI GPT-4）
llm-claude（Anthropic Claude）
llm-local（本地模型）

然後在每個 LLM Action 中選擇適當的 Resource。

Action¶

LLM 和 Structured LLM 有什麼不同？¶

LLM Action 回傳自由形式的文字。

Structured LLM Action 回傳符合定義 Schema 的 JSON。當您需要以下情況時使用：

一致的資料結構
回應中的多個欄位
資料驗證

什麼時候該使用 Pass Action？¶

使用 Pass Action 來：

聚合平行分支 - 結合來自平行 Action 的結果
轉換資料 - 在下一個 Action 前重組資料
明確路由 - 使資料流更清楚
除錯 - 在特定點記錄狀態

可以呼叫外部 API 嗎？¶

可以！使用 HTTPS API Action 呼叫任何 REST API：

設定方法（GET、POST、PUT、DELETE）
設定標頭和驗證
傳遞請求本文
在下一個 Action 中存取回應資料

→ 了解更多：HTTPS API Action

如何在 Workflow 中使用資料庫資料？¶

使用 Connector Action：

MySQL Action - 查詢 MySQL 資料庫
OpenSearch Action - 搜尋 OpenSearch 索引

使用連線詳細資訊設定 Connector Resource，然後在 Action 中引用它。

執行與除錯¶

哪裡可以看到 Workflow 執行日誌？¶

前往側邊欄的「工作流程」（Workflows）
點擊您的 Workflow
查看「執行」（Executions）分頁
點擊某次執行以查看：
輸入/輸出
狀態和執行時間
每個步驟的狀態（如果啟用）

如何除錯失敗的 Workflow？¶

遵循此流程：

檢查執行結果 - 查看錯誤訊息
測試個別 Action - 隔離失敗的 Action
驗證 JSONPath 引用 - 確保 $. 路徑正確
檢查 Resource 設定 - 驗證憑證和設定
簡化 Workflow - 建立最小重現案例

→ 了解更多：故障排除

可以看到 Workflow 狀態中有什麼資料嗎？¶

可以，多數情況下執行完成後即可查看：

開啟某次執行的詳情頁，切換到「歷史」分頁
即可查看各步驟（每個 Action）進出的狀態資料
使用此功能除錯資料流問題

注意： 狀態資料不一定對所有執行都完整可用，端視該次執行與設定而定。文件中提到的「在執行設定中設定狀態保留」目前在介面上未見對應開關，請以「歷史」分頁實際顯示的內容為準。

為什麼我的執行一直顯示「執行中」？¶

平台的狀態值以中文顯示，「執行中」即對應 RUNNING。可能原因：

無限迴圈 - 檢查條件邏輯的終止條件
Action 過久 - 最佳化該 Action 或縮小輸入
死鎖 - 檢視平行執行相依性

如果卡住，執行最終會根據平台的逾時設定自動結束。

最佳實踐¶

→ 詳細的最佳實踐指南，請參閱完整的最佳實踐指南。

應該使用一個大 Workflow 還是多個小 Workflow？¶

偏好多個小 Workflow，因為：

更容易理解和除錯
可以獨立重用
測試和迭代更快
更好的錯誤隔離

使用 Workflow 執行 Action 將它們串連在一起。

應該多久備份一次 Workflow？¶

定期匯出 Workflow 定義：

重大變更後 - 在重大更新前匯出
部署前 - 保留生產就緒版本
每週/每月 - 排程定期備份

將匯出檔案儲存在版本控制（Git）中以追蹤變更。

安全與存取¶

如何保護 API Key 的安全？¶

絕不要在 Workflow 中硬編碼憑證。相反：

儲存在 Resource 設定中 - API Key 存在 LLM 或 Connector Resource
使用工作區權限 - 控制誰可以查看/編輯 Resource
定期輪換 - 定期更新憑證
使用獨立 Key - 開發/測試/正式環境使用不同 Key

多個使用者可以同時處理同一個 Workflow 嗎？¶

可以，但要小心：

一次只有一個使用者可以編輯 - 變更可能衝突
溝通更新 - 與團隊協調
使用 Workflow 匯出/匯入 - 對於重大變更，匯出 → 編輯 → 匯入
部署前測試 - 更新後務必驗證

如何限制對敏感 Workflow 的存取？¶

使用工作區權限控制：

誰可以查看 Workflow - 唯讀存取
誰可以編輯 Workflow - 修改定義
誰可以執行 Workflow - 使用輸入資料執行
誰可以管理 Resource - 建立/更新設定

聯絡您的工作區管理員以設定權限。

仍有問題？¶

查看文件 - 使用搜尋尋找特定主題
檢視範例 - 查看快速上手和最佳實踐
聯絡支援 - 提供具體問題和 Workflow 詳細資訊