[MYAI Studio SDK] Image-Object-Detection-MobileNetV3-SSD300-PyTorch-Python-1

使用 MobileNetV3-SSDLite-300（Single Shot MultiBox Detector，PyTorch）進行物件偵測的命令列（主控台）流程，可在 Windows 11 與 Ubuntu Linux 24.04 執行。引擎程式（qfgaohao/pytorch-ssd）位於 src/ssd/。內附範例資料集 steel（鋼材表面瑕疵，共 4 個類別：inclusion、patches、rolled_in_scale、scratches）與訓練完成的檢查點，因此推論可直接執行，即使只有 CPU 也能跑。訓練是從零開始（沿用原始 Notebook 的設定），實務上建議使用 NVIDIA GPU，訓練過程可透過 TensorBoard 觀察。

[資料夾結構]

• CLAUDE.md / AGENT.md：程式規格文件，兩個檔案內容完全相同。
• CHANGELOG.md：版本變更紀錄。
• copyright.txt：版權聲明。
• 1905.02244.pdf：MobileNets 參考論文。
• data/{dataset}/labels.txt：以逗號分隔的類別清單，供訓練讀取（步驟 04 產生）。
• data/{dataset}/voc-model-labels.txt：第一行為 BACKGROUND，之後每行一個類別，供推論讀取（步驟 04 產生，訓練時會重新產生）。
• data/{dataset}/train/ 與 valid/：各自包含 image/ 與 annotation/（Pascal VOC XML），以及步驟 04 產生的 train.txt / valid.txt。
• data/{dataset}/test/：包含 image/ 與 annotation/，是保留下來供推論（步驟 07 至 09）使用的測試集。
• model/{dataset}/：mb3-ssd-lite-Epoch-37920.pth（訓練完成的檢查點）、logs/（TensorBoard 紀錄）、output/（標註後的推論結果），以及訓練過程的檢查點。
• src/ssd/：引擎程式（train_ssd.py、run_ssd_example.py、inference_folder_1.py、vision/）。
• src/annotation/：內建的 aiohttp 標註伺服器（步驟 03）。
• tool/tools.py：共用工具函式。
• src/：包裝程式進入點、啟動腳本與本說明文件。
• venv/：Python 虛擬環境，由步驟 01 建立。

[操作步驟及說明]

1. 01_venv_create.bat / 01_venv_create.sh

刪除舊的 venv/，建立全新的虛擬環境，並安裝 src/requirements.txt 中的相依套件。若 pip 安裝失敗，會直接中止並顯示錯誤訊息。

 

2. 01_venv_create_gpu.bat / 01_venv_create_gpu.sh

與步驟 01 相同，但會接著把 torch 換成 CUDA 12.8（cu128）版本，適用於配備 NVIDIA GPU 的機器（驅動的 CUDA 版本需 >= 12.8，可用 nvidia-smi 查詢）。

 

3. 02_venv_activate.bat / 02_venv_activate.sh

啟用虛擬環境。Linux 請以 source 方式執行：source src/02_venv_activate.sh。

 

4. 03_annotation.bat / 03_annotation.sh

啟動標註網頁介面，預設連接埠為 8801。參數：--dataset、--split（train / valid / test）、--port。

 

5. 04_prepare.bat / 04_prepare.sh

依據影像與標註檔，產生 train.txt、valid.txt 以及兩個類別清單檔案。

 

6. 05_train.bat / 05_train.sh

訓練 MobileNetV3-SSDLite-300。從零開始訓練，並自動偵測 GPU；按 Ctrl+C 即可停止。

 

7. 06_tensorboard.bat / 06_tensorboard.sh

在連接埠 6066 啟動 TensorBoard，讀取 model/{dataset}/logs/；按 Ctrl+C 停止。

 

8. 07_inference.bat / 07_inference.sh

對單張影像進行物件偵測，預設影像為 data/steel/test/image/inclusion-9.jpg，門檻值 0.6。

 

9. 08_inference_folder.bat / 08_inference_folder.sh

對整個資料夾中的所有影像進行偵測，預設為測試集，門檻值 0.5。

 

10. 09_inference_folder_1.bat / 09_inference_folder_1.sh

資料夾推論並輸出統計數據：依檔名前綴判定類別（例如 inclusion-9.jpg 對應 inclusion），計算漏檢率（underkill）、過殺率（overkill）與正確率（right rate）。

 

11. 99_venv_clear.bat / 99_venv_clear.sh

