debug-inference について
debug-inferenceは、OpenShellサンドボックスからモデルプロバイダーへの推論リクエストを調査するスキルです。ゲートウェイ、プロバイダープロファイルと接続、クライアントのネイティブ設定、一般的なネットワークや認証の問題を確認します。
主な機能
- 01ゲートウェイとサンドボックスの状況確認
- 02プロバイダープロファイルと接続状態の確認
- 03ネイティブエンドポイントとクライアント設定の検証
- 04一般的なネットワーク・認証エラーの診断
- 05ホスト上のローカル推論の確認手順
活用シーン
- 01プロバイダーリクエストが拒否される原因の調査
- 02サンドボックスからローカルモデルサーバーへの接続診断
- 03ルーティング変更後の古いエンドポイントや設定の特定
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/debug-inferenceを入力して読み込まれたか確認します。
詳細
推論のデバッグ
推論は、プロバイダーが許可した通常のネットワークトラフィックとして診断します。OpenShell は、管理対象の推論ルートを提供したり、リクエスト形式を書き換えたり、モデルを選択したりしなくなりました。アプリケーションはプロバイダーのネイティブエンドポイントを呼び出し、ベース URL、モデル、リクエスト形式、タイムアウトを管理します。
コマンド構文は、インストール済みの openshell --help の出力を正としてください。現在の動作については、公開されているプロバイダー管理ガイドとプロバイダープロファイルガイドを参照してください。
診断ワークフロー
1. ゲートウェイとサンドボックスのコンテキストを確認する
openshell status
openshell gateway info
openshell sandbox get <sandbox>
ホスト上のローカルモデルサーバーの場合、host.openshell.internal が示すのはゲートウェイを実行しているマシンです。ゲートウェイがリモートにある場合、オペレーターのノート PC を示すものではありません。また、127.0.0.1 のみでリッスンしているサーバーはコンテナから到達できないことがあります。ゲートウェイのランタイムから到達可能なアドレスにバインドしてください。
2. プロバイダーとそのプロファイルを確認する
openshell provider get <provider>
openshell profile export <profile-id> -o yaml
プロファイルについて、以下を確認してください。
- クライアントが呼び出すエンドポイントのホスト、ポート、プロトコルが正確に指定されていること。
- クライアントのバイナリが許可されていること。
- 認証情報のキーと、意図する認証方式が宣言されていること。
- プロバイダーが API の一部のみを公開する場合、HTTP ルールが狭く設定されていること。
カスタムまたはセルフホストの OpenAI 互換エンドポイントの場合は、エンドポイントを含むプロファイルをインポートしてください。プロバイダー設定のみに保存されたベース URLでは、新しいエンドポイントは許可されません。
openshell profile lint -f ./provider-profile.yaml
openshell profile import -f ./provider-profile.yaml
openshell provider create --name <provider> --type <profile-id>
プロファイルに示されている必須の --credential KEY または --credential KEY=VALUE 引数を追加してください。認証情報のバインドエラーを解消するためだけに、エンドポイントポリシーを広げないでください。
3. アタッチを確認する
openshell sandbox provider list <sandbox>
openshell sandbox provider attach <sandbox> <provider> --wait --timeout 30
変更の receipt_id を保存し、openshell sandbox provider status <sandbox> <provider> --receipt <receipt-id> --wait --timeout 30 を使って、いつ反映されるかを確認します。成功すると、サンドボックスで新しいプロセス向けの認証情報、ポリシー、環境変数が適用されたことを確認できます。結果が pending、failed、withheld、または superseded の場合は、クライアントを起動する前に理由を調べてください。
アタッチ完了までの待機が成功した後にクライアントを起動し、更新された環境変数を受け取れるようにします。
openshell sandbox exec <sandbox> -- <client-command>
通常の静的プロバイダーを更新した後は、その変更が反映されるまで待ってから新しいクライアントを起動してください。既存のプロセスはリビジョンにひも付いた参照を保持するため、準備が完了しても古い参照から置き換え後の値を取得することはできません。管理対象の更新認証情報については、それぞれのライフサイクルに従って診断してください。
認証情報や発行された参照を診断出力に含めないでください。確認済みのデタッチによって、今後の認証情報解決が無効になり、以後のプロセス環境から参照が削除されます。すでに転送されたリクエストは完了することがあります。
openshell sandbox provider detach <sandbox> <provider> --wait --timeout 30
4. ネイティブクライアント設定を確認する
アプリケーションでは、実際の上流契約を使用する必要があります。
- 廃止された管理対象の仮想エンドポイントではなく、プロバイダーのネイティブなベース URL。
- OpenShell が書き換えていたプレースホルダーではなく、実際のモデル ID。
- ネイティブの OpenAI、Anthropic、Vertex、またはその他のプロバイダーのリクエスト形式。
- アプリケーションが管理するタイムアウトと再試行の設定。
- アタッチされたプロファイルで宣言された認証情報の環境変数。
新しく起動したサンドボックスプロセスから、正確なエンドポイントに接続して確認してください。プロバイダーが提供している場合は、まず秘密情報を必要としない探索用エンドポイントを使い、その後、プロバイダーがドキュメントで定める API 形式に従って最小限の推論リクエストを送信します。
5. よくある失敗の解釈
| 症状 | 考えられる原因 | 対処方法 |
|---|---|---|
credential_placeholder_in_request_body | 本文の参照が無効または取り消されているか、分類メタデータを利用できません | 制御された拒否理由を確認してください。会話履歴から参照を削除するか、プロバイダーへのアクセスを復元してください。ツールの出力を送信するために、本文の認証情報書き換えやバイパスフラグを有効にしないでください。不明なリテラルと有効な発行済みプレースホルダーは、モデルプロバイダー独自のプレースホルダーも含め、そのまま渡されます。ヘッダーの解決によって本文の書き換えが有効になることはありません。 |
| 廃止されたマネージドエンドポイントの DNS 解決に失敗する | クライアントが削除されたマネージドエンドポイントを引き続き使用しています | プロバイダー本来のベース URL を設定し、エンドポイントを指定したプロバイダープロファイルを適用してください |
| 直接リクエストが拒否される | 添付、エンドポイントポリシー、HTTP ルール、またはバイナリ認可が不足しています | 添付されたプロバイダープロファイルとサンドボックスの実効ポリシーを確認してください |
credential_endpoint_mismatch | 認証情報プロファイルがリクエスト先を許可していません | ホスト／ポート／パスを修正するか、目的のエンドポイントに限定したプロファイルをインポートしてください |
request_authority_mismatch | HTTP authority が CONNECT の接続先と異なります | 両方の authority で同じホストと実効ポートを使用してください |
| 認証情報の変数が見つからない | このプロセスの起動時にプロバイダーが適用されていなかったか、複数のプロファイルでキーが重複しています | プロバイダーを適用して新しいプロセスを起動してください。重複したキーは明示的に解決してください |
| アップストリームがモデルまたは本文を拒否する | クライアントが削除されたモデル／リクエストの書き換えに依存しています | アプリケーションで実際のモデルとプロバイダー本来のリクエスト形式を設定してください |
ホストでは 127.0.0.1 が機能するが、サンドボックスでは機能しない | ループバックが異なる実行環境を指しています | host.openshell.internal またはゲートウェイから到達可能な別のエンドポイントとプロファイルを使用してください |
| ホストローカルのリクエストがタイムアウトする | サーバーのバインドアドレス、ゲートウェイトポロジー、またはホストのファイアウォールが、コンテナーからホストへの通信を遮断しています | リスナーを確認し、必要なゲートウェイネットワーク経路とポートのみを許可してください |
ホストローカル推論のチェックリスト
Ollama、LM Studio、vLLM、SGLang、TRT-LLM、およびローカルの NIM デプロイの場合：
- ゲートウェイホストからエンジンへの接続を確認します。
- ゲートウェイの実行環境から到達可能なアドレスでリッスンしていることを確認します。
host.openshell.internalと実際のポートを指定したカスタムプロファイルをインポートします。- プロファイルを対象のバイナリと API パスのみに制限します。
- プロバイダーを作成して適用します。
- アプリケーションのベース URL、モデル、タイムアウトを設定します。
- 新たに起動したサンドボックスプロセスから、本来のエンドポイントをプローブします。
報告
次の内容を報告してください。
- 使用中のゲートウェイと、トポロジーが失敗の一因かどうか。
- 関係するプロバイダー、プロファイル、適用状況、エンドポイント、クライアントバイナリ。
- 失敗したホスト、ポート、パス、リクエスト authority の正確な値（シークレットを除く）。
- クライアントが削除されたマネージドルーティングの動作に依存し続けているかどうか。
- 問題を解決するために必要な、最小限のプロファイル、適用、またはアプリケーション設定の変更。