本 SDK 以命令列 (Console/Terminal) 的方式，使用 PyTorch 的 ResNet-50 進行影像分類的訓練與推論，支援 Windows 11 與 Ubuntu Linux 24.04。引擎程式位於 src/examples/imagenet/，可透過 --arch 參數切換多種網路架構 (預設 resnet50)。範例資料集 plate 為鋼板表面瑕疵影像，共 6 個類別 (CR、IN、PA、PS、RS、SC)，並附上已訓練好的 ResNet-50 權重，下載後即可直接進行推論。
[資料夾結構]
- CLAUDE.md / AGENT.md：程式規格說明文件 (兩份內容相同)。
- CHANGELOG.md：版本更新紀錄。
- copyright.txt：版權宣告。
- 1512.03385.pdf：ResNet 參考論文。
- data/{dataset}/：labels_map.txt (類別清單，訓練時會重新產生)，以及 train/、val/、test/ 三個資料夾，採用 torchvision ImageFolder 格式 (一個類別一個子資料夾)。
- model/{dataset}/：model_best.pth.tar (最佳權重)、checkpoint.pth.tar (最新權重)、logs/ (TensorBoard 紀錄)。
- tool/tools.py：共用工具函式。
- src/：Python 程式進入點、引擎程式 (examples/imagenet/)、啟動腳本與本說明文件。
- venv/：Python 虛擬環境，由步驟 01 建立。
[執行環境需求]
- 作業系統：Windows 11 或 Ubuntu Linux 24.04。
- Python 3 與 pip。
- 訓練建議使用 NVIDIA 顯示卡；僅推論時 CPU 亦可執行。
[操作步驟及說明]
步驟 1：建立虛擬環境 (CPU 版)
刪除舊的 venv/ 後重新建立，並安裝 src/requirements.txt 內的套件。若 pip 安裝失敗會直接中止並顯示錯誤訊息。
Windows：src\01_venv_create.bat
Linux：bash src/01_venv_create.sh
步驟 2：建立虛擬環境 (GPU 版)
與步驟 1 相同，但會改安裝 CUDA 12.8 (cu128) 版本的 torch，適用於有 NVIDIA 顯示卡的電腦 (驅動程式的 CUDA 版本需大於等於 12.8，可用 nvidia-smi 查詢)。
Windows：src\01_venv_create_gpu.bat
Linux：bash src/01_venv_create_gpu.sh
步驟 3：啟動虛擬環境
啟動 venv。Linux 請使用 source 指令執行。
Windows：src\02_venv_activate.bat
Linux：source src/02_venv_activate.sh
步驟 4：訓練模型
訓練影像分類模型。預設參數為 plate 資料集、resnet50 架構、500 個 epochs、batch size 48、影像尺寸 512、learning rate 0.0005。若 model_best.pth.tar 已存在，會自動接續訓練。
Windows：src\03_train.bat
Linux：bash src/03_train.sh
步驟 5：觀看訓練曲線
以 TensorBoard 開啟 model/{dataset}/logs 內的訓練紀錄。可傳入兩個參數 [dataset] [port]，預設為 plate 與 6066。
Windows：src\04_tensorboard.bat
Linux：bash src/04_tensorboard.sh
步驟 6：單張影像推論
對單一張影像進行分類，預設影像為 data/plate/test/SC/SC-1.png。
Windows：src\05_inference.bat
Linux：bash src/05_inference.sh
步驟 7：整個資料夾推論
對整個資料夾內的影像進行分類 (預設為 data/{dataset}/test)，並統計 Acc@1 與 Acc@5。
Windows：src\06_inference_folder.bat
Linux：bash src/06_inference_folder.sh
步驟 8：資料夾推論 (含漏檢與過殺統計)
同步驟 7，但額外輸出 underkill (漏檢)、overkill (過殺) 與 right rate (正確率) 的統計數據。
Windows：src\07_inference_folder_topk.bat
Linux：bash src/07_inference_folder_topk.sh
步驟 9：清除虛擬環境
刪除 venv/ 資料夾。
Windows：src\99_venv_clear.bat
Linux：bash src/99_venv_clear.sh
[Python 程式進入點]
- src/train.py：--dataset plate --arch resnet50 --batch-size 48 --image-size 512 --epochs 500 --learning-rate 0.0005 --workers 4 [--num-classes N] [--resume PATH] [--pretrained PATH]。類別數量會由 data/{dataset}/train 內的類別資料夾自動判斷。若 model/{dataset}/model_best.pth.tar 存在會自動接續訓練，--resume 設為空字串則從頭訓練。權重檔存放於 model/{dataset}/，TensorBoard 紀錄存放於 model/{dataset}/logs/ (每次執行會清除)。
- src/inference.py：--dataset plate --arch resnet50 --source FILE|FOLDER --batch-size 12 --image-size 512 [--num-classes N] [--weights PATH] [--topk-right] [--show]。--source 指向單一檔案時進行單張推論；指向資料夾時會統計整個資料夾的 Acc@1 與 Acc@5；加上 --topk-right 會改輸出漏檢、過殺與正確率統計；加上 --show 會逐張顯示影像 (需在桌面環境下執行)。
[GPU 設定]
Windows 上由 PyPI 安裝的 torch 預設為 CPU 版本。若要使用 NVIDIA 顯示卡，請依照驅動程式的 CUDA 版本 (可用 nvidia-smi 查詢) 安裝對應的 torch，例如 CUDA 12.8：
pip uninstall -y torch torchvision
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
引擎會自動偵測 CUDA，若無法使用則自動改用 CPU 執行。
[參考資料]
- Deep Residual Learning for Image Recognition 論文 (He et al. 2015，隨附 1512.03385.pdf)：https://arxiv.org/abs/1512.03385
- EfficientNet-PyTorch (內含的引擎專案)：https://github.com/lukemelas/EfficientNet-PyTorch
- 其他網路架構來源：https://github.com/zjZSTU/GoogLeNet、https://github.com/weiaicunzai/pytorch-cifar100、https://github.com/d-li14/mobilenetv3.pytorch
- PyTorch 安裝說明：https://pytorch.org/get-started/locally/
這個 SDK 內建於 MYAI Studio 人工智慧開發工具。
單獨購買價格：3,000元，永久授權，單一 SDK 授權，單機授權，一次下載，一年電子郵件範例諮詢服務。如果是軟體客製化問題，請購買我們的客製化顧問服務點數。