TokenLab

核心指南

日誌與疑難排解

保留追蹤請求、任務與費用所需的 ID

請在您的日誌中保留 TokenLab 的請求、任務與帳單 ID。它們能將使用者操作與其結果及費用連結起來,且無需儲存提示詞 (prompt) 或私人媒體內容。

在 Console 中,擷取的請求與回應詳細資訊會在擷取後保留 30 天,即使物理清理作業仍在排程中,存取權也會在到期時精確終止。請求識別資訊與帳單/使用量記錄擁有獨立的生命週期。請參閱 資料保留。

從請求到調查與支援

  1. 在擁有該請求的工作區中開啟 Runs。找到其 Request ID 並選取該列。

  2. 選擇 Open full details 以進入專屬頁面。Back to requests 可還原列表篩選器。連結絕不會授予對其他工作區的存取權;請使用該工作區授權的帳號。

  3. 若狀態為擱置中或未知,請先重新整理進度。若回應失敗或中斷,請在可用時選擇 Investigate the issue。這會針對該請求在應用程式內的 Agent 中啟動調查;它不會重新執行原始的模型請求。成功的請求預設不需要調查。

  4. 若您仍需協助,請從請求或調查中選擇人工支援動作。這會在可用時開啟一個包含連結請求與對話的預覽視窗。請檢閱摘要並移除私人內容,然後明確選擇 Submit。單獨的調查或預覽不會發送支援請求。

  5. 提交後,請保留確認資訊並在 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 或 403API 金鑰、管理權杖、組織存取權、金鑰範圍驗證
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 金鑰使用量
取得任務狀態取得任務狀態

本頁內容