疑難排解¶

本指南涵蓋使用 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`	憑證無效	使用正確的憑證更新資源

整頁的錯誤畫面¶

有時候看到的不是欄位旁的紅字，而是整頁只剩一張卡片：中間一個大圖示、一行標題、一行說明和一顆按鈕。左側選單與麵包屑都不見了，這是平台的錯誤頁，共三種：

畫面	什麼時候出現	該怎麼辦
找不到頁面「你要找的頁面不存在或已被移除。」	網址打錯、連結過期，或那個項目已經被刪掉	按「回首頁」回到起點，再從選單重新點進去。書籤失效多半屬於這一類。
目前處於離線狀態「網路連線中斷，請檢查網路連線後再試。」	在沒有網路的狀態下開啟或重新整理一頁，資料載不進來	檢查網路（Wi-Fi、VPN）後按「重試」，不必重新登入。
伺服器錯誤「發生錯誤，請稍後再試。」	載入這一頁的資料時後端出錯	先按「回首頁」再走一次；持續發生請帶著時間與網址洽管理員。

網路是中途斷掉的話，看到的不是整頁錯誤

已經開著某一頁、操作到一半才斷線時，畫面不會變成上面那張離線卡片：側邊欄與已經載進來的資料都還在，只有畫面下方浮出一條紅色提示「網路連線中斷，請檢查網路連線後再試。」，沒有圖示也沒有「重試」鈕。整頁的離線卡片是在沒有網路時才去開一頁（或按重新整理）才會出現。

按鈕偶爾會是英文的「Back to home」

直接在網址列輸入一個不存在的網址、整頁重新載入時，按鈕可能顯示英文的「Back to home」而不是「回首頁」——作用完全一樣。從平台內部點連結過去時顯示的是中文。

取得協助¶

如果無法解決問題：

查閱文件：檢視相關指南和教學
用本手冊右上角的搜尋：把錯誤訊息或欄位名稱貼進去找對應章節
收集資訊：記錄錯誤訊息、工作流程設定和重現步驟
聯絡貴單位的平台管理員：附上下列資訊。平台本身沒有內建的客服或工單入口，對外支援管道請向管理員索取

尋求協助時應提供的資訊¶

工作流程名稱和 ID
重現問題的步驟
預期行為 vs 實際行為
錯誤訊息（完整文字）
設定的截圖
最近所做的變更