TokenLab 請求控制台：從單一儀表板除錯 AI API 呼叫

失敗的 AI API 呼叫很少會明確地告知原因。你通常只會得到一個狀態碼、可能還有一串錯誤訊息，以及一個支援管道，然後有人會問：「請求 ID 是什麼？」如果你手邊沒有這個 ID，調查工作在開始前就會停滯。我們建立了 TokenLab Request Console，將請求層級的詳細資訊整合到單一儀表板視圖中，以縮短這段差距。它會顯示模型、金鑰、快取狀態、計費狀態、時間以及經過遮蔽的負載預覽。在我們的管線中，我們將請求 ID 視為首要的查詢鍵。

重點摘要

• TokenLab Request Console 是 TokenLab API 儀表板內的請求層級除錯介面，而非計費報告。
• 每個請求都有一個你可以直接搜尋的 ID。你可以透過 URL 中的 requestId 深度連結到特定請求。
• 該控制台會顯示近期請求的路由、計費狀態、快取狀態、模型/金鑰上下文以及經過遮蔽的負載預覽。
• 存取權限受限於你的組織，並由儀表板成員權限管理——團隊成員只能看到其角色允許的內容。
• 若要進行單一事件除錯，請使用控制台。若要跨時間範圍進行批次成本審查，請改用使用量匯出功能。

什麼是 TokenLab Request Console

你可以在 TokenLab 儀表板的 API 區塊中，透過 /dashboard/api?tab=requestConsole 存取它。API 儀表板本身位於 /dashboard/api。該控制台建立在一個前提之上：當請求失敗時，最快的修復方法是直接掌握其完整上下文，而不是僅憑錯誤訊息進行猜測。

儀表板說明將控制台描述為近期請求的檢查器，涵蓋路由、計費、請求/回應主體以及模型供應商上下文。我們將其細分為幾個工作區塊：

列表視圖 (List view)。 一個可篩選的近期請求表格。當你還沒有特定的請求 ID 時，可以從這裡開始。你可以掃描失敗或異常的呼叫。

檢查器面板 (Inspector panel)。 當你選擇一個請求後，檢查器會開啟並顯示完整細節：由哪個模型提供服務、使用了哪個 API 金鑰、是否命中快取，以及最終狀態為何。

錯誤上下文 (Error context)。 如果請求失敗，控制台會顯示與該特定呼叫相關的錯誤資訊。你無需再交叉比對獨立的錯誤日誌。

路由與計費狀態 (Route and billing state)。 顯示請求如何路由，以及它是已計費、待處理、已退款還是已失敗。當客戶詢問「我是否為該錯誤付費了？」時，這四種狀態最為重要。

負載預覽 (Payload preview)。 在可用時，請求和回應主體會以遮蔽後的預覽形式顯示，讓你了解其形狀與結構，而不會在主體中暴露原始機密。

模型供應商與模型金鑰上下文 (Model vendor and model key context)。 顯示處理該呼叫的供應商及特定模型。當你在單一整合後方執行多個模型，並需要確認是否呼叫了正確模型時，這非常有用。

這一切都不需要你在 API 之上建立自己的日誌管線。它已經針對每個組織呈現，並透過儀表板成員權限進行篩選，因此擁有適當存取權限的團隊成員可以看到與你相同的請求資料。

首先檢查什麼

當 API 呼叫失敗時，檢查事項有其自然的順序。在確認請求是否確實到達正確端點之前，就直接跳到「模型是否當機」的檢查，只會浪費時間。

五欄分類法

檢查項目	它告訴你的資訊
請求 ID (Request ID)	確認你正在查看的是該特定呼叫，而非類似的呼叫
狀態 (Status)	已計費、待處理、已退款或已失敗 — 告訴你這是成本問題還是技術問題
模型 (Model)	實際服務該請求的模型（當你跨多個模型路由時很有用）
快取狀態 (Cache state)	提示快取命中或未命中是否改變了成本或延遲
金鑰來源 (Key source)	使用了哪個 API 金鑰，當多個金鑰或環境共用一個整合時很有用

