核心指南
日誌與疑難排解
保留追蹤請求、任務與費用所需的 ID
請在您的日誌中保留 TokenLab 的請求、任務與帳單 ID。它們能將使用者操作與其結果及費用連結起來,且無需儲存提示詞 (prompt) 或私人媒體內容。
在 Console 中,擷取的請求與回應詳細資訊會在擷取後保留 30 天,即使物理清理作業仍在排程中,存取權也會在到期時精確終止。請求識別資訊與帳單/使用量記錄擁有獨立的生命週期。請參閱 資料保留。
從請求到調查與支援
-
在擁有該請求的工作區中開啟 Runs。找到其 Request ID 並選取該列。
-
選擇 Open full details 以進入專屬頁面。Back to requests 可還原列表篩選器。連結絕不會授予對其他工作區的存取權;請使用該工作區授權的帳號。
-
若狀態為擱置中或未知,請先重新整理進度。若回應失敗或中斷,請在可用時選擇 Investigate the issue。這會針對該請求在應用程式內的 Agent 中啟動調查;它不會重新執行原始的模型請求。成功的請求預設不需要調查。
-
若您仍需協助,請從請求或調查中選擇人工支援動作。這會在可用時開啟一個包含連結請求與對話的預覽視窗。請檢閱摘要並移除私人內容,然後明確選擇 Submit。單獨的調查或預覽不會發送支援請求。
-
提交後,請保留確認資訊並在 Support 中繼續相同的對話。請重複使用該對話進行回覆與補充資訊,而非提交重複的請求。
應保留的 ID
| 識別碼 | 出現位置 | 用途 |
|---|---|---|
request_id | 錯誤主體、儀表板日誌、使用量記錄 | 請求層級的支援與對帳 |
id / task_id | 非同步建立與狀態回應 | 使用 GET /v1/tasks/{id} 輪詢任何非同步工作 |
poll_url | 非同步建立回應 | 狀態 URL;使用 id 輪詢 /v1/tasks/{id} |
billing_transaction_id | 結算後的非串流回應、非同步任務狀態回應、使用量記錄、X-Billing-Transaction-ID | 成本對帳 |
X-Task-ID | 非同步任務回應標頭 | 標頭層級的任務關聯 |
| 您自己的工作/使用者 ID | 您的應用程式 | 尋找使用者操作對應的 TokenLab 請求 |
面向客戶的記錄應使用 TokenLab ID。切勿公開私人服務 URL、快取鍵或診斷元資料。
應記錄的內容
記錄足以診斷請求的資訊,但不要洩漏機密:
- 端點、HTTP 方法、模型、狀態碼、時間戳記與延遲。
- 公開識別碼:
request_id、task_id、poll_url與billing_transaction_id(若存在)。 - 請求中發送的欄位名稱,而非完整的提示詞或私人媒體內容。
- 最終的非同步狀態回應與安全的錯誤欄位。
- 客戶端重試次數,以及重試是建立新任務還是恢復現有任務。
除非您擁有明確的保留許可,否則請務必遮蔽 Authorization、API 金鑰、管理權杖 (management tokens)、簽章 URL、私人媒體 URL、完整提示詞與使用者個人資料。
疑難排解矩陣
| 徵狀 | 優先檢查項目 | 實用頁面 |
|---|---|---|
401 或 403 | API 金鑰、管理權杖、組織存取權、金鑰範圍 | 驗證 |
402 | 餘額、API 金鑰消費上限 | 帳單與定價 |
429 | 帳戶層級、端點速率限制、重試行為 | 速率限制 |
400 invalid_request_error | 不支援的欄位、錯誤的端點、缺少必要欄位或模型請求不符 | 錯誤處理 |
| 找不到非同步任務 | 錯誤的 API 金鑰、輸入錯誤的 ID 或任務已過期 | 非同步工作與輪詢 |
| 成本與 UI 不符 | 結算時間差或比對了錯誤的識別碼 | 帳單與定價 |
使用量對帳
使用 Management API 進行伺服器端對帳:
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
-H "Authorization: Bearer mt-your-management-token"GET /v1/management/api-keys/{keyId}/usage 可以透過 scene、model、modelVendor、startDate 與 endDate 進行篩選。請使用這些記錄,而非抓取 Console 頁面或僅從回應 Token 數量計算費用。僅包含日期的 endDate 代表該日期的 00:00 UTC;請參閱 取得 API 金鑰使用量。
串流回應可能會在串流發送後才結算,因此即使稍後記錄了使用量,帳單標頭也可能不存在。非同步媒體任務可能會在終端輪詢後結算。
提供給支援團隊的資訊
聯繫支援團隊時,請包含:
request_id。- 非同步工作的
task_id與poll_url。 billing_transaction_id(若存在)。- 端點、方法、模型、時間戳記與狀態碼。
- 請求欄位名稱與安全的錯誤主體。
- 您的預期結果以及使用者實際看到的內容。
請勿包含 API 金鑰、管理權杖、私人媒體、完整提示詞、私人服務 URL 或診斷識別碼。若支援團隊需要請求範例,請發送遮蔽後的副本。
值得自動化的檢查項目
- 分別針對重複的
401、402、429與5xx回應發出警報;每一種都需要不同的處理方式。 - 追蹤超過您產品 SLA 仍未結束的非同步工作。
- 追蹤針對相同使用者工作 ID 的重複建立嘗試。
- 抽樣已完成的工作,並驗證使用者可見的資產、使用量記錄與儲存的任務記錄是否一致。
API 參考
| 主題 | 參考 |
|---|---|
| 錯誤處理 | 錯誤處理 |
| 速率限制 | 速率限制 |
| 帳單與定價 | 帳單與定價 |
| 取得 API 金鑰使用量 | 取得 API 金鑰使用量 |
| 取得任務狀態 | 取得任務狀態 |