刪除 venv/ 虛擬環境資料夾。

 

[Python 程式進入點]

src/annotation_server.py

• --dataset steel：資料集資料夾名稱
• --split：train、valid 或 test
• --port 8801：連接埠
• --no-browser：不自動開啟瀏覽器

內建的 Pascal VOC XML 標註介面，標註結果會寫入 data/{dataset}/{split}/annotation/。

 

src/prepare.py

• --dataset steel：資料集資料夾名稱

產生影像清單、labels.txt（逗號分隔，供訓練讀取）與 voc-model-labels.txt（第一行 BACKGROUND，之後每行一個類別，供推論讀取）。

 

src/train.py

• --dataset steel：資料集資料夾名稱
• --epochs 200000：訓練回合數
• --batch-size 8：批次大小
• --learning-rate 0.01：學習率
• --validation-epochs 20：每幾個 epoch 進行一次驗證
• --workers 0：資料載入的執行緒數，Windows 請保持 0
• --pretrained：預訓練權重路徑（選用）
• --resume：接續訓練的檢查點路徑（選用）
• --clear-logs：清空既有的 TensorBoard 紀錄（選用）

每次驗證都會將 mb3-ssd-lite-Epoch-{N}-Loss-{L}.pth 儲存至 model/{dataset}/，TensorBoard 紀錄則寫入 model/{dataset}/logs/。當驗證損失已達可接受的程度時，按 Ctrl+C 即可停止訓練。

 

src/tensorboard_server.py

• --dataset steel：資料集資料夾名稱
• --port 6066：連接埠
• --no-browser：不自動開啟瀏覽器

用於檢視訓練曲線的 TensorBoard。

 

src/inference.py

• --dataset steel：資料集資料夾名稱
• --source：輸入影像路徑
• --weights：模型權重路徑
• --threshold 0.6：偵測門檻值
• --show：顯示結果影像

標註後的影像會輸出至 model/{dataset}/output/。若系統沒有 GPU，會自動以 CPU 執行。

 

src/inference_folder.py

• --dataset steel：資料集資料夾名稱
• --source：輸入資料夾路徑
• --weights：模型權重路徑
• --threshold 0.5：偵測門檻值
• --stats：輸出漏檢率、過殺率與正確率統計
• --show：顯示結果影像

[快速開始]

Windows 11

src\01_venv_create.bat

src\07_inference.bat

src\05_train.bat（需 GPU 機器）

 

Ubuntu 24.04

bash src/01_venv_create.sh

bash src/07_inference.sh

bash src/05_train.sh（需 GPU 機器）

 

若要使用自己的資料，完整流程為：03_annotation（標註 train 與 valid）→ 04_prepare → 05_train（以 06_tensorboard 觀察，按 Ctrl+C 停止）→ 07 至 09 進行推論，並以 --weights model/{dataset}/mb3-ssd-lite-Epoch-{N}-Loss-{L}.pth 指定訓練好的權重。

[GPU 設定]

PyPI 預設的 torch 套件在 Windows 上僅支援 CPU。若要使用 NVIDIA GPU，請安裝與顯示卡驅動的 CUDA 版本相符的套件（可用 nvidia-smi 查詢）。例如驅動為 CUDA 12.8 時：

pip uninstall -y torch torchvision

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

 

或是直接執行 01_venv_create_gpu 即可。引擎會自動偵測 CUDA，若無法使用則自動改以 CPU 執行。

[參考資料]

• MobileNetV3 論文（Howard 等人，2019，已附於 1905.02244.pdf）：arxiv.org/abs/1905.02244
• MobileNetV3-SSD（原始 readme 所引用）：github.com/shaoshengsong/MobileNetV3-SSD、Compact-Version
• MobileNetV3 其他實作（原始 readme 所引用）：xiaolai-sqlai/mobilenetv3、kuan-wang/pytorch-mobilenet-v3
• SSD 論文（Liu 等人，2016）：arxiv.org/abs/1512.02325
• pytorch-ssd（引擎基礎）：github.com/qfgaohao/pytorch-ssd
• PyTorch 安裝：pytorch.org/get-started/locally

 

這個 SDK 內建於 MYAI Studio 人工智慧開發工具。

 

單獨購買價格：3,000元，永久授權，單一 SDK 授權，單機授權，一次下載，一年電子郵件範例諮詢服務。如果是軟體客製化問題，請購買我們的客製化顧問服務點數。