疑難排解¶
本指南涵蓋使用 Headquarter.ai 時可能遇到的常見問題及其解決方案。
Workflow 問題¶
Workflow 無法啟動¶
症狀：點擊「Start」沒有反應或顯示錯誤。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 缺少必填輸入 | 檢查 Start 節點的 Input Schema，確保提供所有必填欄位 |
| 輸入格式無效 | 確認輸入資料符合預期的類型（String、Number、Object 等） |
| Workflow 未更新 | 執行前在編輯器右上角點「動作」>「更新」儲存變更（編輯時雖會自動顯示「草稿已儲存」，但那只是暫存草稿，要正式生效仍須手動點「更新」） |
| Resource 不可用 | 檢查所有引用的 resource（LLM、Retriever 等）是否處於活動狀態 |
Action 未按預期順序執行¶
症狀：Workflow 跳過 Action 或以錯誤順序執行。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| Next State 不正確 | 確認每個 Action 的 Next State 指向正確的下一個 Action |
| 節點未連接 | 確保畫布上的所有節點都在 workflow 圖中連接 |
| 條件邏輯錯誤 | 檢查 Lambda 運算式或分支條件 |
| 平行執行 | Action 完成順序可能與啟動順序不同；使用彙整點 |
Workflow 逾時¶
症狀：執行停止並顯示逾時錯誤。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| LLM 呼叫時間過長 | 改用更快的模型或縮小輸入（節點設定面板「設定」分頁中的「執行設定」區塊目前沒有逾時欄位，無法在該處直接調整逾時） |
| 外部 API 緩慢 | 為 HTTPS API Action 設定適當的逾時 |
| 無限迴圈 | 檢查條件邏輯以確保滿足終止條件 |
| 大量資料處理 | 拆分大型操作或使用 External Memory |
LLM Action 問題¶
空白或非預期的回應¶
症狀：LLM 回傳空字串或非預期的內容。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 提示詞無效 | 檢查 Messages 設定是否有語法錯誤 |
| 缺少上下文 | 確認 JSONPath 引用解析為實際資料 |
| 模型限制 | 某些查詢可能超出模型能力；簡化請求 |
| 超過 token 限制 | 減少輸入大小或使用摘要 |
JSONPath 引用無效¶
症狀：像 $.question 這樣的變數無法解析為值。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 路徑錯誤 | 確認欄位名稱完全匹配（區分大小寫） |
| 欄位不在 schema 中 | 將欄位新增到 Input Schema 或前一個 Action 的輸出 |
| 引用中有錯字 | 檢查 JSONPath 運算式中的錯字 |
| 範圍問題 | 確保引用的 Action 已經執行 |
Resource 問題¶
LLM resource 不可用¶
症狀：無法在 Action 設定中選擇 LLM。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| Resource 未建立 | 前往 Resources 建立 LLM resource |
| API 金鑰無效 | 使用有效的憑證更新 resource |
| 供應商服務中斷 | 檢查 LLM 供應商的狀態頁面 |
| 權限問題 | 確認你在工作區中有存取該 resource 的權限 |
Retriever 沒有回傳結果¶
症狀：Retriever Action 回傳空的 documents 陣列。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 沒有匹配的文件 | 確認 knowledge base 包含相關內容 |
| 查詢太具體 | 放寬搜尋查詢 |
| 索引未建立 | 重建 knowledge base 索引 |
| Knowledge base 錯誤 | 檢查 retriever 是否連接到正確的 knowledge base |
Connector 連線失敗¶
症狀：MySQL 或其他 connector Action 無法連線。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 憑證錯誤 | 確認使用者名稱、密碼和連線字串 |
| 網路問題 | 檢查防火牆規則和網路連線 |
| 資料庫不可用 | 確認資料庫伺服器正在執行 |
| 連線數達到上限 | 檢查連線池是否已耗盡 |
畫布和編輯器問題¶
畫布沒有回應¶
症狀：無法點擊或拖曳畫布上的節點。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 瀏覽器問題 | 重新整理頁面或嘗試其他瀏覽器 |
| 覆蓋層阻擋 | 按 Escape 關閉任何開啟的對話視窗或側邊欄 |
| Workflow 太大 | 縮小或捲動以找到工作區域 |
設定面板未顯示¶
症狀：點擊節點沒有開啟其設定。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 節點未選取 | 直接點擊節點（不是連線） |
| 面板已收合 | 尋找右側的展開按鈕 |
| UI 異常 | 重新整理頁面 |
變更未儲存¶
症狀：重新整理後編輯內容遺失。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 未點擊更新 | 修改後務必在編輯器右上角點「動作」>「更新」；畫面上的「草稿已儲存」只是暫存，與正式「更新」是兩件事 |
| 驗證錯誤 | 檢查表單欄位中的錯誤訊息 |
| 工作階段過期 | 重新驗證後再試一次 |
執行與除錯¶
如何除錯 workflow 問題¶
- 檢查執行歷史：在 workflow 的執行清單中查看過去的執行
- 檢視狀態資料：檢查每個 Action 的狀態以查看資料流
- 測試單一 Action：點選該節點打開設定面板，使用右上角的「Test Action」按鈕隔離問題（此按鈕在平台上維持英文顯示）
- 加入記錄：使用 Lambda Action 輸出除錯資訊
- 簡化：建立最小的 workflow 來重現問題
閱讀執行記錄¶
執行結果頁的欄位在平台上以中文顯示，對照如下：
- 輸入（Input）：傳給 workflow 的內容
- 輸出（Output）：workflow 回傳的內容
- 狀態（Status）：顯示中文值，例如「成功」（對應 SUCCEEDED）、「失敗」（FAILED）、「逾時」（TIMED_OUT）
- 執行時間（Duration）：執行花費的時間，另有「開始時間／停止時間」
- 歷史（State history）：每個步驟的資料（如果有的話）
常見錯誤訊息¶
| 錯誤 | 意思 | 解決方案 |
|---|---|---|
Resource not found | 引用的 resource 不存在 | 建立 resource 或修正引用 |
Invalid input | 輸入不符合 schema | 檢查輸入格式和必填欄位 |
Execution timeout | 花費時間過長 | 增加逾時或最佳化 workflow |
Rate limit exceeded | API 呼叫次數過多 | 加入延遲或減少呼叫頻率 |
Authentication failed | 憑證無效 | 使用正確的憑證更新 resource |
取得協助¶
如果無法解決問題：
- 查閱文件：檢視相關指南和教學
- 搜尋類似問題：問題可能有已知的解決方案
- 收集資訊：記錄錯誤訊息、workflow 設定和重現步驟
- 聯繫支援：提供收集的資訊
尋求協助時應提供的資訊¶
- Workflow 名稱和 ID
- 重現問題的步驟
- 預期行為 vs 實際行為
- 錯誤訊息（完整文字）
- 設定的截圖
- 最近所做的變更