luxonis-troubleshoot

Luxonis トラブルシューティング

既存の OAK パスを復旧します。原因を1つ変更し、同じ観測を再実行して、最初に失敗したレイヤーで止めます。

完了条件

元の失敗した観測が成功し、次の依存チェックも引き続き動作するか、次のアクションを明示してブロック中となっていること。ハードウェア障害（オレンジ色のLED、起動失敗、キャリブレーションの疑い）は [email protected] に連絡してください。

DepthAI の API を記憶から作り出してはいけません。DepthAI v3 のみを使用し、v2 API と混在させないでください。

まず、最も信頼できる情報源として Luxonis MCP ツールを確認します（表示される名前はホストによって異なります）。次に、ツールが返す該当するサンプルまたはドキュメントのソース、続いて https://docs.luxonis.com/llms.txt、最後に観測された動作を確認します。記憶は一般的な推論にのみ使用してください。oakctl のコマンドとフラグについては、インストール済みの oakctl --help をドキュメントや MCP より優先します。ローカルのバージョン（古い場合やベータ版の場合があります）が、ここで可能なことを定義するため、ローカル版を基準に作業し、最新のドキュメントに記載された機能が不足している場合は oakctl の更新を提案してください。観測されたホストまたはデバイスの動作がドキュメントや MCP と矛盾する場合は、観測結果を信頼して、その相違を記録してください。オフラインの場合は、oakctl --help とローカルのサンプルを使って作業し、どの情報が未検証かを明記してください。

AGENTS.md が見つからない場合、またはこの作業でホストのツールチェーンが必要なのに oakctl がない場合は、luxonis-workspace を明示してその手順に従い、その後作業を続けてください。手順をコピーしてはいけません。

存在する場合は、docs/brief.md、docs/device.md、ソース、ログ、証拠を確認してください。レガシーなルートの PROJECT_BRIEF.md と DEVICE.md も存在する場合は確認してください。いずれも必須ではありません。docs/device.md はセットアップメモとして扱い、ライブ状態を信頼してください。最初から新規開発のヒアリングを始めないでください。製品が間違っている場合は、luxonis-app に言及してください。

1. 1つの失敗を固定する

期待される観測を1つ示し、それに矛盾する最小限の実際の結果を示してください。可能な場合は、正確な実行コマンドと観測コマンド、この再現で使用したデバイス、トポロジー、代表的な入力、関連するバージョン、完全な stderr、フレーム、またはコンシューマーの出力を保持してください。

安全で、実行範囲が限定されている場合は、編集前に1回再現してください。断続的な失敗の場合は、範囲を限定した複数の観測を収集し、発生頻度を記録してください。

2. 最初に失敗したレイヤーを特定する

次の順に確認し、最初に失敗した時点で止めます。

1. ホストのツールチェーンとインポート。
2. デバイスの検出、トランスポート、電源、排他的アクセス。
3. ホストプロセスまたは OAK App のライフサイクル。
4. パイプラインの構築、リンク、登録、トピック。
5. センサーまたはリプレイ入力。
6. モデル／アーカイブ入力、前処理、パーサー、推論。
7. 同期、クロップ、トラッキング、ジオメトリ、アプリケーション状態。
8. 要求されたファイル、MQTT、API、UI、ターミナル、その他の最終出力。

デバイスパスが未検証の場合は、luxonis-device-setup を使用してください。ホリスティック録画のキャプチャまたはリプレイには、luxonis-record を使用してください。ライブフレーム、検出結果、深度、クロップ、トラック、または構造化されたパイプラインメッセージに関する確認には、luxonis-inspect を使用してください。外部出力は、パイプラインの証拠とは別に検証してください。

手軽な切り分け方法として、最小限の既知正常な DepthAI スニペットでデバイスを開き、1フレームをストリーミングできるか確認します。失敗する場合、レイヤーはデバイス／接続です。成功する場合は、アプリを最も近い現行サンプルと比較して二分探索してください。

クラッシュ／エラーの場合は、DEPTHAI_LEVEL=debug を設定して再実行してください。深度または出力に問題がある場合は、フレームをキャプチャしてください。FPS が低い場合は、数値を測定してください。

3. 仮説を1つ検証する

現在の証拠がなぜ1つの原因を示しているのか、また、どの結果がその仮説を否定するのかを説明してください。原因を1つ変更してください。再現と観測のコマンドは変えないでください。変更のない操作の再試行は2回までとし、3回目の試行には新たな仮説または人間による判断が必要です。

範囲を限定した修正を優先してください。選択したサンプルに環境を合わせる、アドレス、エンドポイント、キュー、トピック、リンク、ブロッキング読み取りのいずれか1つを修正する、アーカイブ入力、パーサー、ラベル順を復元する、依存するトラッキングパスとクロップパスで同じフィルタリング済み検出結果を使用する、といった対応です。

大規模な書き換え、モデルの置き換え、デバイスの更新、トポロジーの変更から始めないでください。

4. 修復を検証する

最初に失敗した観測を再実行します。成功した場合は、ローカルの修正によって下流のリグレッションが隠れないよう、次に依存するチェックも再実行します。根本原因、証拠、変更したファイル、変更前後のコマンド、成功したチェック、未検証の主張を報告します。

ガードレール

• sudo／管理者権限の操作、ファームウェア／OS の更新、書き込み、工場出荷時設定へのリセット、Hub の採用、永続的なネットワーク設定、グローバルな pip の使用、顧客の成果物の置き換えを行う前に、許可を求めます。
• DepthAI をソースからコンパイルしてはいけません。
• WSL で USB が使えるふりをしてはいけません。
• 1 台のデバイスに対して、競合するプロセスを同時に実行してはいけません。
• 学習、プロプライエタリな SLAM、完全な ROS システムが必要な場合は、その旨を伝えて作業を止めます。OAK のユースケースが不可能だとは言わないでください。人間が引き続き担当する作業と、次のステップを 1 つ提示します。