最佳實踐¶

本指南概述在 Headquarter.ai 中建立有效、可維護且可靠的工作流程的建議做法。

工作流程設計¶

讓每條工作流程只做一件事¶

設計每個工作流程完成單一、明確定義的任務。

建議：

• 建立目的明確的專注工作流程
• 為複雜流程使用工作流程組合
• 使用描述性名稱（例如 customer-support-rag、document-summarizer）

避免：

• 將不相關的功能塞入一個工作流程
• 建立過於複雜的單一工作流程
• 使用通用名稱如 workflow-1 或 my-workflow

規劃資料流¶

在建立之前，先規劃資料如何流經你的工作流程。

檢查清單：

• [ ] 在「開始」節點定義清楚的「輸入結構」和必填欄位
• [ ] 規劃每個任務的輸出
• [ ] 識別需要的資料轉換
• [ ] 在「結束」節點用「輸出結構」把最終結果整理乾淨

使用有意義的名稱¶

使用描述性名稱命名任務和欄位以提高可讀性。

好的名稱：

• classify_intent - 清楚的任務目的
• user_question - 描述性的輸入欄位
• summarized_response - 清楚的輸出欄位

不好的名稱：

• action1 - 沒有上下文
• data - 太通用
• temp - 目的不明

大型語言模型任務¶

撰寫有效的提示詞¶

結構化提示詞以獲得一致、高品質的輸出。

準則：

1. 具體：清楚說明你想要什麼
2. 提供上下文：包含相關背景資訊
3. 設定約束：定義輸出格式和長度
4. 給予範例：展示預期的輸入/輸出模式

提示詞結構範例：

你是一位〔角色，例如：勞動法規顧問〕。你的任務是〔要做的事，例如：依提供的法規條文回答民眾問題〕。

背景資訊：
- 〔相關背景，例如：提問者是不熟悉法律用語的一般民眾〕
- 〔限制，例如：只能依提供的條文作答，找不到依據就說明找不到〕

輸入：{{ user_input }}

輸出要求：
- 〔格式，例如：先給一句結論，再列出依據的條號〕
- 〔長度，例如：300 字以內〕
- 〔品質要求，例如：用白話，不要直接抄法條原文〕

需要固定格式時改用結構化大型語言模型任務¶

當你需要一致的資料結構時：

• 改用「結構化大型語言模型任務」，並定義它的「輸出結構」
• 結構保持簡單、欄位定義清楚
• 為每個欄位加上描述，模型填得更準

處理模型的能力邊界¶

為模型回應的邊界情況做計畫：

• 設定合理的最大 Token 數
• 為關鍵輸出加入驗證
• 用「錯誤處理」分頁的「捕捉」準備一條備援路徑
• 使用多樣化的輸入進行測試

錯誤處理¶

為失敗做設計¶

假設任何任務都可能失敗並相應規劃。

策略：

設定適當的重試¶

重試讓某個任務失敗時自動再試幾次，避免因為一時的網路或服務問題就整個工作流程失敗。

設定位置：重試不在「設定」分頁中的「執行設定」區塊。請在工作流程編輯器點選該節點打開設定面板，切換到「錯誤處理」分頁，點「重試」→「新增重試器」，才會出現以下欄位：

• 最多重試次數（Max Retry Count）：暫時性錯誤設 2-3 次
• 間隔秒數（Retry Interval）：預設 1 秒，可視需要調整（單位是秒，不是毫秒）
• 退避倍率（Backoff Rate）：有速率限制的 API 使用 2（指數）

提供優雅降級¶

即使某些元件失敗也回傳有用的結果：

完全成功：包含所有來源的完整答案
部分失敗：使用可用來源的答案 + 警告
完全失敗：有幫助的錯誤訊息 + 建議

資源管理¶

用一致的方式命名資源¶

建立一致的命名和組織方案：

• 使用資源類型前綴（例如 llm-gpt4、db-mysql-prod）
• 邏輯性地分組相關資源
• 記錄資源的目的和設定

保護憑證¶

保護敏感資訊：

• 不要把憑證打在任務欄位或提示詞裡
• 把 API 金鑰填在資源的憑證欄位，任務只選資源
• 定期到資源的編輯表單換掉憑證，換完按「驗證憑證」／「測試連線」確認
• 定期請管理員檢視「群組」各分頁的權限清單，移除不再需要的授權

追蹤資源用量¶