從請求 ID 開始。如果你是從用戶端日誌、支援票證或錯誤報告中獲得該 ID，請使用深度連結模式：

/dashboard/api?tab=requestConsole&requestId=%3Crequest_id>

這會直接在該請求上開啟檢查器，完全跳過列表視圖。當有人給你一個 ID 並詢問「這裡發生了什麼事」時，這是最快的路徑。

如果你還沒有請求 ID，控制台的篩選器讓你能夠依據模型、時間範圍、提示快取狀態、金鑰來源和狀態進行縮小範圍。例如，當請求失敗時，篩選「失敗」狀態並設定為過去一小時，然後掃描列表以找到使用者詢問的特定呼叫。

正確解讀狀態欄位

這四種狀態——已計費、待處理、已退款、已失敗——回答了不同的問題：

• 已計費 (Billed) 表示呼叫已完成並消耗了額度。如果使用者回報錯誤，但請求顯示已計費，這值得單獨標記。這暗示失敗發生在收到成功回應後的用戶端。
• 待處理 (Pending) 表示請求仍在傳輸中或等待結算。請勿過早將其視為失敗。
• 已退款 (Refunded) 表示 TokenLab 已撤銷該費用，通常與供應商或路由端的失敗有關。
• 已失敗 (Failed) 表示呼叫未成功完成且未計費。

在升級問題之前先了解適用哪種狀態，可以省去與支援團隊來回溝通的麻煩。

確認模型與快取狀態

如果你透過共用整合對 Claude Sonnet 5、DeepSeek V4 Pro 或 Gemini 3.5 Flash 等模型執行請求，請確認控制台顯示的是你預期的模型。設定錯誤的用戶端、過時的環境變數或路由覆寫，都可能在沒有明顯用戶端錯誤的情況下將流量發送到錯誤的模型。

快取狀態對成本和延遲都很重要。在你預期命中卻發生快取未命中，通常意味著提示前綴發生了變化，即使是很細微的變化。請檢查時間戳記、重新排序的欄位或額外的空白字元。控制台的快取狀態篩選器讓你能夠並排比較命中與未命中的請求。

TokenLab Request Console 如何與使用量匯出功能協作

Request Console 與使用量匯出功能解決的是不同的問題，因此明確界定兩者的邊界很有幫助。控制台是為單一請求調查而建：一個呼叫、一個錯誤、一個計費問題，在檢查器面板中即可解答。當特定請求失敗且你需要立即知道原因時，請開啟它。

使用量匯出功能是為總體審查而建：特定時間範圍內的支出、按模型或金鑰分類的明細，以及你會交給財務利害關係人或用於月度對帳的報告。如果你想回答「我們上週在 DeepSeek V4 Pro 上花了多少錢」，那是匯出功能的問題，而非控制台的問題。請參閱 TokenLab 儀表板使用量匯出指南以了解該工作流程。

簡而言之：控制台用於處理事件，匯出功能用於統計總額。有些團隊會依序使用兩者。匯出功能會顯示總體支出中的異常，而控制台則是讓你深入調查導致該異常的特定請求。

實用的除錯常規

臨時除錯在壓力下會變成猜測。一套可重複的常規可以防止事件拖延過久。

檢查清單：當請求失敗時

1. 取得請求 ID。 從你的用戶端日誌、錯誤回應或使用者報告中取得。如果你目前沒有記錄請求 ID，現在就開始吧。這是你擁有的最快查詢鍵。
2. 使用深度連結開啟控制台。 使用 requestId 查詢參數直接跳轉到檢查器。
3. 首先檢查狀態欄位。 已計費、待處理、已退款或已失敗。這將為後續的調查定調。
4. 確認實際服務該請求的模型。 將其與你預期發送的模型進行比較。
5. 檢查快取狀態。 在預期命中卻未命中的情況下，可以解釋非預期的延遲或成本。
6. 檢查金鑰來源。 確認使用了正確的 API 金鑰和環境，特別是在預備環境 (staging) 與生產環境 (production) 的設定中。
7. 閱讀錯誤上下文與路由資訊。 這通常是實際根本原因變得明顯的地方。
8. 檢閱遮蔽後的負載預覽。 確認請求形狀與你的用戶端發送的內容相符。格式錯誤的參數通常會在這裡顯示，而不是在其他任何地方。
9. 必要時交叉比對 API 參考文件。 位於 https://docs.tokenlab.sh/api-reference/chat/create-completion 的 TokenLab 聊天完成 API 參考文件記錄了預期的請求與回應形狀。使用它來確認負載是否在用戶端格式錯誤。
10. 如果是模式而非單一事件，請切換至使用量匯出。 單一失敗請求是控制台問題。一小時內十個失敗請求則是一個值得匯出並進行總體審查的模式。

