常見問題¶

關於在 Headquarter.ai 建構和執行工作流程的常見問題。

入門¶

Resource 和 Workflow 有什麼不同？¶

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

工作流程 是您透過連接任務所建立的實際流程。它們使用資源來執行任務。

可以把資源想像成工具箱中的工具，而工作流程是您使用這些工具建立的專案。

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

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

對於進階使用情境（如 Lambda 任務），Python 知識會有幫助，但大多數工作流程不需要。

我該如何開始？¶

遵循以下路徑：

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

變數與資料¶

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

使用 $.（JSONPath） 用於當前工作流程執行的資料：

工作流程輸入："field.$": "$.user_question"
前一個任務輸出："field.$": "$.LLMResult.text"

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

變數資源："config.%": {"type": "variable", "id": "var-id", ...}
External Memory："data.%": {"type": "external_memory", ...}

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

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

→ 參見變數概覽

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

常見問題：

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

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

使用任務的 ResultPath：$.ActionNameResult

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

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

→ 了解更多：Path Parameter

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

工作流程狀態限制為 256 KB。如果超過此限制：

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

→ 了解更多：External Memory 語法

Workflow¶

如何在執行前測試 Workflow？¶

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

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

可以！使用工作流程執行任務：

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

將資料傳遞給子工作流程並接收其輸出。

→ 了解更多：Start Sync Workflow Execution

如何處理 Workflow 中的錯誤？¶

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

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

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

→ 了解更多：最佳實踐

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

常見原因：

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

→ 了解更多：最佳實踐

Resource¶

如何在 Workflow 間共享 Resource？¶

資源自動在您工作區的所有工作流程間共享。只需：

建立資源一次（例如 LLM 設定）
在任何需要它的工作流程中選擇它
使用一致的命名以便識別

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

不需要！為每個模型/設定建立一個大型語言模型資源並在工作流程間重用。這樣：

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

Retriever 和 Knowledge Base 有什麼不同？¶

知識庫 是您儲存文件的地方（資料）。

檢索器 是您搜尋該知識庫的方式（搜尋設定）。

一個知識庫可以有多個具有不同搜尋策略的檢索器。

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

可以！為每個提供者建立獨立的大型語言模型資源：

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

然後在每個 LLM 任務中選擇適當的資源。

任務¶

LLM 和 Structured LLM 有什麼不同？¶

LLM 任務 回傳自由形式的文字。

結構化 LLM 任務 回傳符合定義 Schema 的 JSON。當您需要以下情況時使用：

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

什麼時候該使用傳遞任務？¶

使用傳遞任務來：

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

可以呼叫外部 API 嗎？¶

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

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

→ 了解更多：HTTPS API 任務

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

使用連結器相關任務：

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

使用連線詳細資訊設定連結器資源，然後在任務中引用它。

執行與除錯¶

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

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

如何除錯失敗的 Workflow？¶

遵循此流程：

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

→ 了解更多：故障排除

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

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

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

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

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

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

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

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

最佳實踐¶

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

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

偏好多個小工作流程，因為：

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

使用工作流程執行任務將它們串連在一起。

應該多久備份一次 Workflow？¶

定期匯出工作流程定義：

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

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

安全與存取¶

如何保護 API Key 的安全？¶

絕不要在工作流程中硬編碼憑證。相反：

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

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

可以，但要小心：

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

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

使用工作區權限控制：

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

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

仍有問題？¶

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