• 用量數字集中在「用量」頁（僅管理員看得到），可看呼叫次數、Token 總數與預估成本，見 用量。
• Agent 可由管理員在「點數設定」給定額度上限，避免單一 Agent 用量失控，見 Agent 設定總覽 — 點數設定。
• 平台沒有自動警報或門檻通知功能，需要盯的話請安排人定期查看上述頁面。

效能最佳化¶

最小化不必要的處理¶

最佳化工作流程效率：

• 只讓必要的資料留在工作流程狀態裡（也就是這次執行共用的那份資料，上限 256 KB）
• 在工作流程早期就把不需要的資料過濾掉
• 避免重複呼叫模型問同樣的事
• 用「輸入與輸出」分頁的 ResultSelector／ResultPath／OutputPath 只留下要往下傳的欄位

明智地使用平行執行¶

平行化獨立的操作。在平台上，平行執行是透過讓一個節點的「下一個狀態」(Next State) 指向多個後續節點來達成（設定面板的「下一個狀態」欄位可指向多個任務）：

好：跨獨立來源的平行搜尋
不好：依賴彼此結果的平行呼叫

設定適當的逾時¶

以下是各類操作可參考的合理時間範圍，方便你判斷某個步驟跑多久算正常、是否該改用更快的模型或拆小步驟：

適當處理大型資料¶

對於大型文件或回應：

• 當資料可能超過工作流程狀態上限（256 KB）時，改用外部記憶體（在「執行設定」勾選「上傳輸出至外部記憶體」）
• 大量結果分批取，例如 SQL 加上筆數限制
• 傳給模型前先摘要
• 用「輸入與輸出」分頁的 ResultSelector／OutputPath 只留必要欄位

測試與驗證¶

漸進式測試¶

分階段建立和測試工作流程：

1. 先單獨測試每一個任務（在編輯器點選該節點打開設定面板，按面板右上角的「測試任務」按鈕（）即可只試跑這一步）
2. 測試任務序列
3. 使用代表性輸入測試完整工作流程
4. 測試邊界情況和錯誤情境

使用代表性測試資料¶

建立反映實際使用的測試輸入：

• 包含典型使用案例
• 包含邊界情況（空輸入、非常長的輸入）
• 包含可能有問題的輸入
• 記錄測試案例以進行迴歸測試

上線前驗證¶

部署前：

• [ ] 所有任務都已單獨測試
• [ ] 完整工作流程已端對端測試
• [ ] 錯誤處理已驗證
• [ ] 效能可接受
• [ ] 輸出格式已驗證

維護¶

把說明寫在平台裡¶

平台本身就有幾個可以寫說明的地方，寫在這裡比寫在別的檔案裡更不容易失散：

• 建立工作流程時的「附註」欄位：寫這條流程的用途；它也會顯示在「執行」畫面的「關於」分頁，執行前可快速確認。
• 每個節點設定面板的「附註」欄位：寫這一步在做什麼、為什麼這樣設。
• 詳細頁的「依賴資源」／「被依賴資源」分頁：不必自己維護相依清單，平台會列出來。

善用版本紀錄¶

• 每次按「動作」>「更新」，平台就會留下一版；到詳細頁的「版本紀錄」分頁可以比對與還原，見 版本紀錄。
• 還原是「往前多加一版」，不是把歷史倒回去，所以還原後記得再試跑一次。
• 要留一份平台之外的備份，用「動作」>「下載定義」把定義存成檔案。

上線後定期檢視¶

平台沒有自動警報功能，所以「監控」實際上是安排人定期看這幾個地方：

• 工作流程詳細頁的「執行」分頁：看最近的執行是成功還是失敗、花了多久。
• 失敗的執行點進去看「歷史」分頁，確認停在哪一步。
• 管理員可到「用量」頁看整體呼叫量與預估成本，見 用量。

安全性¶

驗證輸入¶

絕不信任使用者輸入：

• 驗證必填欄位
• 檢查資料類型和格式
• 在查詢中使用前先清理
• 限制輸入大小

控制存取¶

管理誰可以做什麼。平台的權限單位是群組，不是逐個使用者設定：

• 依職務規劃群組，再把人加進群組，不要所有人共用同一個群組
• 在群組的「資源存取」只授權真正需要的資源，並依需要選 Read（唯讀）而非 Write
• 只把必要的人設為「管理員」角色（角色只有「管理員」與「使用者」兩種）
• 定期請管理員檢視各群組四個權限分頁的清單，移除不再需要的授權

設定方式見 群組 與 使用者。

保護敏感資料¶

小心處理敏感資訊：

• 不要記錄敏感資料
• 在可能的情況下在輸出中遮罩個人識別資訊
• 對外部呼叫使用安全連線
• 遵守資料保留政策