# トラブルシューティングとよくある質問

1. デフォルトでは、EVKを外部ディスプレイに接続すると、花の画面が表示されます。

    花の画面が表示されない場合は、新しいSSHシェルで以下のコマンドを実行してください。

export GBM_BACKEND=msm && export XDG_RUNTIME_DIR=/dev/socket/weston && mkdir -p $XDG_RUNTIME_DIR && weston --continue-without-input --idle-time=0
        Copy to clipboard
2. デバッグ・ログを使用してサンプル・アプリケーションをデバッグするにはどうすればよいですか？

    AIサンプル・アプリケーションやgst-launch-1.0を実行した際の実行エラーをトラブルシューティングするには、デバッグ・ログを有効にしてください。

    GStreamerサンプル・アプリケーションのデバッグ・ログを有効化するには、`GST_DEBUG` 環境変数でデバッグ・レベルを設定します。

    `GST_DEBUG` 環境変数でデバッグ出力の詳細度を制御します。以下のような様々なレベルに設定できます。

    - 0：なし（デバッグ情報なし）
    - 1：ERROR（すべての致命的なエラーを記録）
    - 2：WARNING（すべての警告を記録）
    - 3：FIXME（不完全なコード・パスを記録）
    - 4：INFO（情報提供メッセージを記録）
    - 5：DEBUG（一般的なデバッグ・メッセージを記録）
    - 6：LOG（すべてのログ・メッセージを記録）
    - 7：TRACE（トレース・メッセージを記録）
    - 9：MEMDUMP（メモリー・ダンプを記録）

    たとえば、デバッグ・レベルをERRORに設定するには、ターミナルで以下のコマンドを使用してください。

export GST_DEBUG=2
        Copy to clipboard

    特定のカテゴリのデバッグ・ログをフィルターしたい場合は、`GST_DEBUG` 変数で指定できます。たとえば、ML推論プラグインとFPSのデバッグ・ログを有効にするには、以下のコマンドを使用してください。

export GST_DEBUG=qtiml*:fps*:5
        Copy to clipboard
3. AIサンプル・アプリケーションを設定なしですぐに使用できない場合に、よくある問題は何ですか？

    AIサンプル・アプリケーションは、設定なしですぐに使えるように設計されています。ただし、設定なしですぐに使おうとしてつまずく場合に、最もよくある問題は以下のとおりです。

    - モデルのファイルをロードできない

0:00:00.042355885 4275 0x5579b9f760 ERROR ml-tflite-engine ml-tflite-engine-c-api.cc:578:gst_ml_tflite_engine_new: Failed to load model file '/etc/models/googlenet_quantized.tflite'!
            Copy to clipboard

        この問題は、モデルのファイルが見つからないか、または正しい形式でない場合に発生します。

        モデルのファイルパスを確認し、モデルの変換/量子化を行ったSDKとターゲット・デバイスのSDKバージョンが同じであるかを確認してください。
    - ラベルをデシリアライズできない

0:00:00.543394063 4676 0x55aca865e0 ERROR mlmodule gstmlmodule.c:301:gst_ml_parse_labels: Failed to deserialize labels!
            Copy to clipboard

        この問題は、パスに指定されたラベル・ファイルが存在しない場合に発生します。ラベル・ファイルがデバイスにコピーされており、指定したパスが正しいことを確認してください。
    - モジュール・オプションを設定できない