遵循此順序——ID、狀態、模型、快取、金鑰、錯誤、負載——可以防止你跳過真正解釋失敗原因的欄位。

常見問題 (FAQ)

如何在沒有請求 ID 的情況下找到失敗的請求？

使用 TokenLab Request Console 中的列表視圖篩選器。依據模型、時間範圍、提示快取狀態、金鑰來源和狀態縮小範圍。例如，篩選「失敗」狀態並設定為過去一小時，然後掃描使用者詢問的呼叫。找到後，開啟檢查器並複製請求 ID 以供日後日誌使用。

為什麼用戶端回報錯誤時，請求卻顯示已計費？

已計費表示呼叫已完成並消耗了額度。如果使用者回報錯誤但請求顯示已計費，失敗很可能發生在收到成功回應後的用戶端。請單獨標記該案例，因為它指向的修復路徑與失敗或已退款的請求不同。

檢查器中的快取未命中告訴我什麼？

快取未命中表示請求未命中提示快取。這對成本和延遲很重要。在你預期命中卻發生未命中，通常意味著提示前綴發生了變化，即使是很細微的變化。請檢查時間戳記、重新排序的欄位或額外的空白字元。

我可以與團隊成員分享請求連結嗎？

可以，如果他們的儀表板成員權限允許的話。請求資料受限於你的組織。使用深度連結格式 /dashboard/api?tab=requestConsole&requestId=<request_id> 直接開啟檢查器。團隊成員只能看到其角色允許的內容。

我什麼時候應該從控制台切換到使用量匯出？

當問題是一種模式而非單一事件時請切換。單一失敗請求是控制台問題。一小時內十個失敗請求則是一個值得匯出並進行總體審查的模式。請使用匯出功能來處理特定時間範圍內的支出、按模型或金鑰分類的明細以及月度對帳。

來源與時效性

• TokenLab Request Console — /dashboard/api?tab=requestConsole — 觀察於 2026-07-09
• TokenLab Chat Completions API 參考文件 — https://docs.tokenlab.sh/api-reference/chat/create-completion — 觀察於 2026-07-09
• TokenLab 儀表板使用量匯出 — /blog/tokenlab-dashboard-usage-exports — 觀察於 2026-07-09
• TokenLab 公開模型目錄 — /models — 觀察於 2026-07-09
• TokenLab API 金鑰儀表板 — /dashboard/api — 觀察於 2026-07-09

所引用的模型範例（Claude Sonnet 5、DeepSeek V4 Pro、Gemini 3.5 Flash）反映了截至 2026-09-19 的當前模型 SSOT。本控制台說明的來源快照觀察於 2026-07-09；來源中的原始模型 SSOT 日期為 2026-07-07。

後續步驟

如果你目前透過 grep 用戶端日誌並交叉比對獨立的計費儀表板來除錯 AI API 失敗，Request Console 可以從該迴圈中移除一個步驟。控制台位於 /dashboard/api?tab=requestConsole。API 金鑰儀表板位於 tokenlab.sh/dashboard/api。聊天完成請求/回應形狀記錄於 https://docs.tokenlab.sh/api-reference/chat/create-completion。若要進行總體支出審查，請使用 使用量匯出。有關模型定價和上下文視窗詳細資訊，請參閱 模型目錄。現在就開啟控制台並按 ID 尋找最近的失敗請求。