環境與常見問題¶

完整包應保留哪些內容¶

分發完整的軟體資料夾，包括主程式、_internal、經典環境目錄和異常偵測環境目錄。客戶需要可用的顯示卡驅動及適配的系統執行庫；軟體內包含框架執行庫，不代表可以替代 NVIDIA 驅動。

MkDocs 只用於開發時生成文件，客戶不需要安裝 MkDocs、Python 或另一個網頁伺服器。說明由軟體開啟只監聽本機地址的輕量服務，五種語言頁面及搜尋資源隨包提供。

說明網頁位於隨包的 _internal/help_site。該目錄用於說明入口，不能按普通說明文件隨意刪掉。軟體根目錄的 docs 技術說明和 package-manifest.json 仍不是訓練/推論的執行依賴；manifest 用於檔案完整性排查。

為什麼沒有 mAP¶

先確認是否有獨立驗證集，再看是否到了驗證輪次。經典 COCO 只有訓練集時不執行驗證，也不自動分出圖片。若已執行驗證仍沒有有效值，檢視原始驗證日誌，不使用 loss 替代評估。

GPU 利用率不高¶

GPU 百分比取決於實際任務、批次、圖片尺寸、資料讀取、CPU 前處理和取樣間隔。GPU 利用率與顯示記憶體使用率不是同一概念。檢查日誌是否真的選中了 GPU，以及 data_cost 是否佔據較大比例；經典 Windows 可適度調整 workers，再比較實際吞吐量。

記憶體或顯示記憶體不足¶

先減小 batch，再按任務降低影像尺寸。異常偵測還可降低候選特徵上限、核心集上限或保留比例。不同任務參數含義不同，不要把核心集上限理解成 batch。

經典模型仍在下載預訓練權重¶

“使用配置檔案中的預訓練設定”會沿用 URL，客戶機不一定已有快取。離線時選本地相容權重或隨機初始化。程式結構存在不等於預訓練權重已快取。

權重、類別或前處理不匹配¶

使用與權重一致的任務、配置、類別順序和前處理。經典模型可從訓練實驗匯入；現代分類要保留模型中的前處理後設資料。不要拿普通偵測模型到 OBB 頁面，或把匯出的經典靜態模型當作 .pdparams 檢查點。

ONNX 為什麼在 CPU 上執行¶

當前主推論頁面對現代 ONNX 強制使用 CPU，並在原始日誌中提示。選擇 GPU 不會解除這項現有相容性策略。

說明頁面或搜尋打不開¶

保持軟體開啟，從側邊欄重新開啟說明，檢查預設瀏覽器和本機訪問許可權。無需網際網路。若提示文件缺失，使用包含 help_site 的完整新版本；舊包不會因為原始碼新增文件而自動獲得說明。