最佳實踐¶

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

Workflow 設計¶

保持 workflow 專注¶

設計每個 workflow 完成單一、明確定義的任務。

建議：

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

避免：

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

規劃資料流¶

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

檢查清單：

• [ ] 定義清楚的 Input Schema 和必填欄位
• [ ] 規劃每個 Action 的輸出
• [ ] 識別需要的資料轉換
• [ ] 設計乾淨結果的 Output Schema

使用有意義的名稱¶

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

好的名稱：

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

不好的名稱：

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

LLM Action¶

撰寫有效的提示詞¶

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

準則：

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

提示詞結構範例：

You are a [role]. Your task is to [specific task].

Context:
- [relevant information]
- [constraints]

Input: {{ user_input }}

Output requirements:
- [format specifications]
- [length limits]
- [quality criteria]

使用 Structured LLM 獲得可靠的輸出¶

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

• 使用定義了 Output Schema 的 Structured LLM Action
• 保持 schema 簡單且定義良好
• 包含欄位描述以獲得更好的準確度

處理 LLM 限制¶

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

• 設定合理的 token 限制
• 為關鍵輸出加入驗證
• 為非預期的回應實作備援
• 使用多樣化的輸入進行測試

錯誤處理¶

為失敗做設計¶

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

策略：

設定適當的重試¶

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

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

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

提供優雅降級¶

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

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

Resource 管理¶

一致地組織 resource¶

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

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

保護憑證¶

保護敏感資訊：

• 絕不在 workflow 設定中硬編碼憑證
• 使用 resource 設定儲存 API 金鑰
• 定期更換憑證
• 定期稽核 resource 存取

監控 resource 使用¶

追蹤 resource 消耗：

• 監控 LLM API 使用量和成本
• 注意速率限制問題
• 追蹤資料庫連線使用
• 為異常模式設定警報

效能最佳化¶

最小化不必要的處理¶

最佳化 workflow 效率：

• 只保留必要的輸出欄位以減少 state 大小（即「Output Selector」，詳見下方說明）
• 在 workflow 早期過濾資料
• 避免冗餘的 LLM 呼叫
• 在適當的地方快取結果

明智地使用平行執行¶

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

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

設定適當的逾時¶

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

適當處理大型資料¶

對於大型文件或回應：

• 當資料可能超過 workflow 狀態上限（256 KB）時，改用 External Memory
• 為大型結果集實作分頁
• 傳給 LLM 前先摘要
• 使用 Output Selector 限制 state 大小

測試與驗證¶

漸進式測試¶

分階段建立和測試 workflow：

1. 使用 Test Action 功能測試單一 Action（在編輯器點選該節點打開設定面板，右上角的「Test Action」按鈕即可單獨試跑這一步；此按鈕在平台上維持英文顯示）
2. 測試 Action 序列
3. 使用代表性輸入測試完整 workflow
4. 測試邊界情況和錯誤情境

使用代表性測試資料¶

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

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

上線前驗證¶

部署前：

• [ ] 所有 Action 都已單獨測試
• [ ] 完整 workflow 已端對端測試
• [ ] 錯誤處理已驗證
• [ ] 效能可接受
• [ ] 輸出格式已驗證

維護¶

記錄你的 workflow¶

為每個 workflow 維護文件：

• 目的和使用案例
• 輸入/輸出規格
• 相依性（resource、其他 workflow）
• 已知限制
• 變更歷史

版本控制實踐¶

追蹤 workflow 變更：

• 定期匯出 workflow 定義
• 使用描述性的提交訊息
• 從匯出還原後進行測試
• 保留可運作設定的備份

在生產環境中監控¶

追蹤 workflow 健康狀態：

• 監控執行成功率
• 追蹤執行時間
• 失敗時發出警報
• 定期檢視錯誤模式

安全性¶

驗證輸入¶

絕不信任使用者輸入：

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

控制存取¶

管理誰可以做什麼：

• 適當使用工作區角色
• 將 resource 存取限制在必要的使用者
• 定期檢視權限
• 稽核敏感操作

保護敏感資料¶

小心處理敏感資訊：

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