0:00:00.55129740 4958 0x5561019180 WARN  qtimlvclassification mlvclassification.c:986:gst_ml_video_classification_set_caps:<mlvideoclassification0> error: Failed to set module options!
            Copy to clipboard

        この問題は、LiteRT/Qualcomm AI Engine Directのユース・ケースで定数を設定する場合に発生します。モデルの定数を正しく読み込んで設定する手順については、[AI Hubモデルをアプリケーションに統合](https://docs.qualcomm.com/doc/80-70018-15BJ/topic/integrate-ai-hub-models.html) を参照してください。
4. AIサンプル・アプリのプロファイリングを測定するにはどうすればよいですか？

    - プリプロセス時間

        AI推論プラグインに入力を投入する前に、入力を前処理（正規化、再スケール、色の置き換えなど）する必要があります。このタスクは、`qtimlvconverter` プリプロセス・プラグインによって管理されます。以下のコマンドを実行することで、プリプロセスの時間を計測できます。

export GST_DEBUG=qtimlvconverter:6
            Copy to clipboard

        プリプロセスの時間がログに表示されます。

LOG   qtimlvconverter mlconverter.c:1830:gst\_ml\_video\_converter\_transform:&lt;qtimlvconverter&gt; Conversion took 2.743 ms
    - モデルの推論時間

        Qualcomm Intelligent Multimedia SDKがサポートする3つのAI推論プラグインは、それぞれQualcomm Neural Processing SDK、LiteRT、Qualcomm AI Engine Directフレームワークを利用しています。

        - qtimlsnpe
        - qtimltflite
        - qtimlqnn

        これらのプラグインは、CPU、GPU、HTPなどの様々なハードウェア上で推論を実行できます。ハードウェア上でのAI推論時間を算出するには、以下のコマンドを使用します。

export GST_DEBUG=qtiml*:6
            Copy to clipboard

LOG qtimlvtflite mltflite.c:561:gst\_ml\_tflite\_transform:&lt;qtimltflite&gt; Execute took 3.445 ms
LOG qtimlvtflite mltflite.c:561:gst\_ml\_tflite\_transform:&lt;qtimltflite&gt; Execute took 3.555 ms
    - ポストプロセス時間

        AI推論プラグインからの出力は、ポストプロセス・プラグインによって処理されます。これらのプラグインは、AIモデルの結果を受け取り、入力ストリームにオーバーレイしたり、その他の計算に使用できるエレメントを生成します。たとえば、`qtimlvclassification` のテキスト・ボックスや `qtimlvsegmentation` のセグメンテーション・マスクなどです。

        これらのプラグインの処理時間を測定するには、以下のコマンドを使用します。 .. code-block:

export GST_DEBUG=qtimlv*:6
            Copy to clipboard

        ポストプロセス時間はログに表示されます。以下では例として、`qtimlvclassification` プラグインを使用します。

LOG    qtimlvclassification mlvclassification.c:1068:gst\_ml\_video\_classification\_transform:&lt;qtimlvclassification&gt; Categorization tookExecute took 1.962 ms
5. ユース・ケースのエンドツーエンドのFPSを測定するにはどうすればよいですか？

    GStreamerパイプラインのフレームレート（FPS）を測定するには、`fpsdisplaysink` エレメントを使用します。このエレメントは、ビデオ上のオーバーレイとして、またはコンソールに出力することによって、現在および平均のフレームレートを表示できます。

    サンプル・アプリは、`fpsdisplaysink` プラグインを使用して、HDMIモニターにパイプラインのFPSを直接表示します。
6. リファレンス・アプリケーションで、既存のモデルをカスタム・モデルに置き換える最も簡単な方法は何ですか？

    サンプル・アプリケーションに正しいモデル・ファイルとラベル・ファイルを使用していることを確認してください。

    `--model_path` オプションと `--label_path` オプションにそれぞれのファイル・パスを指定します。

    サンプル・アプリは、指定された場所のモデル・ファイルとラベル・ファイルを使用します。

    詳細は、[AI Hubモデルをアプリケーションに統合](https://docs.qualcomm.com/doc/80-70018-15BJ/topic/integrate-ai-hub-models.html) を参照してください。
7. リファレンス・アプリケーションで、別のサポート対象モデル（サポート対象のIMSDK）に置き換えました。パフォーマンスと精度の問題をデバッグするにはどうすればよいですか？

    モデルのパフォーマンスと精度の問題を分析するには、AI SDKツールを使用し、以下の手順に従ってください。

    - パフォーマンス測定：

        SDKベンチマーク・ツールを使用します。たとえば、Qualcomm Neural Processing Engine SDKをご使用の場合は、[https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-bench-py](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-bench-py) を使用します。
    - Accuracy debugger：

        - AI Hubモデル：

            1. AI Hubの最新モデルを使用していることを確認してください。
            2. 選択したモデルの定数を正しく入力します。詳細は、[AI Hubモデルをアプリケーションに統合](https://docs.qualcomm.com/doc/80-70018-15BJ/topic/integrate-ai-hub-models.html) を参照してください。
            3. AI Hubモデルの精度問題に関して、さらにサポートが必要な場合は、[Qualcomm AI Hub slack](https://qualcomm-ai-hub.slack.com/join/shared_invite/zt-2ur7psfuu-CygEMlDFjoHTbPKIRCVYuQ%23/shared-invite/email) で問題を報告してください。
        - カスタム・モデル

            1. モデルの量子化は精度低下のよくある原因です。モデルの量子化に適正なデータセットを使用するようにしてください。トレーニング後の量子化（Post Training Quantization、PTQ）では、実際のデプロイ環境に近似したデータセットの一部を使用することが想定されています。PTQで良い結果を得るためには、モデルを量子化するために適切な量のデータ（たとえば、約25～30枚のRAW画像）を入力する必要があります。
            2. W8A16やW16A16など、モデルの精度を変えて実験し、モデルの精度が向上するかどうかを確認します。
            3. 高度な量子化のためのPTQ技術や量子化認識トレーニング（Quantization-Aware Training、QAT）技術にはAIMETを使用します。詳細は、[AIMETドキュメント](https://quic.github.io/aimet-pages/releases/latest/user_guide/index.html) を参照してください。
8. AI SDKを使用したモデル量子化のベスト・プラクティス

    - キャリブレーション・データの準備

        モデルが本番で使用するデータに近い代表的なキャリブレーション・データを使用します。これにより、量子化のスケーリング係数とゼロ点を正確に決定できます。
    - 正しい量子化手法の選択

        - PTQ：この手法はよりシンプルかつ高速です。わずかな精度低下しか許されないモデルに適しています。再トレーニングを行うことなく、事前学習済みの浮動小数点モデルを量子化されたモデルに変換します。
        - 量子化認識トレーニング（Quantization-Aware Training、QAT）：この手法では、量子化を考慮してモデルをトレーニングするため、より高い精度を維持できます。複雑度は増しますが、精度が非常に重要なモデルには有効です。

        詳細な手順は、[AIMETドキュメント](https://quic.github.io/aimet-pages/releases/latest/user_guide/index.html) を参照してください。
9. AI SDKには、LiteRTをDLCに変換するツールが用意されています。LiteRTモデルはDLCに変換する必要がありますか、それともLiteRTモデルをNPU上で直接高速化できますか？

    LiteRTモデルをNPUで高速化するために、必ずしもDLCに変換する必要はありません。クアルコムのAI SDKは、NPU上でのLiteRTデリゲートを使用したLiteRTモデルの直接実行をサポートしています。つまり、LiteRTモデルをDLCフォーマットに変換することなく、NPUの機能を利用できます。
10. AI SDKには、PyTorch、Onnx、Tensorflowの各モデルをDLCに変換するツールが用意されていますが、最もすばやくデプロイできるのはどの方法ですか？

    モデルをまずONNXに変換した後、DLCに変換することが、デプロイのための最も迅速で柔軟な手法である場合が多いです。
11. モデルがNPU上で実行されているかどうかを確認するにはどうすればよいですか？

    クアルコムの以下のツールをご使用ください。

    1. [Qualcomm profiler](https://docs.qualcomm.com/bundle/publicresource/topics/80-54323-2/command-line-interface.html)
    2. Sysmon（リンク未定）
12. Snapdragonプラットフォームの多種多様なAIエンジンのメリットを活かすにはどうすればよいですか？ハードウェア・コアごと（GPU、NPUなど）で異なるAIモデルを実行するにはどうすればよいですか？

    AI SDKツールとAPIには、ランタイム（CPU、GPU、DSP）を選択するオプションが用意されています。コマンド・ライン・パラメーターとして適切なランタイムを選択するか、または特定のC/C++ APIを使用することができます。詳細は、[https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-net-run](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-net-run) をご覧ください。

    AIサンプル・アプリケーションは、デフォルトでDSPランタイムを使用します。ランタイムは、サンプル・アプリケーションの設定で変更できます。

    たとえば、`gst-ai-object-detection` サンプル・アプリでは、`config_detection.json` ファイル内の `runtime` パラメーターを変更します。

    ランタイム：

    - `"cpu"`
    - `"gpu"`
    - `"dsp"`
13. AI SDKでモデル変換に失敗した場合は、どうすればよいですか？

    [クアルコムのサポート・フォーラム](https://mysupport.qualcomm.com/supportforums/s/) にお問い合わせください。
14. カスタムの浮動小数点モデルはCPU上では精度が良いのですが、量子化後のモデルの精度はCPU上でもNPU上でも悪いです。デバッグするにはどのようにすればよいですか？

    モデルの量子化に関連する問題が発生している可能性があります。モデルの量子化に関するガイダンスについては、[ユーザーによるモデルの置換](https://docs.qualcomm.com/doc/80-70018-15BJ/topic/troubleshooting.html#user-replaced-model) FAQを参照してください。
15. 量子化したカスタム・モデルはCPU上では想定どおりに動作するのですが、NPU上では同じモデルが正確に動作しません。デバッグするにはどのようにすればよいですか？

    TBD
16. サンプル・アプリを実行しても、HDMI画面に出力が表示されません。デバッグするにはどのようにすればよいですか？

    HDMIディスプレイの問題をデバッグするには、[ディスプレイのデバッグ](https://docs.qualcomm.com/bundle/publicresource/topics/80-70014-18/debug.html) に従ってください。
17. サンプル・アプリケーションを実行するのに、HDMIモニターの代わりにHDMIテレビを使用することは可能ですか？

    たいていは使用できますが、動作しない場合はHDMIモニターをご使用ください。
18. AIサンプル・アプリのハードウェア・ランタイムを調べるにはどうすればよいですか？

    多くのGStreamerサンプル・アプリケーションは、様々なランタイム（CPU、GPU、DSP）での推論をサポートしています。アプリが推論に使用するランタイムを調べるには、ログを確認してください。

    - CPU

Running app with model: /usr/models/inception\_v3\_quantized.tflite and labels: /usr/labels/classification.labels
Using CPU Delegate
Adding all elements to the pipeline...
    - GPU

Running app with model: /usr/models/inception\_v3\_quantized.tflite and labels: /usr/labels/classification.labels
Using GPU Delegate
Adding all elements to the pipeline...
    - DSP

Running app with model: /usr/models/inception\_v3\_quantized.tflite and labels: /usr/labels/classification.labels
Using DSP Delegate
Adding all elements to the pipeline...
19. devtoolのサニティー・チェック・エラーとは何ですか？デバッグするにはどのようにすればよいですか？

    時折、devtoolがサニティー・チェック・エラーを表示することがあります。

    ホスト・コンピューターのsudoアクセス権を持っていることを確認してください。エラーが消えない場合は、以下の回避策を実行してください。

    1. 権限を更新します。

umask a+rx
            Copy to clipboard
    2. `$ESDK_ROOT/layers/poky/meta/conf/sanity.conf` ファイルのBitBakeサニティー・チェックを無効化します。

BB_MIN_VERSION = "1.53.1"
            SANITY_ABIFILE = "${TMPDIR}/abi_version"
            SANITY_VERSION ?= "1"
            LOCALCONF_VERSION ?= "2"
            LAYER_CONF_VERSION ?= "7"
            SITE_CONF_VERSION ?= "1"
            
            #INHERIT += "sanity"
            Copy to clipboard

## さらにサポートが必要な場合

[クアルコムのサポート・フォーラム](https://mysupport.qualcomm.com/supportforums/s/) でご質問ください。

Last Published: Oct 15, 2025

[Previous Topic
超解像度で画像をアップスケールする](https://docs.qualcomm.com/bundle/publicresource/80-70018-15BJ/topics/super-resolution.md) [Next Topic
モデル移植におけるベスト・プラクティス](https://docs.qualcomm.com/bundle/publicresource/80-70018-15BJ/topics/appx-export-yolov8.md)