# 故障排除和常見問題解答 1. 如何使用調試日誌來調試範例應用程序？ 要排除執行 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 2. 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: error: Failed to set module options! Copy to clipboard 為 LiteRT/Qualcomm AI 引擎 Direct 使用案例設定常數時，會發生此情況。請參閱 [將 AI Hub 模型整合至應用程式](https://docs.qualcomm.com/doc/80-70020-15BT/topic/integrate-ai-hub-models.html) 以瞭解正確讀取和設定模型常數的步驟。 3. 如何測量 AI 範例應用程式的分析？ - 預處理時間 將輸入提供給 AI 推論外掛程式之前，必須對輸入進行預處理 (包括正規化、重新縮放和色彩反轉)。此任務由預處理外掛程式 `qtimlvconverter` 管理。您可以執行以下命令以測量預處理時間： export GST_DEBUG=qtimlvconverter:6 Copy to clipboard 預處理時間顯示在日誌中。 LOG qtimlvconverter mlconverter.c:1830:gst\_ml\_video\_converter\_transform:<qtimlvconverter> Conversion took 2.743 ms - 模型推論時間 Qualcomm 智慧多媒體 SDK 支援三個 AI 推理外掛程式，分別使用 Qualcomm 神經處理 SDK、LiteRT 及 Qualcomm AI 引擎 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:<qtimltflite> Execute took 3.445 ms LOG qtimlvtflite mltflite.c:561:gst\_ml\_tflite\_transform:<qtimltflite> 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:<qtimlvclassification> Categorization tookExecute took 1.962 ms 4. 如何測量用例的端到端每秒幀數 (FPS) ？ 若要測量 GStreamer 管道中的每秒畫格數 (FPS)，請使用 `fpsdisplaysink` 元件。此元件可將目前和平均畫格率顯示為影片上的覆疊或列印至主控台。 範例程式使用 `fpsdisplaysink` 外掛程式，直接在 HDMI 監視器上顯示管線的 FPS。 5. 在參考應用程式中，用您的自訂模型取代現有模型的最簡單方法是什麼？ 確保您為範例應用程式使用正確的模型和標籤檔案。 在對應的範例應用程式組態檔中提供模型和標籤檔案路徑。 範例應用程式將使用來自指定位置的模型和標籤檔案。 更多資訊請參閱 [將 AI Hub 模型整合至應用程式](https://docs.qualcomm.com/doc/80-70020-15BT/topic/integrate-ai-hub-models.html) 。 6. 使用者在參考應用程式中替換另一個支援的模型 (支援 IMSDK)。如何對效能和準確性問題進行除錯？ 若要測量模型的效能與精確度問題，請使用 AI SDK 工具，您可以依照下列步驟進行： - 效能測量： 使用 SDK 基準測試工具。例如，如果使用 Qualcomm 神經處理引擎 SDK，請使用 [snpe-bench-py](https://docs.qualcomm.com/bundle/publicresource/topics/80-63442-2/tools.html#snpe-bench-py) - 精確度調試器： - AI Hub 模型： 1. 確保您使用的是 AI Hub 的最新模型。 2. 正確填入所選模型的常數。更多資訊請參閱 [將 AI Hub 模型整合至應用程式](https://docs.qualcomm.com/doc/80-70020-15BT/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. 模型量化是準確性下降的常見原因。請務必使用正確的資料集進行模型量化。使用者應使用與實際部署環境近似的部分資料集來進行訓練後量化 (PTQ)。為了讓 PTQ 提供良好的結果，使用者必須提供適量的資料來量化模型，例如約 25-30 張 RAW 影像。 2. 試驗不同的模型精確度，例如 W8A16 和 W16A16，看看模型精確度是否有改善。 3. 使用 AIMET 進行訓練後量化 (PTQ) 和量化感知訓練 (QAT) 技術進行進階量化。如需詳細資訊，請參閱 [AIMET 文件](https://quic.github.io/aimet-pages/releases/latest/user_guide/index.html)。 7. 使用 AI SDK 進行模型量化的最佳實踐有哪些？ - 準備校準數據 使用與模型在生產中將遇到的資料密切相符的代表性校正資料。這有助於準確確定量化的比例因數和零點 - 選擇正確的量化方法 - 訓練後量化 (PTQ)：此方法較簡單也較快速。適合可接受輕微準確度損失的模型。可將經過預先訓練的浮點模型轉換成量化模型，不需要重新訓練。 - 量化感知訓練 (QAT)：這種方法是在考慮量化的情況下訓練模型，有助於保持較高的精準度。此訓練更複雜，但對於精度要求較高的模型來說更有益。 詳細步驟請參閱 [AIMET 文件](https://quic.github.io/aimet-pages/releases/latest/user_guide/index.html)。 8. AI SDK 提供轉換 LiteRT 為 DLC 的工具。使用者必須將 LiteRT 模型轉換為 DLC，還是 LiteRT 模型可直接在 NPU 上加速？ 您不必將 LiteRT 模型轉換為 DLC，即可在 NPU 上加速這些模型。Qualcomm 的 AI SDK 支援透過 LiteRT 委派直接在 NPU 上執行 LiteRT 模型。這代表您無須將 LiteRT 模型轉換為 DLC 格式，即可利用 NPU 的功能。 9. AI SDK 提供工具以將 PyTorch、Onnx 和 Tensorflow 模型轉換成 DLC。其中何者是最快速的部署路徑？ 先將您的模型轉換為 ONNX，然後再轉換為 DLC，通常是最快速、最靈活的部署方法。 10. 使用者如何知道模型是否在 NPU 上運行？ 使用以下來自 Qualcomm 的工具： 1. [Qualcomm 分析器](https://docs.qualcomm.com/bundle/publicresource/topics/80-54323-2/command-line-interface.html) 2. Sysmon (Link TBD) 11. 使用者如何從 Snapdragon 平台的異質 AI 引擎中獲益？如何在不同的硬體核心上執行不同的 AI 模型？(GPU、NPU 等) AI SDK 工具和 API 提供選擇執行階段 (CPU、GPU 或 DSP) 的選項。您可以選擇合適的執行階段作為命令列參數或使用特定 C/C++ API。如需詳細資訊，請參閱 [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"` 12. 如果使用 AI SDK 時模型轉換失敗，該怎麼辦？ 請聯絡 [Qualcomm 支援論壇](https://mysupport.qualcomm.com/supportforums/s/) 以取得支援。 13. 自訂浮點模型在 CPU 上提供良好的準確度，但量化模型在 CPU 和 NPU 上的準確度不佳。如何偵錯此項目？ 可能存在與模型量化相關的問題，請參閱 [使用者替換模型](https://docs.qualcomm.com/doc/80-70020-15BT/topic/troubleshooting.html#user-replaced-model) FAQ 以取得模型量化的指引。 14. 一個自訂量化模型在 CPU 上如預期般執行，但在 NPU 上卻無法精確執行相同的模型。如何偵錯此項目？ TBD 15. 執行範例應用程式時，HDMI 螢幕上沒有輸出。如何偵錯此項目？ 請遵循 [顯示除錯](https://docs.qualcomm.com/bundle/publicresource/topics/80-70020-20/bring-up.html#debug-video) 對 HDMI 顯示問題進行除錯。 16. 是否可以使用 HDMI 電視而非 HDMI 監視器來執行範例應用程式？ 通常情況下這會有效，如果無效，請使用 HDMI 顯示器。 17. 如何檢查 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… 18. devtool 健全性檢查錯誤是什麼？如何進行除錯？ 偶爾，您可能會看到 devtool 顯示 sanity check 錯誤 請確保您擁有主機電腦的 sudo 存取權限。如果錯誤仍然存在，請執行以下解決方法： 1. 更新權限。 umask a+rx Copy to clipboard 2. 在 `$ESDK_ROOT/layer/poky/meta/conf/sanity.conf` 檔中停用 BitBake sanity 檢查。 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 19. 在目標裝置上側載 Snapdragon Neural Processing SDK Engine 的步驟。 1. 前往目標裝置殼層並執行以下命令： ssh root@ Copy to clipboard mount -o rw,remount /usr Copy to clipboard exit Copy to clipboard 2. 前往主機電腦上的 SNPE SDK 根資料夾並執行以下命令： 以下命令適用於 QCS6490。 - 如果是 QCS8275：請將 `hexagon-v68` 替換為 `hexagon-v75` - 如果是 QCS9075：請將 `hexagon-v68` 替換為 `hexagon-v73` scp lib/aarch64-oe-linux-gcc11.2/* root@:/usr/lib/ Copy to clipboard scp lib/hexagon-v68/unsigned/* root@:/usr/lib/rfsa/adsp/ Copy to clipboard scp bin/aarch64-oe-linux-gcc11.2/* root@:/usr/bin/ Copy to clipboard ssh root@ Copy to clipboard chmod -R 777 /usr/bin/ Copy to clipboard 3. 驗證新的 SDK 版本： snpe-net-run --version Copy to clipboard 欲深入瞭解如何下載 Qualcomm AI Runtime SDK，請參閱 [Qualcomm 套件管理器](https://docs.qualcomm.com/doc/80-70020-15BT/topic/qairt-install.html#qairt-qpm)。 20. 從 QIM SDK 取得預處理張量並使用 SNPE 進行推論的除錯步驟。 1. 從視訊檔案產生經過預處理的原始張量。 1. 建立用來儲存原始張量的資料夾。 mkdir -p /opt/frames/ Copy to clipboard 2. 啟用顯示。 export XDG_RUNTIME_DIR=/dev/socket/weston && export WAYLAND_DISPLAY=wayland-1 Copy to clipboard 3. 執行 GStreamer 管道以將原始張量傾印至資料夾。 gst-launch-1.0 -v -e filesrc location=/etc/media/video.mp4 ! qtdemux ! queue ! h264parse ! v4l2h264dec capture-io-mode=4 output-io-mode=4 ! queue ! qtimlvconverter ! queue ! neural-network/tensors,type=FLOAT32,rate=30000/1000,dimensions="<<1,520,520,3>>" ! queue ! multifilesink location="/opt/frames/frame_%03d.raw" Copy to clipboard 備註 請根據使用的影片和模型視需要調整速率 (輸入影片的 FPS) 和尺寸 (模型的輸入尺寸)。 2. 透過 SNPE 或 QNN 執行推論。 1. 建立包含原始檔案絕對路徑的 `input_list.txt` 檔案，如下所示。 對 `input_list.txt` 檔案中列出的每個檔案進行推論。 `input_list.txt` 中的範例內容 /opt/frames/frame_000.raw /opt/frames/frame_001.raw Copy to clipboard 2. 在 HTP 後端執行 SNPE DLC 或 QNN 模型。 Tab SNPE Tab QNN snpe-net-run --container .dlc --input_list input_list.txt --output_dir output_htp --use_dsp Copy to clipboard qnn-net-run --model .so --backend libQnnHtp.so --input_list input_list.txt --output_dir output_htp Copy to clipboard 如需詳細資訊，請參閱使用 [Neural Processing Engine](https://docs.qualcomm.com/doc/80-70020-15BT/topic/run-models.html#snpe-run) 或 [AI Engine Direct](https://docs.qualcomm.com/doc/80-70020-15BT/topic/run-models.html#qnn-run) 部署模型。 ## 更多支援 在 [Qualcomm 支援論壇](https://mysupport.qualcomm.com/supportforums/s/) 上提出您的問題。 Last Published: Dec 23, 2025 [Previous Topic 透過超解析度提升影像畫質](https://docs.qualcomm.com/bundle/publicresource/80-70020-15BT/topics/super-resolution.md) [Next Topic 模型移植最佳實務](https://docs.qualcomm.com/bundle/publicresource/80-70020-15BT/topics/appx-export-yolov8.md)