常見問題¶

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

入門¶

資源和工作流程有什麼不同？¶

資源 是可重用的設定（例如要用哪個大型語言模型、怎麼連到某個資料庫），您設定一次後就能在多個工作流程中使用。

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

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

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

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

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

我該如何開始？¶

遵循以下路徑：

1. 閱讀平台概覽了解這個平台能幫你做什麼
2. 跟著第一個工作流程做出你的第一條流程
3. 探索最佳實踐改進您的工作流程

變數與資料¶

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

這三種寫法都是同一件事的三種做法：不要把值寫死，而是等執行時才把資料代入。差別在於你會把它填在畫面上的哪一種欄位：

• 九成情況你只會用到 $.。實際怎麼點，見 JSONPath 語法。
• {{ }} 的用法見 Template 語法。
• .% 目前沒有引導式介面，需要在「程式碼」分頁手寫定義；不熟悉的話請先改用 $.，或請工程同事協助。見 外部記憶體語法。

→ 先看懂資料怎麼在步驟間傳遞：變數與資料引用概覽

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

常見問題：

1. 沒有打開「JSONPath」開關 - 開關沒打開時，你填的 $.value 會被當成一段固定文字，不會去取資料
2. 錯誤的欄位名稱 - 欄位名稱區分大小寫
3. 欄位不存在 - 檢查「開始」節點的「輸入結構」有沒有定義這個欄位，或前一個任務有沒有輸出它
4. 任務尚未執行 - 被引用的任務必須排在這個任務前面才取得到資料

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

使用任務的 ResultPath：$.ActionNameResult

例如，如果您有一個名為 GenerateAnswer 的大型語言模型任務：

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

→ 了解更多：Path Parameters

什麼是 256 KB 的工作流程狀態限制？¶

「狀態」是這次執行從頭到尾共用的那份資料——每個任務把結果寫進去，後面的任務從裡面讀（就像一份一路傳下去的病歷夾，見 變數與資料引用概覽）。這份資料整體上限為 256 KB。

一般文字問答遠遠用不到這個額度；會超過通常是因為某個任務一次回傳了大量內容，例如整份 PDF 的全文、資料庫幾千列的查詢結果、或網頁抓下來的完整 HTML。超過時該次執行會失敗。

處理方式：

• 改用外部記憶體 (External Memory)：大型資料放在狀態外面，狀態裡只留一個引用。
• 打開「上傳輸出至外部記憶體」開關：在節點設定面板「設定」分頁的「執行設定」區塊（是滑動開關，不是勾選框），讓這個任務的輸出自動改走外部記憶體。
• 從源頭減量：例如資料庫查詢加上筆數限制、先摘要再往下傳、只取需要的欄位。

→ 了解更多：外部記憶體語法

工作流程¶

如何在執行前測試工作流程？¶

1. 測試個別任務 - 點選節點打開設定面板，按面板右上角的「測試任務」按鈕（），就能單獨試跑這一個任務
2. 用範例輸入執行 - 在編輯器右上角的「動作」選單點「執行應用程式」，搭配代表性測試資料跑一次
3. 檢查執行結果 - 檢視每個步驟的輸出和狀態

可以在另一個工作流程中重用工作流程嗎？¶

可以。在「新增狀態」面板的「工作流程執行」分類裡有兩種任務：

• 執行工作流程任務 - 觸發後不等待（非同步、即發即忘）
• 執行同步工作流程任務 - 等待子工作流程跑完再繼續

兩者都能把資料傳給子工作流程並接收它的輸出。

→ 了解更多：執行同步工作流程

如何處理工作流程中的錯誤？¶

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

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

若某個任務失敗時想改走另一條處理路徑（而不是整條流程直接失敗），可在同一個「錯誤處理」分頁使用「捕捉」→「建立新的捕捉器」。

→ 了解更多：最佳實踐

為什麼我的工作流程執行這麼久？¶

常見原因：

• 長時間的大型語言模型呼叫 - 改用更快的模型或縮小輸入
• 大型資料處理 - 改用外部記憶體，或拆分成更小的步驟
• 低效的任務順序 - 把互不相依的任務改成平行執行
• 外部 API 緩慢 - 檢查 API 回應時間

→ 了解更多：最佳實踐

資源¶

如何在多個工作流程間共用同一個資源？¶

一個資源建立好之後，可以被多個工作流程與 Agent 重複選用，不必為每條流程各做一份：

1. 建立資源一次（例如一個大型語言模型資源）
2. 在任何需要它的工作流程任務中選擇它
3. 使用一致的命名以便識別

