コアガイド

ログとトラブルシューティング

リクエスト、タスク、課金を追跡するために必要なIDを保持する

TokenLabのリクエストID、タスクID、および課金IDをログに記録してください。これらは、プロンプトやプライベートなメディアを保存することなく、ユーザーのアクションとその結果、および課金を関連付けるために使用されます。

コンソールでは、キャプチャされたリクエストおよびレスポンスの詳細はキャプチャから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キー、管理トークン、署名付き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 でフィルタリングできます。コンソールのページをスクレイピングしたり、レスポンスのトークン数のみから料金を計算したりするのではなく、これらの記録を使用してください。日付のみの 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キーの利用状況を取得
タスクステータスを取得タスクステータスを取得

このページの内容