疑難排解¶
本指南涵蓋使用 Headquarter.ai 時可能遇到的常見問題及其解決方案。
工作流程問題¶
工作流程無法啟動¶
症狀：在「執行」畫面按「開始」沒有反應或顯示錯誤。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 缺少必填輸入 | 檢查「開始」節點的「輸入結構」，確保「執行」畫面上每個必填欄位都填了 |
| 輸入格式無效 | 確認輸入資料符合「輸入結構」裡定義的類型（String、Number、Object 等） |
| 工作流程未更新 | 執行前在編輯器右上角點「動作」>「更新」儲存變更（編輯時雖會自動顯示「草稿已儲存」，但那只是暫存草稿，要正式生效仍須手動點「更新」） |
| 資源不可用 | 檢查所有引用的資源（大型語言模型、檢索器等）狀態是否為「就緒」 |
任務未按預期順序執行¶
症狀：工作流程跳過任務或以錯誤順序執行。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 「下一個狀態」不正確 | 確認每個任務設定面板的「下一個狀態」指向正確的下一個任務 |
| 節點未連接 | 確保畫布上的所有節點都串在流程圖裡，沒有孤立節點 |
| 條件邏輯錯誤 | 檢查「依條件分類」節點的條件設定，見 流程控制節點 |
| 平行執行 | 平行分支的完成順序可能與啟動順序不同；用一個「傳遞資料任務」當彙整點 |
工作流程逾時¶
症狀：執行停止並顯示逾時錯誤。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 大型語言模型呼叫時間過長 | 改用更快的模型或縮小輸入 |
| 外部 API 或查詢緩慢 | 少數任務有自己的逾時欄位可調（Athena 任務的「等待逾時」、OpenSearch 任務的「逾時」、Agent 任務的「WebSocket 閒置逾時」）；HTTPS API 任務沒有逾時欄位，只能從對方服務或縮小請求範圍著手 |
| 無限迴圈 | 檢查條件邏輯以確保滿足終止條件 |
| 大量資料處理 | 拆分大型操作或改用外部記憶體 |
節點設定面板沒有通用的逾時欄位
「設定」分頁中的「執行設定」區塊只有「上傳輸出至外部記憶體」、兩個即時輸出串流開關與「錯誤時中止」（都是滑動開關，不是勾選框），沒有逾時欄位。也就是說，多數任務無法在畫面上「把逾時調長」，遇到太慢只能改用更快的模型、縮小輸入或把大型操作拆小。
大型語言模型任務問題¶
空白或非預期的回應¶
症狀：模型回傳空字串或非預期的內容。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 提示詞有問題 | 檢查「對話」表格每一列的「角色」與「內容」，見 大型語言模型任務 |
| 缺少上下文 | 確認打開「JSONPath」開關的欄位確實取到了資料（可用該任務的測試按鈕試跑，看輸入是不是空的） |
| 模型限制 | 某些查詢可能超出模型能力；簡化請求 |
| 超過 token 限制 | 減少輸入大小或先摘要再送給模型 |
JSONPath 引用無效¶
症狀：像 $.question 這樣的變數無法解析為值。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 路徑錯誤 | 確認欄位名稱完全匹配（區分大小寫） |
| 欄位不存在 | 把欄位加進「開始」節點的「輸入結構」，或確認前一個任務真的有輸出它 |
| 引用中有錯字 | 檢查 JSONPath 運算式中的錯字 |
| 順序問題 | 被引用的任務必須排在這個任務前面 |
資源問題¶
選不到大型語言模型資源¶
症狀：無法在任務設定中選擇大型語言模型。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 資源未建立 | 前往「資源」建立大型語言模型資源 |
| API 金鑰無效 | 使用有效的憑證更新資源 |
| 供應商服務中斷 | 檢查該模型供應商的狀態頁面 |
| 權限問題 | 一般使用者只看得到管理員授權給自己群組的資源。請管理員到「群組」的「資源存取」把該資源授權給你的群組，見 群組 |
檢索器沒有回傳結果¶
症狀：檢索器任務回傳的 documents 是空的。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 沒有匹配的文件 | 確認知識庫包含相關內容 |
| 查詢太具體 | 放寬搜尋查詢 |
| 知識庫還沒灌資料，或來源已更新但沒重新同步 | 到對應載入器的「同步任務」分頁按「開始新的同步任務」；要整庫重建就在對話框開啟「強制執行完整同步」 |
| 接錯知識庫 | 檢查檢索器是否連接到正確的知識庫 |
連結器連線失敗¶
症狀：MySQL 或其他連結器相關任務無法連線。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 憑證錯誤 | 到該連結器的編輯表單確認主機、帳號、密碼，並按右上角的「測試連線」／「驗證憑證」確認 |
| 網路問題 | 檢查防火牆規則和網路連線（通常需要貴單位的網路或資料庫管理者協助） |
| 資料庫不可用 | 確認資料庫伺服器正在執行 |
| 連線數達到上限 | 平台端沒有可調的連線數設定；請資料庫管理者確認該帳號的連線數上限與目前用量 |
畫布和編輯器問題¶
畫布沒有回應¶
症狀：無法點擊或拖曳畫布上的節點。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 瀏覽器問題 | 重新整理頁面或嘗試其他瀏覽器 |
| 覆蓋層阻擋 | 按 Escape 關閉任何開啟的對話視窗或側邊欄 |
| 工作流程太大 | 縮小或捲動以找到工作區域 |
設定面板未顯示¶
症狀：點擊節點沒有開啟其設定。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 節點未選取 | 直接點擊節點（不是連線） |
| 面板已收合 | 尋找右側的展開按鈕 |
| UI 異常 | 重新整理頁面 |
變更未儲存¶
症狀：重新整理後編輯內容遺失。
可能原因與解決方案：
| 原因 | 解決方案 |
|---|---|
| 未點擊更新 | 修改後務必在編輯器右上角點「動作」>「更新」；畫面上的「草稿已儲存」只是暫存，與正式「更新」是兩件事 |
| 驗證錯誤 | 檢查表單欄位中的錯誤訊息 |
| 工作階段過期 | 重新驗證後再試一次 |
執行與除錯¶
如何除錯工作流程問題¶
- 檢查執行紀錄：到工作流程詳細頁的「執行」分頁查看過去的執行
- 檢視狀態資料：開啟某筆執行，切到「歷史」分頁，看每一步進出的資料
- 測試單一任務：點選該節點打開設定面板，按面板右上角的「測試任務」按鈕（）單獨試跑，隔離問題
- 加入記錄：用「程式碼任務」把中間結果輸出出來看
- 簡化：建立最小的工作流程來重現問題
閱讀執行記錄¶
執行結果頁的欄位在平台上以中文顯示，對照如下：
- 輸入（Input）：傳給工作流程的內容
- 輸出（Output）：工作流程回傳的內容
- 狀態（Status）：顯示中文值，例如「成功」（對應 SUCCEEDED）、「失敗」（FAILED）、「逾時」（TIMED_OUT）
- 執行時間（Duration）：執行花費的時間，另有「開始時間／停止時間」
- 歷史（State history）：每個步驟的資料（如果有的話）
常見錯誤訊息¶
| 錯誤 | 意思 | 解決方案 |
|---|---|---|
Resource not found | 引用的資源不存在 | 建立資源或修正引用 |
Invalid input | 輸入不符合 schema | 檢查輸入格式和必填欄位 |
Execution timeout | 花費時間過長 | 平台沒有可調高的通用逾時欄位；請改用更快的模型、縮小輸入，或把大型操作拆成多個步驟 |
Rate limit exceeded | API 呼叫次數過多 | 加入延遲或減少呼叫頻率 |
Authentication failed | 憑證無效 | 使用正確的憑證更新資源 |
取得協助¶
如果無法解決問題：
- 查閱文件：檢視相關指南和教學
- 用本手冊右上角的搜尋：把錯誤訊息或欄位名稱貼進去找對應章節
- 收集資訊：記錄錯誤訊息、工作流程設定和重現步驟
- 聯絡貴單位的平台管理員：附上下列資訊。平台本身沒有內建的客服或工單入口，對外支援管道請向管理員索取
尋求協助時應提供的資訊¶
- 工作流程名稱和 ID
- 重現問題的步驟
- 預期行為 vs 實際行為
- 錯誤訊息（完整文字）
- 設定的截圖
- 最近所做的變更