我需要為每個工作流程建立新的大型語言模型資源嗎？¶

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

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

檢索器和知識庫有什麼不同？¶

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

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

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

可以在一個工作流程中使用多個大型語言模型提供者嗎？¶

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

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

然後在每個大型語言模型任務中選擇適當的資源。

任務¶

大型語言模型任務和結構化大型語言模型任務有什麼不同？¶

大型語言模型任務 回傳自由形式的文字。

結構化大型語言模型任務 回傳符合你定義的「輸出結構」的 JSON。當您需要以下情況時使用：

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

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

使用傳遞資料任務來：

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

可以呼叫外部 API 嗎？¶

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

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

→ 了解更多：HTTPS API 任務

如何在工作流程中使用資料庫資料？¶

使用連結器相關任務：

• MySQL 任務 - 查詢 MySQL 資料庫
• OpenSearch 任務 - 搜尋 OpenSearch 索引
• Athena 任務 - 用 SQL 查詢存放在 Amazon S3 上的資料

先建立好帶連線資訊的連結器資源，再在任務的「連結器」欄位選它。

執行與除錯¶

哪裡可以看到工作流程的執行紀錄？¶

1. 在側邊欄點「工作流程」
2. 點進你的工作流程
3. 切到「執行」分頁

4. 點某一次執行，即可查看：

   • 輸入／輸出
   • 狀態、開始與停止時間、執行時間
   • 「歷史」分頁裡各步驟進出的資料

如何除錯失敗的工作流程？¶

遵循此流程：

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

→ 了解更多：疑難排解

可以看到工作流程狀態中有什麼資料嗎？¶

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

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

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

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

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

• 無限迴圈 - 檢查條件邏輯的終止條件
• 任務過久 - 最佳化該任務或縮小輸入
• 互相等待 - 檢查各節點的「下一個狀態」是否接成了會互相等待的環

如果一直卡著不動，可到該筆執行的「歷史」分頁看它停在哪一步，再針對那一步排查。

最佳實踐¶

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

應該使用一個大工作流程還是多個小工作流程？¶

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

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

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

應該多久備份一次工作流程？¶

平台每次按「更新」都會留下一版，可到工作流程詳細頁的「版本紀錄」分頁回顧或還原，見 版本紀錄。若還想在平台之外多留一份備份，可用編輯器「動作」選單的「下載定義」把流程定義存成檔案：

• 重大變更前 - 先下載一份現行可用的版本
• 上線前 - 保留一份確定可運作的定義
• 定期 - 依團隊習慣每週或每月各留一份

下載的定義檔可放進你們自己的版本控制（例如 Git）追蹤變更。

安全與存取¶

如何保護 API 金鑰的安全？¶

不要把金鑰打在任務的欄位或提示詞裡。建議做法：

1. 存在資源裡 - 金鑰填在大型語言模型或連結器資源的憑證欄位，任務只要「選這個資源」就好，不必看到金鑰本身
2. 用群組權限限制誰看得到 - 請管理員在「群組」的「資源存取」只把該資源授權給需要的群組，見 群組
3. 定期更新憑證 - 到該資源的編輯表單換掉金鑰後儲存；有驗證按鈕的資源可順手按「驗證憑證」或「測試連線」確認新金鑰可用
4. 開發與正式環境用不同金鑰 - 分別建立兩個資源，用名稱區分（例如 llm-openai-dev、llm-openai-prod）

多個使用者可以同時編輯同一個工作流程嗎？¶

可以，但要小心：

• 同時編輯會互相覆蓋 - 最後按「更新」的那個人的版本會生效
• 先和團隊說一聲 - 同一條流程盡量一次只有一個人在改
• 改壞了可以還原 - 到詳細頁的「版本紀錄」分頁還原到先前的版本，見 版本紀錄
• 改完務必試跑 - 用「執行應用程式」跑一次確認沒壞

如何限制對敏感工作流程的存取？¶

平台的權限單位是群組（不是逐個使用者設定）：管理員先建立群組，在群組上決定它能用哪些 Agent、工作流程與資源，再把人加進群組。相關分頁有四個：

每一筆權限只有兩種等級：Read（唯讀）與 Write（可讀寫）——沒有單獨的「可執行」權限等級。

需要調整權限請聯絡貴單位的平台管理員，設定方式見 群組。

仍有問題？¶

• 查看文件 - 使用右上角的搜尋尋找特定主題
• 檢視範例 - 查看第一個工作流程和最佳實踐
• 找人幫忙 - 聯絡貴單位的平台管理員，並提供工作流程名稱、重現步驟與完整錯誤訊息