CV Day 2 環境與工具鏈:Colab、torchvision、timm、Ultralytics
執行需求:CPU 可跑。今天我們把整個系列的「地基」打好:從 Colab 的 GPU 設定開始,到本機 Python 與 PyTorch 的版本對齊,再到 torchvision、timm、Ultralytics 這幾個核心套件的安裝與匯入驗證。環境沒弄對,後面的範例都會出狀況;弄對了,後續四十多篇就能放心跑下去。
引言
對很多人來說,學深度學習的第一個門檻不是演算法,而是環境。今天裝好套件、明天版本衝突、後天 CUDA 驅動不相容——這些坑會在不知不覺中消磨掉大半的學習熱情。這個系列選擇把環境議題集中在 Day 2 一次講完,後續章節就能假設你已經有可用的開發環境,把重心放在模型與資料上。
2024 年底,PyTorch 生態系的主流版本是 PyTorch 2.5(搭配 CUDA 12.1 與 12.4)、torchvision 0.20、timm 1.0.x、Ultralytics 8.3.x、albumentations 1.4.x、diffusers 0.31、transformers 4.46、onnxruntime 1.19。這幾個版本彼此之間已經過社群大量測試,組合起來是 2024 年底最穩定的「電腦視覺工具鏈」。我們在系列中固定使用這些版本,並在每篇的延伸資源標明,避免日後升級造成的隱性問題。
讀完這篇,你會知道怎麼在 Colab 上建立 GPU 環境、怎麼在本機建立 Python 虛擬環境、怎麼驗證安裝結果,以及當版本衝突時要怎麼排查。我們會用「可整段執行」的指令串,把每一個步驟都做一遍,並把輸出結果寫在註解裡,這樣你能直接比對自己的結果跟預期是否一致。環境準備對了,後面四十三篇就能省下很多時間。
兩種開發環境:Colab 與本機 venv
在開始裝套件之前,先決定你要在哪裡開發。這個系列支援兩種環境:Google Colab 與本機虛擬環境(venv)。前者完全免費、有現成的 GPU,缺點是 session 會斷線、最長只能用 12 小時(Colab 免費版);後者完全可控、可以長期儲存進度,缺點是你要自己想辦法搞定 GPU(如果沒獨立顯示卡就只能用 CPU)。
建議的學習路徑是:先用 Colab 跑完前幾篇熟悉介面,等到要做完整專案或想長期儲存實驗時,再切回本機。這兩種環境的切換不困難,因為我們的範例都設計成「跨平台可跑」。如果你已經有獨立顯示卡,本機開發會更舒服;如果還沒有,Colab 是最划算的起點。另外,企業內部常會因資安政策不允許把資料上傳到 Colab,這時就必須用本機環境搭配私有雲 GPU(例如 AWS、GCP 或自家的 GPU server)。
Colab 的 GPU 環境設定
打開 Colab 之後,第一件事是確認執行階段(runtime)有沒有 GPU。預設是沒有的,要手動切換。點選上方選單的「執行階段」→「變更執行階段類型」,硬體加速器選「T4 GPU」,按下儲存。這時候 Colab 會幫你配置一台有 16GB 顯存的機器,適合做大多數電腦視覺實驗。
切換完之後,跑下面這段確認 GPU 是否真的可用,並順便安裝本系列固定版本的套件:
!nvidia-smi | head -10
!pip install --quiet torch==2.5.0 torchvision==0.20.0 timm==1.0.9 ultralytics==8.3.40 albumentations==1.4.14 diffusers==0.31.0 transformers==4.46.0
第一行 nvidia-smi 是 NVIDIA 系統管理介面指令,可以印出 GPU 型號、顯存量、驅動版本等資訊。Colab 偶爾會給你不同的 GPU(K80、T4、L4),每一台的顯存與速度都不一樣,做大型訓練時要心裡有數。第二行用 --quiet 安裝套件避免大量輸出,整個過程大約 2 到 5 分鐘。如果 Colab 預裝的版本剛好符合,就會跳過重新安裝,節省時間。萬一安裝失敗,最常見的原因是 Colab 預裝的某個套件版本跟新版衝突,這時可以先 !pip install --upgrade pip 再重試。
本機虛擬環境(venv)
本機開發時,建議用 Python 內建的 venv 建立獨立環境。這樣不同專案的套件不會互相打架,升級或降級也只影響當下的環境。在 macOS、Linux、Windows 上的指令略有不同,這裡用 PowerShell 版本示範(macOS/Linux 只要把 python 改成 python3 即可):
python -m venv .venv-cvision
.\.venv-cvision\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install torch==2.5.0 torchvision==0.20.0 --index-url https://download.pytorch.org/whl/cu121
pip install timm==1.0.9 ultralytics==8.3.40 albumentations==1.4.14 diffusers==0.31.0 transformers==4.46.0 onnxruntime==1.19.2
第一行建立虛擬環境到 .venv-cvision 目錄,第二行啟動它(啟動後命令提示字元前面會出現 (.venv-cvision) 字樣)。第三行把 pip 升級到最新,第四行從 PyTorch 官方提供的 CUDA 12.1 wheel 倉庫安裝 PyTorch。如果你用的是 Apple Silicon,PyTorch 2.5 已經原生支援 MPS(Apple 自己的 GPU 框架),可以把 --index-url 那行換成一般 pip install,並在後續把 .to("cuda") 換成 .to("mps")。如果完全沒有 GPU,就裝 CPU 版,指令是 pip install torch==2.5.0 torchvision==0.20.0 --index-url https://download.pytorch.org/whl/cpu。CPU 版訓練速度慢很多,但能完整執行所有範例,是學習階段最保險的選擇。
驗證安裝結果:六個關鍵套件的匯入檢查
裝完之後,最重要的是驗證。寫一個 check_env.py,把本系列會用到的核心套件都匯入一次,順便印出版本與 GPU 狀態。這個腳本建議每次建立新環境時都跑一次,未來升級或除錯時也能當起點。
import sys
print(f"Python 版本:{sys.version.split()[0]}") # 輸出:Python 版本:3.11.9
import torch
print(f"PyTorch:{torch.__version__}")
print(f"CUDA 可用:{torch.cuda.is_available()}")
print(f"CUDA 版本:{torch.version.cuda}") # 若為 None 表示是 CPU 版
if torch.cuda.is_available():
print(f"GPU:{torch.cuda.get_device_name(0)}")
這個區塊先印出 Python 版本,確認我們在虛擬環境裡(如果看到的是系統 Python 而不是 .venv-cvision 裡的版本,代表虛擬環境沒啟動)。接著檢查 PyTorch 是否能偵測到 CUDA:CPU 環境會看到 CUDA 可用:False,GPU 環境則會顯示 GPU 名稱與 CUDA 版本。這是判斷「我有沒有真的在用 GPU」最直接的方式,未來遇到訓練跑很慢時,第一步就是跑這段確認環境。
接下來檢查 torchvision、timm、Ultralytics 這幾個套件是否能正常匯入。torchvision 提供了影像轉換、預訓練模型與資料集;timm 是 Ross Wightman 維護的模型動物園;Ultralytics 則是 YOLO 系列的核心實作。
import torchvision
import timm
import ultralytics
print(f"torchvision:{torchvision.__version__}") # 輸出:torchvision:0.20.0
print(f"timm:{timm.__version__}") # 輸出:timm:1.0.9
print(f"Ultralytics:{ultralytics.__version__}") # 輸出:Ultralytics:8.3.40
# 列舉幾個 torchvision 內建模型
from torchvision.models import resnet18, vit_b_16
print("torchvision 提供 resnet18 / vit_b_16 等數百個預訓練模型")
# 列舉 timm 內建模型數量
print(f"timm 提供 {len(timm.list_models())} 種預訓練模型")
# 列出 Ultralytics 支援的任務
from ultralytics import YOLO
print("Ultralytics 支援偵測、分割、姿態、分類、OBB 等任務")
這段展示了「匯入不夠、還要驗證功能」的原則:光是 import torchvision 成功,不代表模型權重檔能下載;光是 import timm 成功,不代表你寫的模型名稱拼字正確。透過 len(timm.list_models()) 可以看到 timm 在 2024 年底已經有上千個預訓練模型;Ultralytics 的 YOLO 類別則提供統一的偵測/分割/姿態介面。這個檢查也順便讓你熟悉每個套件最常被呼叫的入口函式,後續章節會反覆用到。
最後驗證 albumentations、diffusers、transformers 與 onnxruntime:
import albumentations as A
import diffusers
import transformers
import onnxruntime as ort
print(f"albumentations:{A.__version__}") # 輸出:albumentations:1.4.14
print(f"diffusers:{diffusers.__version__}") # 輸出:diffusers:0.31.0
print(f"transformers:{transformers.__version__}") # 輸出:transformers:4.46.0
print(f"onnxruntime:{ort.__version__}") # 輸出:onnxruntime:1.19.2
# 隨機抽一個 albumentations 轉換鏈,確認 API 還在
transform = A.Compose([
A.RandomResizedCrop(size=(224, 224), scale=(0.8, 1.0)),
A.HorizontalFlip(p=0.5),
A.Normalize(mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225)),
])
print("albumentations pipeline 建立成功:", type(transform).__name__)
albumentations 是 2024 年電腦視覺社群最常用的影像增強函式庫,速度比 torchvision 內建的 transforms 還快,並且支援更複雜的幾何變換。diffusers 是 Hugging Face 維護的擴散模型函式庫;transformers 則涵蓋更廣的 Transformer 家族,包含 DETR、SAM 2 等偵測與分割模型。onnxruntime 是把模型部署到 CPU 與邊緣裝置的利器,會在 Day 44 詳細介紹。今天只要確認這幾個套件都能匯入即可。
完整實作:一次走完「讀圖 → 前處理 → 模型推論」
環境檢查通過之後,我們做一個端到端的小實驗:用 torchvision 內建的 ResNet18 預訓練模型,對一張影像做推論,並把輸出視覺化。這段範例會用到前面裝好的 torchvision、PIL、matplotlib,是 Day 3 之後所有分類任務的最小骨架。
import urllib.request
from PIL import Image
import torchvision
from torchvision.models import resnet18, ResNet18_Weights
# 下載一張範例影像(dog.jpg)
url = "https://github.com/pytorch/hub/raw/master/images/dog.jpg"
urllib.request.urlretrieve(url, "dog.jpg")
img = Image.open("dog.jpg").convert("RGB")
print("影像尺寸:", img.size) # 輸出:影像尺寸: (1546, 1213)
# 載入預訓練權重與對應的前處理
weights = ResNet18_Weights.DEFAULT
model = resnet18(weights=weights)
model.eval()
preprocess = weights.transforms()
batch = preprocess(img).unsqueeze(0)
print("輸入張量形狀:", tuple(batch.shape)) # 輸出:輸入張量形狀: (1, 3, 224, 224)
第一段用 urllib.request 把 PyTorch hub 上的範例影像抓下來,這個 URL 是 PyTorch 官方提供的穩定連結。第二段用 weights.transforms() 取得 ResNet18 對應的前處理鏈(這個寫法是 torchvision 0.13 之後推薦的,比手寫 transforms.Compose 更安全,因為它跟預訓練權重的訓練方式一致)。unsqueeze(0) 是把 (C, H, W) 變成 (1, C, H, W),加上一個 batch 維度。這種「權重決定前處理」的設計,是 torchvision 0.13 之後最值得記住的改動。
接下來跑推論並印出前五名預測:
import torch
with torch.no_grad():
logits = model(batch)
probs = logits.softmax(dim=1)[0]
# 取出 top-5
top5 = torch.topk(probs, k=5)
for prob, idx in zip(top5.values.tolist(), top5.indices.tolist()):
label = weights.meta["categories"][idx]
print(f"{label:<30} 信心={prob:.3f}")
# 輸出(實際數字會略有不同):
# Samoyed, Samoyede 信心=0.887
# Pomeranian 信心=0.044
# white wolf, Arctic wolf, Canis lupus tundrarum 信心=0.027
# keeshond 信心=0.006
# Eskimo dog, husky 信心=0.005
torch.no_grad() 是推論時的標準寫法,可以省下儲存梯度的記憶體與計算時間。softmax(dim=1) 把 logits 轉成機率分布;torch.topk 同時取最大值與索引。weights.meta["categories"] 是 torchvision 0.13 之後新增的屬性,能直接讀到 ImageNet 的 1000 個類別名稱,不用另外下載 label 檔。整個流程在 CPU 上大概跑 1 秒,GPU 上會更快,但因為這只是單張影像推論,差距不大。f-string 裡的 :<30 是把字串靠左對齊到 30 字元寬,讓輸出排版整齊。
最後示範如何把這次推論的結果寫成記錄檔,這在實戰上很實用:
import json
from pathlib import Path
record = {
"model": "resnet18",
"torchvision": torchvision.__version__,
"image": "dog.jpg",
"top5": [
{"label": weights.meta["categories"][idx], "prob": float(prob)}
for prob, idx in zip(top5.values.tolist(), top5.indices.tolist())
],
}
# 把結果寫成 JSON,方便後續實驗記錄
Path("inference_log.json").write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
print("推論記錄已寫入 inference_log.json") # 輸出:推論記錄已寫入 inference_log.json
這個小片段展示實戰中很常被忽略的事:實驗要記錄。用 JSON 存模型、版本、輸入、輸出這些資訊,未來除錯時才能知道「當時是哪個版本跑出這個結果」。Day 41 的專案章節會進一步介紹 MLflow 與 DVC 等正式的實驗追蹤工具,但 JSON 已經能應付 80% 的日常需求。如果一次推論有上百張影像要跑,可以用串列推論迴圈把每張結果都 append 到 JSON,最後寫成一份完整的評估報告,這是分類任務評估章節(Day 8)的基礎。
常見錯誤與踩雷
第一個常見錯誤是「RuntimeError: Found no NVIDIA driver on your system」。這個訊息代表 PyTorch 的 GPU 版被裝了,但系統沒有對應的 NVIDIA 驅動或 CUDA toolkit。對應的排查方向:用 nvidia-smi 確認顯示卡有沒有被系統認到,如果沒有就是驅動問題;如果有但 PyTorch 看不到,通常是 CUDA 版本對不上。解決方法:到 PyTorch 官方網站選對應 CUDA 版本的安裝指令重新安裝。Windows 使用者還要另外安裝 Visual Studio Build Tools,才能編譯自定義 CUDA 算子。
第二個常見錯誤是「ImportError: cannot import name 'ResNet18_Weights' from 'torchvision.models'」。這個訊息代表 torchvision 版本太舊(0.12 之前沒有這個寫法)。對應的排查方向:用 pip show torchvision 看版本,如果是 0.20 系列就應該有;如果不是,升級到 torchvision==0.20.0。另一個可能原因是 Python 環境裡同時裝了多個 torchvision,這時可以用 pip uninstall torchvision 全部移除再重裝。
第三個是「pip install ultralytics 之後 import 失敗」。Ultralytics 在 8.3.x 對 Python 版本有要求(3.8 以上),如果你的 Python 太舊會出問題。另外,Ultralytics 會自動下載 YOLO 權重,如果你第一次匯入卻沒有網路,會卡住或報錯。對應的排查方向:確認 Python ≥ 3.8、yolo --version 能印出版本、首次執行允許網路下載權重。如果在企業內網受限,可能需要手動下載權重檔並放到指定資料夾。
第四個是「albumentations 與 opencv-python 的相依衝突」。albumentations 1.4.x 會自動安裝 opencv-python-headless 作為後端,但如果你另外裝了 opencv-python,版本衝突會讓匯入失敗。對應的排查方向:用 pip list | grep -i opencv 看目前裝的 OpenCV 套件,必要時 pip install opencv-python-headless==4.10.0.84 強制對齊版本。在 Docker 或 Colab 環境裡,這個衝突特別常見,因為容器映像可能預裝了不同版本的 OpenCV。
第五個是「明明已經 model.to("cuda"),但訓練還是跑 CPU」。這個問題的成因是「模型在 GPU,但資料還在 CPU」。修正方式:把每個 batch 也 .to("cuda"),或更乾淨的做法是寫一個 helper:batch = {k: v.to(device) for k, v in batch.items()}。這是新手最常踩的坑之一,記得訓練迴圈裡同時搬模型與搬資料。
效能與實務提醒
本機 GPU 的選擇對訓練速度影響很大。NVIDIA RTX 3060(12GB 顯存)以上可以做完整的 ResNet、EfficientNet 微調;RTX 4090(24GB)則可以訓練 ViT-Large、做偵測與分割的實驗。Apple Silicon(M1/M2/M3/M4)的 MPS 加速對中小型模型也很順,但部分運算(例如大型 attention)還不支援,遇到時會自動回退到 CPU。CPU 訓練則只建議做最小實驗,正式專案一定要 GPU。如果你的預算有限,建議優先升級 GPU 而不是記憶體或 CPU,深度學習對 GPU 的依賴度最高。
Colab 的免費額度是「每天 12 小時 GPU」,但 2024 年起 Colab 對「GPU 強佔」做了限制——一段時間沒用會被踢下線。可以裝 !pip install colab-autotime 或寫個簡單的 script 定期 print 東西,避免 idle 中斷。如果要做長時間訓練,建議用 Colab Pro(每月約 NT$290,享更長 session 與優先 GPU),或者用 Colab 的背景執行功能(colab-background-notebook)。2024 年底,Colab 也開始支援 A100,雖然額度有限,但對需要大顯存的實驗很有幫助。
最後一個提醒:環境檔案要版本控制。建議把 requirements.txt 放進專案,裡面寫死每個套件的版本(例如 torch==2.5.0)。未來換電腦或跟同事協作時,只要 pip install -r requirements.txt 就能重現一模一樣的環境。這個小習慣能省下大量「為什麼在我的電腦上不能跑」的除錯時間。更嚴謹的做法是用 Poetry 或 uv 管理依賴,並把 lock 檔也提交進版控;這個系列為了簡單統一使用 requirements.txt,但實際專案建議升級到 Poetry。另外,Docker 也是一個好選擇,把環境整個封裝進映像檔,部署時連 Python 版本都不用管;這個系列不會深入 Docker,但 Day 44 部署章節會順便提到 ONNX + Docker 的組合。
小結
今天把整個系列的工具鏈建好了:Colab 與本機 venv 兩種環境都能跑 PyTorch 2.5 + torchvision 0.20 + timm 1.0.9 + Ultralytics 8.3.40 + albumentations 1.4.14 + diffusers 0.31 + transformers 4.46 + onnxruntime 1.19。我們用六段驗證腳本確認每個套件都能匯入並執行核心 API,並用一個 ResNet18 推論範例走完「讀圖 → 前處理 → 模型推論」的最小流程,最後還把推論結果寫入 JSON 作為實驗記錄的最小範例。版本固定是這個系列最重要的紀律:日後升級時請先看官方 release notes,確認沒有破壞性變動再升。
結語
環境準備好了,明天就正式進入分類任務。我們會從 CNN 與 ResNet 的基礎回顧開始,看影像分類在 PyTorch 2.5 的生態系裡有哪些常見寫法,並整理分類任務在「資料 → 模型 → 訓練 → 評估」這條鏈上的標準流程。Day 3 雖然是回顧,但會把後續 Day 4 到 Day 9 都會用到的基礎術語一次講清楚,包括感受野、stride、padding 這些捲積層的細節,以及為什麼 ResNet 的 skip connection 是近代 CNN 的關鍵設計。
延伸資源
- PyTorch 2.5 安裝說明(2024):
https://pytorch.org/get-started/locally/ - torchvision 0.20 模型清單(2024):
https://pytorch.org/vision/stable/models.html - timm 1.0.9 官方說明(2024):
https://huggingface.co/docs/timm/ - Ultralytics 8.3.40 官方說明(2024):
https://docs.ultralytics.com/ - albumentations 1.4 使用手冊(2024):
https://albumentations.ai/docs/ - diffusers 0.31 安裝指南(2024):
https://huggingface.co/docs/diffusers/v0.31.0/
留言
張貼留言