mcpField
M
model-debugging

model-debugging

github.com/pollinationsクラウド・DevOps5.3k69 回インストール今日更新
リポジトリ

model-debugging について

Pollinations のサービスで発生したモデルの障害を診断するリポジトリスキルです。エンジニア向けに、リクエストの追跡、可観測性データの確認、機密情報に配慮した証拠の報告を案内します。

主な機能

  1. 01Worker とプロバイダー間のリクエスト追跡
  2. 02稼働状況とエラーの可観測性データ確認
  3. 03範囲を限定した本番 SQL クエリ
  4. 04ユーザーとリクエスト形式別の障害比較
  5. 05目的別エラー報告スクリプト

活用シーン

  1. 01モデルエラーや停止の調査
  2. 02フォールバックによる主系障害の隠蔽確認
  3. 03タイムアウトやストリーミング問題の分析

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/pollinations/pollinations --skill model-debugging

インストール後、Claude Code で/model-debuggingを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

scripts/
check-user-errors.sh
find-402-users.sh
find-403-users.sh
find-500-errors.sh
tinybird-query.sh

詳細

モデルのデバッグ

ライブの問題を診断する前に、リポジトリの AGENTS.md を読み、現在のルートを確認します。報告された原因は仮説として扱います。まず、影響を受けているモデル、リクエストの形式、環境、時間帯、ユーザーに見えている症状を特定します。

障害を追跡する

  1. Model Monitor と、enter.pollinations.ai/observability/endpoints/model_health.pipe および recent_server_errors.pipe の現在の定義を確認します。モニターには集計された稼働状況が表示され、エラーパイプには直近の対応が必要なサーバー側の障害が含まれます。
  2. enter および gen Workers を通じてリクエスト ID を追跡し、続いてプロバイダーまで追跡します。ライブイベントには、該当する Worker のログまたは wrangler tail を使用します。クエリを実行する前に、対象の環境を確認してください。
  3. 本番 SQL には enter.pollinations.ai/observability/scripts/tb-prod.sh を使用します。このスクリプトは既存の読み取りトークンを読み込みますが、表示はしません。アクセス権と最新のイベントを確認するには --check を使用します。クエリの時間範囲と行数は制限してください。
  4. 影響を受けたユーザーのリクエストを、同じモデルとルートを使用する他のユーザーのリクエストと比較します。ステータス、上流のステータス、プロバイダー、リクエスト形式、時間帯でグループ化します。必要に応じて、既存の認証済みテスト用認証情報で正確なリクエストを再現します。キャッシュされた応答を上流の正常性と取り違えないよう、一意のプロンプトを使用してください。
  5. 根拠、影響、残る不確実性、最小限の修正を報告します。コード修正が求められた場合は、該当するリポジトリのスキルとテスト手順に従ってください。

データの解釈

  • generation_event_v2 には、認証済みでキャッシュされていないリクエストが含まれます。SQL を記述する前に、現在のデータソース定義を確認してください。1 つのリクエストにつき、複数の上流試行の行が含まれる場合があります。is_final はユーザーに見える結果を示します。最終応答だけを数えると、フォールバックの成功によって壊れたプライマリが隠れてしまう可能性があります。
  • model_health の total_requests とステータス件数は最終結果に基づきます。own_calls、primary_5xx、primary_retried_503s、fallback_rescues は上流の稼働状況と復旧状況を示します。両方のビューを確認してください。
  • 401、402、403、400、429 は異なるレイヤーで発生する可能性があります。generation_event_v2 の error_source と error_response_code を確認してください。また、呼び出し側の問題やモデル障害と判断する前に、recent_server_errors.pipe（24 時間保持）を通じて error_event の upstream_status、upstream_body、upstream_host を確認してください。
  • サーバー側で 200 が返っていても、クライアントのタイムアウト後に届く場合があります。ステータス率や p95 だけではなく、ユーザー別およびリクエスト形式別のレイテンシの裾を調べてください。
  • ストリーミングの障害や使用量データの欠落については、プロバイダー、アダプター、バリデーターを通じて、最終 SSE チャンクと元のトランスポートエラーを調べてから、プロバイダーの問題と判断してください。
  • プロバイダーの 500 は、符号付き INT32 の範囲を超える seed など、無効な呼び出し側の入力によって発生する場合があります。上流の障害と断定する前に、リクエスト形式別に障害を比較してください。
  • Azure Content Safety は、設定が欠落している場合やリクエストが失敗した場合に、安全という結果を返します。画像モデレーションが機能していないように見える場合は、現在の設定と gen のログを確認してください。画像応答が成功していても、安全性チェックが実行された証明にはなりません。
  • キュー満杯またはレート制限のエラーがすぐに発生する場合、リミッターの状態、またはバックエンドがアイドル状態のまま、多数のクライアントが 1 つのプロキシ IP を共有していることが原因の可能性があります。Worker を再起動する前に、リミッターとバックエンドのカウンターを比較してください。
  • デプロイまたはプロキシがタイムアウトの原因と疑われる場合は、変更の前後で症状を比較し、最外部のホップを調べてください。該当するリージョンから、直接接続とプロキシ経由のプローブを順次実行します。並列の集中実行は、クライアント側で誤解を招く障害を発生させる場合があります。

対象を絞ったヘルパー

scripts/ 内のスクリプトは、リポジトリの読み取り専用ヘルパーを通じて本番環境の Tinybird にクエリを実行します。上限のある数値ウィンドウを受け付け、リポジトリのルートから実行してください。

.claude/skills/model-debugging/scripts/find-402-users.sh 24 10
.claude/skills/model-debugging/scripts/find-403-users.sh 24 10
.claude/skills/model-debugging/scripts/find-500-errors.sh 24
.claude/skills/model-debugging/scripts/check-user-errors.sh USER_ID 24

これらのレポートには、ユーザー識別子やエラーの詳細が含まれています。タスクに必要な行だけを確認し、機密情報を共有する出力に含めないでください。

シークレットの変更と本番環境へのデプロイには、AGENTS.md に定められた承認および CI のルールが適用されます。インシデントの診断は、いずれの操作も許可するものではありません。

コメント

Markdown 対応