證的完整流程)
1. 為什么 PyTorch 安裝這件事值得單獨(dú)寫(xiě)一篇如果你已經(jīng)裝過(guò)三四次 PyTorch可能會(huì)覺(jué)得這話題沒(méi)什么好聊的——一條命令的事。但我在過(guò)去幾年幫人排查環(huán)境問(wèn)題的經(jīng)歷里遇到最多的恰恰不是模型不收斂、不是顯存爆了而是裝完之后import torch直接報(bào)錯(cuò)或者更隱蔽的裝上了、能跑但 GPU 用不了代碼默默跑在 CPU 上訓(xùn)練一晚上發(fā)現(xiàn)進(jìn)度條幾乎沒(méi)動(dòng)。PyTorch 的安裝之所以容易出問(wèn)題根源在于它的分發(fā)形態(tài)和普通 Python 包不一樣。它不是一個(gè)純 Python 包而是Python 接口 編譯好的 C/CUDA 后端二進(jìn)制的組合體。你pip install torch拿到的 wheel 文件里打包了針對(duì)特定 CUDA 版本、特定操作系統(tǒng)、特定 Python 版本編譯好的動(dòng)態(tài)庫(kù)。這四個(gè)維度Python 版本、操作系統(tǒng)、CUDA 版本、PyTorch 版本只要有一個(gè)對(duì)不上就會(huì)出現(xiàn)各種奇怪的報(bào)錯(cuò)。更麻煩的是網(wǎng)上流傳的安裝教程大量過(guò)期。很多文章還在教你pip install torch1.7.0或者給一個(gè)早就失效的下載鏈接。而 PyTorch 官方從 2.x 開(kāi)始安裝命令的生成邏輯、CUDA 版本的支持矩陣都變了好幾輪。你照著三年前的教程操作大概率會(huì)卡在某個(gè)環(huán)節(jié)。這篇內(nèi)容面向的是這樣幾類人第一次裝 PyTorch 完全不知道從哪下手的新手裝過(guò)但被環(huán)境問(wèn)題折磨過(guò)、想搞清楚背后邏輯的進(jìn)階用戶以及需要在多臺(tái)機(jī)器、多個(gè)項(xiàng)目之間維護(hù)不同 PyTorch 版本的人。我會(huì)把安裝這件事拆成選版本、裝環(huán)境、驗(yàn)證、排錯(cuò)四個(gè)環(huán)節(jié)每個(gè)環(huán)節(jié)都講清楚為什么這么做而不只是給命令。命令你復(fù)制粘貼就行但只有理解了邏輯下次遇到新情況才能自己判斷。先給一個(gè)核心結(jié)論P(yáng)yTorch 安裝的正確姿勢(shì)是先確定你的硬件和驅(qū)動(dòng)能力再反推該裝哪個(gè) CUDA 版本的 PyTorch最后用官方生成的命令安裝裝完必須做一次完整的驗(yàn)證。順序反了就會(huì)反復(fù)重裝。2. 裝之前必須搞清楚的三個(gè)版本關(guān)系很多人裝 PyTorch 失敗是因?yàn)橐簧蟻?lái)就打開(kāi)搜索引擎搜pytorch安裝教程然后照著第一條結(jié)果敲命令。正確的做法是先花五分鐘搞清楚自己機(jī)器上的版本約束這五分鐘能省下后面兩小時(shí)的折騰。2.1 顯卡驅(qū)動(dòng)版本決定了你能用的 CUDA 上限如果你用的是 NVIDIA 顯卡第一件事是打開(kāi)命令行執(zhí)行nvidia-smi這個(gè)命令會(huì)輸出一個(gè)表格右上角有一行CUDA Version: 12.4之類的信息。注意這個(gè)數(shù)字不是你已經(jīng)安裝的 CUDA 版本而是你的驅(qū)動(dòng)所能支持的最高 CUDA 版本。這是最容易誤解的一點(diǎn)。很多人看到這里顯示 12.4就以為自己裝的是 CUDA 12.4其實(shí)系統(tǒng)里可能一個(gè) CUDA Toolkit 都沒(méi)裝。這個(gè)上限值很關(guān)鍵。假設(shè)你的驅(qū)動(dòng)支持到 CUDA 12.1那你就不能裝需要 CUDA 12.4 的 PyTorch 版本否則運(yùn)行時(shí)會(huì)報(bào)CUDA driver version is insufficient for CUDA runtime version。反過(guò)來(lái)驅(qū)動(dòng)支持 12.4你裝 CUDA 11.8 版本的 PyTorch 是完全可以的向下兼容沒(méi)問(wèn)題。如果你的nvidia-smi命令直接報(bào)不是內(nèi)部或外部命令說(shuō)明驅(qū)動(dòng)沒(méi)裝或者沒(méi)加到 PATH。這時(shí)候先去 NVIDIA 官網(wǎng)下載對(duì)應(yīng)顯卡型號(hào)的驅(qū)動(dòng)裝上再回來(lái)繼續(xù)。2.2 PyTorch 自帶的 CUDA 運(yùn)行時(shí)不需要你單獨(dú)裝 CUDA Toolkit這是第二個(gè)高頻誤解。很多人以為要用 GPU 版 PyTorch必須先去 NVIDIA 官網(wǎng)下載安裝幾個(gè) GB 的 CUDA Toolkit。實(shí)際上不需要。PyTorch 的 pip 和 conda 包已經(jīng)把所需的 CUDA 運(yùn)行時(shí)庫(kù)打包進(jìn)去了你裝完 PyTorch 就能直接用 GPU。那什么時(shí)候需要單獨(dú)裝 CUDA Toolkit只有當(dāng)你需要編譯自定義的 CUDA 算子、或者用某些需要調(diào)用nvcc的庫(kù)比如某些版本的 DeepSpeed、apex時(shí)才需要。對(duì)于絕大多數(shù)訓(xùn)練和推理場(chǎng)景PyTorch 自帶的運(yùn)行時(shí)足夠了。這個(gè)設(shè)計(jì)的好處是省事壞處是每個(gè) PyTorch 版本綁定了特定的 CUDA 版本你沒(méi)法自由組合。比如 PyTorch 2.1 的官方 wheel 提供 cu118 和 cu121 兩個(gè)版本你想要 cu120 就沒(méi)有。所以選 PyTorch 版本時(shí)要看你驅(qū)動(dòng)支持的上限能不能覆蓋它綁定的 CUDA 版本。2.3 Python 版本和 PyTorch 版本的對(duì)應(yīng)關(guān)系PyTorch 每個(gè)版本對(duì) Python 的支持范圍是有限的。比如 PyTorch 2.0 支持 Python 3.8 到 3.11PyTorch 2.4 支持 Python 3.8 到 3.12。如果你用的是 Python 3.13那可能只有最新的 PyTorch 版本才支持。這里有個(gè)實(shí)用建議不要用系統(tǒng)自帶的 Python也不要用最新版的 Python。系統(tǒng)自帶的 Python尤其是 Linux 上的往往被系統(tǒng)工具依賴你往里裝包可能搞壞系統(tǒng)。最新版 Python 則可能還沒(méi)被 PyTorch 官方支持。穩(wěn)妥的選擇是用 conda 或 venv 創(chuàng)建一個(gè)獨(dú)立環(huán)境Python 版本選 3.10 或 3.11這兩個(gè)版本目前兼容性最好幾乎所有主流的深度學(xué)習(xí)庫(kù)都支持。把這三個(gè)關(guān)系理清楚你就能確定自己要裝哪個(gè)組合了。下面給一個(gè)決策表你的情況推薦做法有 NVIDIA 顯卡驅(qū)動(dòng)較新裝 GPU 版CUDA 版本選驅(qū)動(dòng)支持上限以下的有 NVIDIA 顯卡驅(qū)動(dòng)很舊先升級(jí)驅(qū)動(dòng)或裝較老的 PyTorch 版本只有核顯或 AMD 顯卡裝 CPU 版或考慮 ROCm 版僅 Linux蘋(píng)果 M 系列芯片裝默認(rèn)版MPS 加速已內(nèi)置不確定先裝 CPU 版跑通流程再換 GPU 版3. 環(huán)境隔離conda 和 venv 到底選哪個(gè)環(huán)境隔離這件事新手容易忽略老手容易過(guò)度糾結(jié)。我的觀點(diǎn)很明確如果你已經(jīng)在用 conda就繼續(xù)用 conda如果沒(méi)用過(guò)直接用 venv 就夠了。不要為了裝 PyTorch 專門(mén)去學(xué) conda。3.1 conda 的優(yōu)勢(shì)和它的坑conda 最大的優(yōu)勢(shì)是它能管理非 Python 的依賴比如 CUDA 運(yùn)行時(shí)、MKL 數(shù)學(xué)庫(kù)這些。用 conda 裝 PyTorch 時(shí)它會(huì)自動(dòng)幫你解決這些底層庫(kù)的版本匹配問(wèn)題。對(duì)于不熟悉系統(tǒng)依賴的用戶這省了不少事。但 conda 也有幾個(gè)坑。第一是下載慢默認(rèn)的 channel 在國(guó)內(nèi)訪問(wèn)速度堪憂需要配置鏡像源。第二是環(huán)境體積大一個(gè)裝了 PyTorch 的 conda 環(huán)境動(dòng)輒幾個(gè) GB。第三是conda 和 pip 混用容易出問(wèn)題如果你先用 conda 裝了 PyTorch又用 pip 裝了某個(gè)依賴可能導(dǎo)致依賴沖突。還有一個(gè)高頻問(wèn)題conda activate命令報(bào)無(wú)法將 conda 項(xiàng)識(shí)別。這通常是因?yàn)?conda 沒(méi)有初始化 shell。解決辦法是執(zhí)行conda init然后重啟終端。Windows 上如果用的是 PowerShell可能還需要調(diào)整執(zhí)行策略。3.2 venv 的輕量和它的局限venv 是 Python 標(biāo)準(zhǔn)庫(kù)自帶的不需要額外安裝創(chuàng)建環(huán)境就是一條命令python -m venv pytorch_env激活方式因系統(tǒng)而異Windows 是pytorch_env\Scripts\activateLinux 和 macOS 是source pytorch_env/bin/activate。venv 的優(yōu)點(diǎn)是輕量、干凈、和 pip 配合完美。缺點(diǎn)是它只管 Python 包不管系統(tǒng)級(jí)的庫(kù)。不過(guò)前面說(shuō)了PyTorch 的 wheel 已經(jīng)把 CUDA 運(yùn)行時(shí)打包進(jìn)去了所以這個(gè)缺點(diǎn)在裝 PyTorch 這個(gè)場(chǎng)景下基本不影響。3.3 我的實(shí)際選擇我自己在本地開(kāi)發(fā)時(shí)用 venv因?yàn)榭臁⒏蓛簟Ｔ诜?wù)器上做多項(xiàng)目隔離時(shí)用 conda因?yàn)樾枰芾聿煌?xiàng)目的 CUDA 版本。如果你只是想在本地跑通 PyTorchvenv 完全夠用而且少一層抽象出問(wèn)題更容易排查。創(chuàng)建好環(huán)境后記得先升級(jí) pippython -m pip install --upgrade pip這一步很多人跳過(guò)但老版本的 pip 在解析 PyTorch 這種大包的依賴時(shí)可能出問(wèn)題升級(jí)一下能避免一些莫名其妙的錯(cuò)誤。4. 拿到正確的安裝命令官方生成器怎么用PyTorch 官網(wǎng)有一個(gè)安裝命令生成器這是最可靠的來(lái)源。但很多人不會(huì)用或者用了但沒(méi)注意細(xì)節(jié)。4.1 生成器的選項(xiàng)怎么選打開(kāi)官網(wǎng)的安裝頁(yè)面你會(huì)看到幾個(gè)下拉框PyTorch Build選 Stable穩(wěn)定版。Preview 是預(yù)覽版除非你要用某個(gè)剛出的新特性否則別選。Your OS選你的操作系統(tǒng)。Package選 pip 或 conda。前面說(shuō)了我推薦 pip。Language選 Python。Compute Platform這是最關(guān)鍵的一項(xiàng)。CUDA 11.8、CUDA 12.1、CUDA 12.4 這些是 GPU 版本CPU 是純 CPU 版本ROCm 是 AMD 顯卡用的。選 Compute Platform 時(shí)對(duì)照你nvidia-smi看到的驅(qū)動(dòng)上限。比如驅(qū)動(dòng)支持到 12.4那 CUDA 12.1 和 11.8 都可以選。選哪個(gè)選較新的那個(gè)因?yàn)樾掳姹就ǔＳ行阅軆?yōu)化和新特性支持。但如果你的項(xiàng)目依賴某個(gè)只支持舊 CUDA 的庫(kù)那就選舊的。生成出來(lái)的命令大概長(zhǎng)這樣pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121注意那個(gè)--index-url參數(shù)它指定了從 PyTorch 自己的包索引下載而不是從 PyPI。這是因?yàn)?PyPI 上的 torch 包默認(rèn)是 CPU 版本或者在某些時(shí)期是特定 CUDA 版本要裝特定 CUDA 版本必須指定索引。4.2 國(guó)內(nèi)下載慢怎么辦PyTorch 的官方索引在國(guó)內(nèi)訪問(wèn)速度不穩(wěn)定幾個(gè) GB 的包下載可能要很久還容易斷。這時(shí)候可以用國(guó)內(nèi)的鏡像源。常用的有清華源、阿里源等。但這里有個(gè)坑鏡像源同步 PyTorch 的 CUDA 版本包可能不全。有些鏡像只同步了 CPU 版本你指定 cu121 的索引它找不到。所以用鏡像時(shí)先確認(rèn)它有沒(méi)有你要的版本。如果鏡像不全可以試試用鏡像下載 CPU 版先跑通流程或者用一些支持?jǐn)帱c(diǎn)續(xù)傳的工具下載 wheel 文件再本地安裝。本地安裝 wheel 的命令是pip install torch-2.4.0cu121-cp311-cp311-linux_x86_64.whlwheel 文件名里的cp311表示 Python 3.11linux_x86_64表示平臺(tái)。下載時(shí)要選對(duì)選錯(cuò)了裝不上。4.3 一個(gè)容易被忽略的細(xì)節(jié)torchvision 和 torchaudio 的版本匹配安裝命令里通常一起裝了 torch、torchvision、torchaudio 三個(gè)包。這三個(gè)包的版本是嚴(yán)格對(duì)應(yīng)的不能隨便混搭。比如 torch 2.4.0 對(duì)應(yīng) torchvision 0.19.0、torchaudio 2.4.0。如果你單獨(dú)升級(jí)了其中一個(gè)可能導(dǎo)致 import 時(shí)報(bào)錯(cuò)。用官方生成的命令一起裝就不會(huì)有這個(gè)問(wèn)題。如果你需要單獨(dú)裝某個(gè)版本去 PyTorch 官網(wǎng)的版本對(duì)應(yīng)表查一下別憑感覺(jué)裝。5. 裝完之后的驗(yàn)證不止是 import torch裝完 PyTorch 后很多人就敲一句import torch看沒(méi)報(bào)錯(cuò)就完事了。這遠(yuǎn)遠(yuǎn)不夠。import torch成功只說(shuō)明 Python 能找到這個(gè)包不代表 CUDA 可用、不代表能正常計(jì)算。完整的驗(yàn)證要分幾層做。5.1 第一層基礎(chǔ)導(dǎo)入和版本確認(rèn)import torch print(torch.__version__) print(torch.version.cuda)第一行輸出 PyTorch 版本比如2.4.0cu121。注意那個(gè)cu121后綴它明確告訴你這是 CUDA 12.1 版本。如果你裝的是 CPU 版這里不會(huì)有cu后綴。第二行輸出 PyTorch 編譯時(shí)用的 CUDA 版本。如果輸出None說(shuō)明你裝的是 CPU 版。如果輸出一個(gè)版本號(hào)說(shuō)明是 GPU 版。這兩行能幫你確認(rèn)裝的是不是你想要的那個(gè)版本。我見(jiàn)過(guò)有人以為自己裝了 GPU 版結(jié)果torch.version.cuda輸出 None白折騰半天。5.2 第二層CUDA 是否真的可用print(torch.cuda.is_available()) print(torch.cuda.device_count()) print(torch.cuda.get_device_name(0))is_available()返回 True 才算 GPU 可用。如果返回 False即使你裝的是 GPU 版也用不了。常見(jiàn)原因有幾個(gè)驅(qū)動(dòng)版本太低、顯卡太老不支持當(dāng)前 CUDA、或者系統(tǒng)里有多個(gè) CUDA 版本沖突。device_count()返回可見(jiàn)的 GPU 數(shù)量。如果你有多張卡但這里只顯示一張可能是CUDA_VISIBLE_DEVICES環(huán)境變量限制了。get_device_name(0)返回第一張卡的型號(hào)確認(rèn)一下是不是你預(yù)期的那張。5.3 第三層實(shí)際跑一次 GPU 計(jì)算前面兩步都是查詢狀態(tài)真正要驗(yàn)證的是能不能在 GPU 上做計(jì)算。跑一段最小代碼import torch # 創(chuàng)建一個(gè)張量并移到 GPU x torch.randn(1000, 1000).cuda() y torch.randn(1000, 1000).cuda() # 做一次矩陣乘法 z torch.matmul(x, y) # 把結(jié)果移回 CPU 并打印 print(z.sum().item()) print(z.device)這段代碼做了三件事在 GPU 上創(chuàng)建張量、在 GPU 上做矩陣乘法、把結(jié)果移回 CPU。如果全部跑通且z.device輸出cuda:0說(shuō)明 GPU 計(jì)算鏈路是通的。為什么要在 GPU 上做矩陣乘法而不是簡(jiǎn)單加法因?yàn)榫仃嚦朔〞?huì)調(diào)用 cuBLAS 庫(kù)能驗(yàn)證 CUDA 的數(shù)學(xué)庫(kù)是否正常工作。加法可能只用到最基礎(chǔ)的 kernel驗(yàn)證不夠充分。5.4 第四層驗(yàn)證反向傳播如果你要用 PyTorch 訓(xùn)練模型還得驗(yàn)證自動(dòng)求導(dǎo)在 GPU 上是否正常import torch x torch.randn(10, 10, requires_gradTrue, devicecuda) y (x ** 2).sum() y.backward() print(x.grad.device) print(x.grad.shape)這段代碼驗(yàn)證了 GPU 上的反向傳播。如果x.grad能正常計(jì)算出來(lái)且 device 是 cuda說(shuō)明訓(xùn)練所需的核心功能都正常。5.5 一個(gè)完整的驗(yàn)證腳本把上面幾層整合成一個(gè)腳本每次裝完新環(huán)境跑一遍import torch def verify_pytorch(): print(fPyTorch version: {torch.__version__}) print(fCUDA version: {torch.version.cuda}) print(fCUDA available: {torch.cuda.is_available()}) if torch.cuda.is_available(): print(fDevice count: {torch.cuda.device_count()}) print(fDevice name: {torch.cuda.get_device_name(0)}) # GPU 計(jì)算測(cè)試 x torch.randn(1000, 1000, devicecuda) y torch.randn(1000, 1000, devicecuda) z torch.matmul(x, y) print(fMatmul result device: {z.device}) # 反向傳播測(cè)試 a torch.randn(10, 10, requires_gradTrue, devicecuda) b (a ** 2).sum() b.backward() print(fGradient device: {a.grad.device}) print(All GPU checks passed.) else: print(CUDA not available, running on CPU only.) if __name__ __main__: verify_pytorch()這個(gè)腳本我放在每個(gè)新環(huán)境的根目錄裝完就跑一次幾秒鐘的事能省下后面大量排查時(shí)間。6. 那些年我踩過(guò)的安裝坑和排查思路前面講的是正確流程但現(xiàn)實(shí)中你更可能遇到的是已經(jīng)出問(wèn)題了怎么辦。這一節(jié)我把遇到過(guò)的典型問(wèn)題和排查鏈路整理出來(lái)你可以對(duì)照自己的報(bào)錯(cuò)找線索。6.1 報(bào)錯(cuò) CUDA driver version is insufficient這個(gè)報(bào)錯(cuò)的意思是你裝的 PyTorch 需要的 CUDA 運(yùn)行時(shí)版本高于你驅(qū)動(dòng)支持的版本。比如你裝了 cu121 的 PyTorch但驅(qū)動(dòng)只支持到 CUDA 11.8。排查步驟先nvidia-smi看驅(qū)動(dòng)支持的 CUDA 上限再python -c import torch; print(torch.version.cuda)看 PyTorch 需要的版本。如果前者小于后者就是這個(gè)問(wèn)題。解決辦法有兩個(gè)升級(jí)顯卡驅(qū)動(dòng)或者重裝一個(gè)低 CUDA 版本的 PyTorch。升級(jí)驅(qū)動(dòng)通常更簡(jiǎn)單去 NVIDIA 官網(wǎng)下載對(duì)應(yīng)型號(hào)的最新驅(qū)動(dòng)裝上就行。但如果是服務(wù)器升級(jí)驅(qū)動(dòng)可能需要重啟要挑個(gè)合適的時(shí)間。6.2 報(bào)錯(cuò) ImportError: libcudart.so.11.0: cannot open shared object file這是 Linux 上常見(jiàn)的問(wèn)題說(shuō)明系統(tǒng)找不到 CUDA 運(yùn)行時(shí)庫(kù)。可能的原因PyTorch 裝的是 GPU 版但系統(tǒng)里沒(méi)有對(duì)應(yīng)的 CUDA 庫(kù)而 PyTorch 又沒(méi)能用自帶的。等等前面不是說(shuō) PyTorch 自帶 CUDA 運(yùn)行時(shí)嗎是的但有些情況下它會(huì)去系統(tǒng)路徑找。比如你用 conda 裝的時(shí)候conda 可能裝了一個(gè)系統(tǒng)級(jí)的 CUDA 庫(kù)然后 PyTorch 去鏈接它結(jié)果版本對(duì)不上。排查方法ldd命令查看 torch 的動(dòng)態(tài)庫(kù)依賴ldd $(python -c import torch; print(torch.__file__)) | grep cuda如果看到某些 cuda 庫(kù)顯示 not found就是這個(gè)問(wèn)題。解決辦法通常是重裝 PyTorch確保用 pip 而不是 conda或者清理掉系統(tǒng)里沖突的 CUDA 庫(kù)。6.3 裝完 import 很慢或者卡住有時(shí)候import torch要等十幾秒甚至更久。這通常不是安裝問(wèn)題而是 PyTorch 在初始化時(shí)掃描 CUDA 設(shè)備、加載庫(kù)。如果機(jī)器上有多個(gè) CUDA 版本或者網(wǎng)絡(luò)文件系統(tǒng)慢會(huì)更明顯。一個(gè)緩解辦法是設(shè)置環(huán)境變量CUDA_MODULE_LOADINGLAZY讓 CUDA 模塊延遲加載。另一個(gè)辦法是確認(rèn)沒(méi)有多個(gè) CUDA 版本在 PATH 里打架。如果 import 直接卡死不動(dòng)可能是顯卡驅(qū)動(dòng)和 PyTorch 版本不兼容或者有其他進(jìn)程占用了 GPU。先nvidia-smi看看有沒(méi)有僵尸進(jìn)程占著顯存。6.4 Windows 上的特有問(wèn)題Windows 上裝 PyTorch 有幾個(gè)額外的坑。第一是路徑里有中文或空格可能導(dǎo)致某些庫(kù)加載失敗。建議把 Python 環(huán)境和項(xiàng)目都放在純英文、無(wú)空格的路徑下。第二是多個(gè) Python 版本共存。Windows 上可能同時(shí)裝了 Python 3.9、3.10、3.11你pip install裝到了 A 版本但運(yùn)行時(shí)用的是 B 版本。解決辦法是用python -m pip install而不是直接pip install確保裝到當(dāng)前python對(duì)應(yīng)的環(huán)境里。第三是驅(qū)動(dòng)簽名問(wèn)題。有些情況下 Windows 會(huì)攔截未簽名的驅(qū)動(dòng)導(dǎo)致 GPU 不可用。這個(gè)在正規(guī)渠道下載的 NVIDIA 驅(qū)動(dòng)上很少見(jiàn)但如果遇到了需要調(diào)整系統(tǒng)的驅(qū)動(dòng)簽名策略。6.5 排查問(wèn)題的通用思路遇到任何安裝問(wèn)題按這個(gè)順序排查確認(rèn)版本python --version、pip --version、nvidia-smi、torch.__version__把四個(gè)版本都打出來(lái)。確認(rèn)環(huán)境which pythonLinux或where pythonWindows確認(rèn)你操作的是哪個(gè) Python。確認(rèn)安裝位置python -c import torch; print(torch.__file__)看 torch 是從哪加載的?？赐暾麍?bào)錯(cuò)不要只看最后一行往上翻通常真正的錯(cuò)誤信息在前面。搜索報(bào)錯(cuò)關(guān)鍵詞把報(bào)錯(cuò)的核心句子去掉路徑和變量名拿去搜通常能找到遇到同樣問(wèn)題的人。這個(gè)順序的核心邏輯是先確認(rèn)事實(shí)再猜測(cè)原因。很多人一看到報(bào)錯(cuò)就開(kāi)始瞎試試了半小時(shí)才發(fā)現(xiàn)自己一直在錯(cuò)誤的 Python 環(huán)境里操作。7. 多版本共存和項(xiàng)目隔離的實(shí)戰(zhàn)建議如果你同時(shí)維護(hù)多個(gè)項(xiàng)目它們可能依賴不同版本的 PyTorch。這時(shí)候怎么管理7.1 一個(gè)項(xiàng)目一個(gè)環(huán)境最穩(wěn)妥的做法是每個(gè)項(xiàng)目一個(gè)獨(dú)立環(huán)境。用 venv 的話cd project_a python -m venv .venv source .venv/bin/activate # Linux/macOS pip install torch2.1.0 cd ../project_b python -m venv .venv source .venv/bin/activate pip install torch2.4.0每個(gè)項(xiàng)目的依賴記錄在requirements.txt里換機(jī)器時(shí)重建環(huán)境就行。這個(gè)做法看起來(lái)笨但最不容易出問(wèn)題。7.2 用 requirements.txt 鎖定版本requirements.txt里不要只寫(xiě)torch要寫(xiě)具體版本torch2.4.0 torchvision0.19.0 torchaudio2.4.0如果用了 CUDA 特定版本還要在安裝時(shí)指定索引。可以在 requirements 文件里加一行--index-url https://download.pytorch.org/whl/cu121 torch2.4.0這樣pip install -r requirements.txt就會(huì)從正確的索引裝正確的版本。7.3 導(dǎo)出和復(fù)現(xiàn)環(huán)境裝好一個(gè)能用的環(huán)境后導(dǎo)出完整依賴列表pip freeze requirements_lock.txt這個(gè)文件記錄了所有包的精確版本包括間接依賴。換機(jī)器時(shí)用這個(gè)文件重建能最大程度復(fù)現(xiàn)原環(huán)境。注意pip freeze會(huì)導(dǎo)出所有包包括你不需要的可以手動(dòng)清理一下。7.4 關(guān)于 Docker 的一點(diǎn)建議如果你的項(xiàng)目要部署到服務(wù)器或者需要嚴(yán)格的環(huán)境一致性用 Docker 是最省心的。PyTorch 官方提供了各種版本的鏡像直接FROM pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime就行。Docker 的好處是環(huán)境完全隔離不會(huì)和宿主機(jī)沖突。壞處是需要 GPU 支持時(shí)要裝 nvidia-container-toolkit多一層配置。如果你只是本地開(kāi)發(fā)用 venv 就夠了如果要部署Docker 值得投入時(shí)間學(xué)一下。8. 驗(yàn)證通過(guò)之后下一步做什么裝完、驗(yàn)證通過(guò)只是萬(wàn)里長(zhǎng)征第一步。接下來(lái)你大概率要做這幾件事我順帶說(shuō)幾個(gè)容易踩的點(diǎn)。第一件事是確認(rèn)你的數(shù)據(jù)能正常加載到 GPU。很多人驗(yàn)證時(shí)用的是隨機(jī)張量真到加載數(shù)據(jù)集時(shí)發(fā)現(xiàn) DataLoader 的num_workers設(shè)置不對(duì)或者 pin_memory 沒(méi)開(kāi)導(dǎo)致 GPU 利用率上不去。這些是性能問(wèn)題不是安裝問(wèn)題但裝完就該順手檢查。第二件事是確認(rèn)混合精度訓(xùn)練能用。如果你打算用torch.cuda.amp裝完可以跑個(gè)小例子驗(yàn)證一下from torch.cuda.amp import autocast, GradScaler scaler GradScaler() with autocast(): # 你的前向計(jì)算 pass如果這里報(bào)錯(cuò)可能是 PyTorch 版本和 CUDA 版本不匹配或者顯卡太老不支持。第三件事是記錄下你的環(huán)境信息。把torch.__version__、torch.version.cuda、nvidia-smi的輸出存一份以后出問(wèn)題時(shí)對(duì)比用。我習(xí)慣在項(xiàng)目根目錄放一個(gè)env_info.txt記錄這些信息團(tuán)隊(duì)協(xié)作時(shí)特別有用。最后分享一個(gè)我自己的習(xí)慣每次裝完新環(huán)境除了跑驗(yàn)證腳本我還會(huì)跑一個(gè)最小的訓(xùn)練循環(huán)用真實(shí)的數(shù)據(jù)集比如 MNIST訓(xùn)練幾個(gè) epoch確認(rèn)整個(gè)鏈路——數(shù)據(jù)加載、前向、反向、優(yōu)化器更新、驗(yàn)證——都正常。這個(gè)測(cè)試大概兩分鐘但能發(fā)現(xiàn)很多import torch發(fā)現(xiàn)不了的問(wèn)題。裝環(huán)境這件事多花十分鐘驗(yàn)證能省下后面幾小時(shí)的排查。 PyTorch安裝避坑指南：從版本選擇到GPU驗(yàn)證的完整流程
1. 為什么 PyTorch 安裝這件事值得單獨(dú)寫(xiě)一篇如果你已經(jīng)裝過(guò)三四次 PyTorch可能會(huì)覺(jué)得這話題沒(méi)什么好聊的——一條命令的事。但我在過(guò)去幾年幫人排查環(huán)境問(wèn)題的經(jīng)歷里遇到最多的恰恰不是模型不收斂、不是顯存爆了而是裝完之后import torch直接報(bào)錯(cuò)或者更隱蔽的裝上了、能跑但 GPU 用不了代碼默默跑在 CPU 上訓(xùn)練一晚上發(fā)現(xiàn)進(jìn)度條幾乎沒(méi)動(dòng)。PyTorch 的安裝之所以容易出問(wèn)題根源在于它的分發(fā)形態(tài)和普通 Python 包不一樣。它不是一個(gè)純 Python 包而是Python 接口 編譯好的 C/CUDA 后端二進(jìn)制的組合體。你pip install torch拿到的 wheel 文件里打包了針對(duì)特定 CUDA 版本、特定操作系統(tǒng)、特定 Python 版本編譯好的動(dòng)態(tài)庫(kù)。這四個(gè)維度Python 版本、操作系統(tǒng)、CUDA 版本、PyTorch 版本只要有一個(gè)對(duì)不上就會(huì)出現(xiàn)各種奇怪的報(bào)錯(cuò)。更麻煩的是網(wǎng)上流傳的安裝教程大量過(guò)期。很多文章還在教你pip install torch1.7.0或者給一個(gè)早就失效的下載鏈接。而 PyTorch 官方從 2.x 開(kāi)始安裝命令的生成邏輯、CUDA 版本的支持矩陣都變了好幾輪。你照著三年前的教程操作大概率會(huì)卡在某個(gè)環(huán)節(jié)。這篇內(nèi)容面向的是這樣幾類人第一次裝 PyTorch 完全不知道從哪下手的新手裝過(guò)但被環(huán)境問(wèn)題折磨過(guò)、想搞清楚背后邏輯的進(jìn)階用戶以及需要在多臺(tái)機(jī)器、多個(gè)項(xiàng)目之間維護(hù)不同 PyTorch 版本的人。我會(huì)把安裝這件事拆成選版本、裝環(huán)境、驗(yàn)證、排錯(cuò)四個(gè)環(huán)節(jié)每個(gè)環(huán)節(jié)都講清楚為什么這么做而不只是給命令。命令你復(fù)制粘貼就行但只有理解了邏輯下次遇到新情況才能自己判斷。先給一個(gè)核心結(jié)論P(yáng)yTorch 安裝的正確姿勢(shì)是先確定你的硬件和驅(qū)動(dòng)能力再反推該裝哪個(gè) CUDA 版本的 PyTorch最后用官方生成的命令安裝裝完必須做一次完整的驗(yàn)證。順序反了就會(huì)反復(fù)重裝。2. 裝之前必須搞清楚的三個(gè)版本關(guān)系很多人裝 PyTorch 失敗是因?yàn)橐簧蟻?lái)就打開(kāi)搜索引擎搜pytorch安裝教程然后照著第一條結(jié)果敲命令。正確的做法是先花五分鐘搞清楚自己機(jī)器上的版本約束這五分鐘能省下后面兩小時(shí)的折騰。2.1 顯卡驅(qū)動(dòng)版本決定了你能用的 CUDA 上限如果你用的是 NVIDIA 顯卡第一件事是打開(kāi)命令行執(zhí)行nvidia-smi這個(gè)命令會(huì)輸出一個(gè)表格右上角有一行CUDA Version: 12.4之類的信息。注意這個(gè)數(shù)字不是你已經(jīng)安裝的 CUDA 版本而是你的驅(qū)動(dòng)所能支持的最高 CUDA 版本。這是最容易誤解的一點(diǎn)。很多人看到這里顯示 12.4就以為自己裝的是 CUDA 12.4其實(shí)系統(tǒng)里可能一個(gè) CUDA Toolkit 都沒(méi)裝。這個(gè)上限值很關(guān)鍵。假設(shè)你的驅(qū)動(dòng)支持到 CUDA 12.1那你就不能裝需要 CUDA 12.4 的 PyTorch 版本否則運(yùn)行時(shí)會(huì)報(bào)CUDA driver version is insufficient for CUDA runtime version。反過(guò)來(lái)驅(qū)動(dòng)支持 12.4你裝 CUDA 11.8 版本的 PyTorch 是完全可以的向下兼容沒(méi)問(wèn)題。如果你的nvidia-smi命令直接報(bào)不是內(nèi)部或外部命令說(shuō)明驅(qū)動(dòng)沒(méi)裝或者沒(méi)加到 PATH。這時(shí)候先去 NVIDIA 官網(wǎng)下載對(duì)應(yīng)顯卡型號(hào)的驅(qū)動(dòng)裝上再回來(lái)繼續(xù)。2.2 PyTorch 自帶的 CUDA 運(yùn)行時(shí)不需要你單獨(dú)裝 CUDA Toolkit這是第二個(gè)高頻誤解。很多人以為要用 GPU 版 PyTorch必須先去 NVIDIA 官網(wǎng)下載安裝幾個(gè) GB 的 CUDA Toolkit。實(shí)際上不需要。PyTorch 的 pip 和 conda 包已經(jīng)把所需的 CUDA 運(yùn)行時(shí)庫(kù)打包進(jìn)去了你裝完 PyTorch 就能直接用 GPU。那什么時(shí)候需要單獨(dú)裝 CUDA Toolkit只有當(dāng)你需要編譯自定義的 CUDA 算子、或者用某些需要調(diào)用nvcc的庫(kù)比如某些版本的 DeepSpeed、apex時(shí)才需要。對(duì)于絕大多數(shù)訓(xùn)練和推理場(chǎng)景PyTorch 自帶的運(yùn)行時(shí)足夠了。這個(gè)設(shè)計(jì)的好處是省事壞處是每個(gè) PyTorch 版本綁定了特定的 CUDA 版本你沒(méi)法自由組合。比如 PyTorch 2.1 的官方 wheel 提供 cu118 和 cu121 兩個(gè)版本你想要 cu120 就沒(méi)有。所以選 PyTorch 版本時(shí)要看你驅(qū)動(dòng)支持的上限能不能覆蓋它綁定的 CUDA 版本。2.3 Python 版本和 PyTorch 版本的對(duì)應(yīng)關(guān)系PyTorch 每個(gè)版本對(duì) Python 的支持范圍是有限的。比如 PyTorch 2.0 支持 Python 3.8 到 3.11PyTorch 2.4 支持 Python 3.8 到 3.12。如果你用的是 Python 3.13那可能只有最新的 PyTorch 版本才支持。這里有個(gè)實(shí)用建議不要用系統(tǒng)自帶的 Python也不要用最新版的 Python。系統(tǒng)自帶的 Python尤其是 Linux 上的往往被系統(tǒng)工具依賴你往里裝包可能搞壞系統(tǒng)。最新版 Python 則可能還沒(méi)被 PyTorch 官方支持。穩(wěn)妥的選擇是用 conda 或 venv 創(chuàng)建一個(gè)獨(dú)立環(huán)境Python 版本選 3.10 或 3.11這兩個(gè)版本目前兼容性最好幾乎所有主流的深度學(xué)習(xí)庫(kù)都支持。把這三個(gè)關(guān)系理清楚你就能確定自己要裝哪個(gè)組合了。下面給一個(gè)決策表你的情況推薦做法有 NVIDIA 顯卡驅(qū)動(dòng)較新裝 GPU 版CUDA 版本選驅(qū)動(dòng)支持上限以下的有 NVIDIA 顯卡驅(qū)動(dòng)很舊先升級(jí)驅(qū)動(dòng)或裝較老的 PyTorch 版本只有核顯或 AMD 顯卡裝 CPU 版或考慮 ROCm 版僅 Linux蘋(píng)果 M 系列芯片裝默認(rèn)版MPS 加速已內(nèi)置不確定先裝 CPU 版跑通流程再換 GPU 版3. 環(huán)境隔離conda 和 venv 到底選哪個(gè)環(huán)境隔離這件事新手容易忽略老手容易過(guò)度糾結(jié)。我的觀點(diǎn)很明確如果你已經(jīng)在用 conda就繼續(xù)用 conda如果沒(méi)用過(guò)直接用 venv 就夠了。不要為了裝 PyTorch 專門(mén)去學(xué) conda。3.1 conda 的優(yōu)勢(shì)和它的坑conda 最大的優(yōu)勢(shì)是它能管理非 Python 的依賴比如 CUDA 運(yùn)行時(shí)、MKL 數(shù)學(xué)庫(kù)這些。用 conda 裝 PyTorch 時(shí)它會(huì)自動(dòng)幫你解決這些底層庫(kù)的版本匹配問(wèn)題。對(duì)于不熟悉系統(tǒng)依賴的用戶這省了不少事。但 conda 也有幾個(gè)坑。第一是下載慢默認(rèn)的 channel 在國(guó)內(nèi)訪問(wèn)速度堪憂需要配置鏡像源。第二是環(huán)境體積大一個(gè)裝了 PyTorch 的 conda 環(huán)境動(dòng)輒幾個(gè) GB。第三是conda 和 pip 混用容易出問(wèn)題如果你先用 conda 裝了 PyTorch又用 pip 裝了某個(gè)依賴可能導(dǎo)致依賴沖突。還有一個(gè)高頻問(wèn)題conda activate命令報(bào)無(wú)法將 conda 項(xiàng)識(shí)別。這通常是因?yàn)?conda 沒(méi)有初始化 shell。解決辦法是執(zhí)行conda init然后重啟終端。Windows 上如果用的是 PowerShell可能還需要調(diào)整執(zhí)行策略。3.2 venv 的輕量和它的局限venv 是 Python 標(biāo)準(zhǔn)庫(kù)自帶的不需要額外安裝創(chuàng)建環(huán)境就是一條命令python -m venv pytorch_env激活方式因系統(tǒng)而異Windows 是pytorch_env\Scripts\activateLinux 和 macOS 是source pytorch_env/bin/activate。venv 的優(yōu)點(diǎn)是輕量、干凈、和 pip 配合完美。缺點(diǎn)是它只管 Python 包不管系統(tǒng)級(jí)的庫(kù)。不過(guò)前面說(shuō)了PyTorch 的 wheel 已經(jīng)把 CUDA 運(yùn)行時(shí)打包進(jìn)去了所以這個(gè)缺點(diǎn)在裝 PyTorch 這個(gè)場(chǎng)景下基本不影響。3.3 我的實(shí)際選擇我自己在本地開(kāi)發(fā)時(shí)用 venv因?yàn)榭臁⒏蓛簟Ｔ诜?wù)器上做多項(xiàng)目隔離時(shí)用 conda因?yàn)樾枰芾聿煌?xiàng)目的 CUDA 版本。如果你只是想在本地跑通 PyTorchvenv 完全夠用而且少一層抽象出問(wèn)題更容易排查。創(chuàng)建好環(huán)境后記得先升級(jí) pippython -m pip install --upgrade pip這一步很多人跳過(guò)但老版本的 pip 在解析 PyTorch 這種大包的依賴時(shí)可能出問(wèn)題升級(jí)一下能避免一些莫名其妙的錯(cuò)誤。4. 拿到正確的安裝命令官方生成器怎么用PyTorch 官網(wǎng)有一個(gè)安裝命令生成器這是最可靠的來(lái)源。但很多人不會(huì)用或者用了但沒(méi)注意細(xì)節(jié)。4.1 生成器的選項(xiàng)怎么選打開(kāi)官網(wǎng)的安裝頁(yè)面你會(huì)看到幾個(gè)下拉框PyTorch Build選 Stable穩(wěn)定版。Preview 是預(yù)覽版除非你要用某個(gè)剛出的新特性否則別選。Your OS選你的操作系統(tǒng)。Package選 pip 或 conda。前面說(shuō)了我推薦 pip。Language選 Python。Compute Platform這是最關(guān)鍵的一項(xiàng)。CUDA 11.8、CUDA 12.1、CUDA 12.4 這些是 GPU 版本CPU 是純 CPU 版本ROCm 是 AMD 顯卡用的。選 Compute Platform 時(shí)對(duì)照你nvidia-smi看到的驅(qū)動(dòng)上限。比如驅(qū)動(dòng)支持到 12.4那 CUDA 12.1 和 11.8 都可以選。選哪個(gè)選較新的那個(gè)因?yàn)樾掳姹就ǔＳ行阅軆?yōu)化和新特性支持。但如果你的項(xiàng)目依賴某個(gè)只支持舊 CUDA 的庫(kù)那就選舊的。生成出來(lái)的命令大概長(zhǎng)這樣pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121注意那個(gè)--index-url參數(shù)它指定了從 PyTorch 自己的包索引下載而不是從 PyPI。這是因?yàn)?PyPI 上的 torch 包默認(rèn)是 CPU 版本或者在某些時(shí)期是特定 CUDA 版本要裝特定 CUDA 版本必須指定索引。4.2 國(guó)內(nèi)下載慢怎么辦PyTorch 的官方索引在國(guó)內(nèi)訪問(wèn)速度不穩(wěn)定幾個(gè) GB 的包下載可能要很久還容易斷。這時(shí)候可以用國(guó)內(nèi)的鏡像源。常用的有清華源、阿里源等。但這里有個(gè)坑鏡像源同步 PyTorch 的 CUDA 版本包可能不全。有些鏡像只同步了 CPU 版本你指定 cu121 的索引它找不到。所以用鏡像時(shí)先確認(rèn)它有沒(méi)有你要的版本。如果鏡像不全可以試試用鏡像下載 CPU 版先跑通流程或者用一些支持?jǐn)帱c(diǎn)續(xù)傳的工具下載 wheel 文件再本地安裝。本地安裝 wheel 的命令是pip install torch-2.4.0cu121-cp311-cp311-linux_x86_64.whlwheel 文件名里的cp311表示 Python 3.11linux_x86_64表示平臺(tái)。下載時(shí)要選對(duì)選錯(cuò)了裝不上。4.3 一個(gè)容易被忽略的細(xì)節(jié)torchvision 和 torchaudio 的版本匹配安裝命令里通常一起裝了 torch、torchvision、torchaudio 三個(gè)包。這三個(gè)包的版本是嚴(yán)格對(duì)應(yīng)的不能隨便混搭。比如 torch 2.4.0 對(duì)應(yīng) torchvision 0.19.0、torchaudio 2.4.0。如果你單獨(dú)升級(jí)了其中一個(gè)可能導(dǎo)致 import 時(shí)報(bào)錯(cuò)。用官方生成的命令一起裝就不會(huì)有這個(gè)問(wèn)題。如果你需要單獨(dú)裝某個(gè)版本去 PyTorch 官網(wǎng)的版本對(duì)應(yīng)表查一下別憑感覺(jué)裝。5. 裝完之后的驗(yàn)證不止是 import torch裝完 PyTorch 后很多人就敲一句import torch看沒(méi)報(bào)錯(cuò)就完事了。這遠(yuǎn)遠(yuǎn)不夠。import torch成功只說(shuō)明 Python 能找到這個(gè)包不代表 CUDA 可用、不代表能正常計(jì)算。完整的驗(yàn)證要分幾層做。5.1 第一層基礎(chǔ)導(dǎo)入和版本確認(rèn)import torch print(torch.__version__) print(torch.version.cuda)第一行輸出 PyTorch 版本比如2.4.0cu121。注意那個(gè)cu121后綴它明確告訴你這是 CUDA 12.1 版本。如果你裝的是 CPU 版這里不會(huì)有cu后綴。第二行輸出 PyTorch 編譯時(shí)用的 CUDA 版本。如果輸出None說(shuō)明你裝的是 CPU 版。如果輸出一個(gè)版本號(hào)說(shuō)明是 GPU 版。這兩行能幫你確認(rèn)裝的是不是你想要的那個(gè)版本。我見(jiàn)過(guò)有人以為自己裝了 GPU 版結(jié)果torch.version.cuda輸出 None白折騰半天。5.2 第二層CUDA 是否真的可用print(torch.cuda.is_available()) print(torch.cuda.device_count()) print(torch.cuda.get_device_name(0))is_available()返回 True 才算 GPU 可用。如果返回 False即使你裝的是 GPU 版也用不了。常見(jiàn)原因有幾個(gè)驅(qū)動(dòng)版本太低、顯卡太老不支持當(dāng)前 CUDA、或者系統(tǒng)里有多個(gè) CUDA 版本沖突。device_count()返回可見(jiàn)的 GPU 數(shù)量。如果你有多張卡但這里只顯示一張可能是CUDA_VISIBLE_DEVICES環(huán)境變量限制了。get_device_name(0)返回第一張卡的型號(hào)確認(rèn)一下是不是你預(yù)期的那張。5.3 第三層實(shí)際跑一次 GPU 計(jì)算前面兩步都是查詢狀態(tài)真正要驗(yàn)證的是能不能在 GPU 上做計(jì)算。跑一段最小代碼import torch # 創(chuàng)建一個(gè)張量并移到 GPU x torch.randn(1000, 1000).cuda() y torch.randn(1000, 1000).cuda() # 做一次矩陣乘法 z torch.matmul(x, y) # 把結(jié)果移回 CPU 并打印 print(z.sum().item()) print(z.device)這段代碼做了三件事在 GPU 上創(chuàng)建張量、在 GPU 上做矩陣乘法、把結(jié)果移回 CPU。如果全部跑通且z.device輸出cuda:0說(shuō)明 GPU 計(jì)算鏈路是通的。為什么要在 GPU 上做矩陣乘法而不是簡(jiǎn)單加法因?yàn)榫仃嚦朔〞?huì)調(diào)用 cuBLAS 庫(kù)能驗(yàn)證 CUDA 的數(shù)學(xué)庫(kù)是否正常工作。加法可能只用到最基礎(chǔ)的 kernel驗(yàn)證不夠充分。5.4 第四層驗(yàn)證反向傳播如果你要用 PyTorch 訓(xùn)練模型還得驗(yàn)證自動(dòng)求導(dǎo)在 GPU 上是否正常import torch x torch.randn(10, 10, requires_gradTrue, devicecuda) y (x ** 2).sum() y.backward() print(x.grad.device) print(x.grad.shape)這段代碼驗(yàn)證了 GPU 上的反向傳播。如果x.grad能正常計(jì)算出來(lái)且 device 是 cuda說(shuō)明訓(xùn)練所需的核心功能都正常。5.5 一個(gè)完整的驗(yàn)證腳本把上面幾層整合成一個(gè)腳本每次裝完新環(huán)境跑一遍import torch def verify_pytorch(): print(fPyTorch version: {torch.__version__}) print(fCUDA version: {torch.version.cuda}) print(fCUDA available: {torch.cuda.is_available()}) if torch.cuda.is_available(): print(fDevice count: {torch.cuda.device_count()}) print(fDevice name: {torch.cuda.get_device_name(0)}) # GPU 計(jì)算測(cè)試 x torch.randn(1000, 1000, devicecuda) y torch.randn(1000, 1000, devicecuda) z torch.matmul(x, y) print(fMatmul result device: {z.device}) # 反向傳播測(cè)試 a torch.randn(10, 10, requires_gradTrue, devicecuda) b (a ** 2).sum() b.backward() print(fGradient device: {a.grad.device}) print(All GPU checks passed.) else: print(CUDA not available, running on CPU only.) if __name__ __main__: verify_pytorch()這個(gè)腳本我放在每個(gè)新環(huán)境的根目錄裝完就跑一次幾秒鐘的事能省下后面大量排查時(shí)間。6. 那些年我踩過(guò)的安裝坑和排查思路前面講的是正確流程但現(xiàn)實(shí)中你更可能遇到的是已經(jīng)出問(wèn)題了怎么辦。這一節(jié)我把遇到過(guò)的典型問(wèn)題和排查鏈路整理出來(lái)你可以對(duì)照自己的報(bào)錯(cuò)找線索。6.1 報(bào)錯(cuò) CUDA driver version is insufficient這個(gè)報(bào)錯(cuò)的意思是你裝的 PyTorch 需要的 CUDA 運(yùn)行時(shí)版本高于你驅(qū)動(dòng)支持的版本。比如你裝了 cu121 的 PyTorch但驅(qū)動(dòng)只支持到 CUDA 11.8。排查步驟先nvidia-smi看驅(qū)動(dòng)支持的 CUDA 上限再python -c import torch; print(torch.version.cuda)看 PyTorch 需要的版本。如果前者小于后者就是這個(gè)問(wèn)題。解決辦法有兩個(gè)升級(jí)顯卡驅(qū)動(dòng)或者重裝一個(gè)低 CUDA 版本的 PyTorch。升級(jí)驅(qū)動(dòng)通常更簡(jiǎn)單去 NVIDIA 官網(wǎng)下載對(duì)應(yīng)型號(hào)的最新驅(qū)動(dòng)裝上就行。但如果是服務(wù)器升級(jí)驅(qū)動(dòng)可能需要重啟要挑個(gè)合適的時(shí)間。6.2 報(bào)錯(cuò) ImportError: libcudart.so.11.0: cannot open shared object file這是 Linux 上常見(jiàn)的問(wèn)題說(shuō)明系統(tǒng)找不到 CUDA 運(yùn)行時(shí)庫(kù)。可能的原因PyTorch 裝的是 GPU 版但系統(tǒng)里沒(méi)有對(duì)應(yīng)的 CUDA 庫(kù)而 PyTorch 又沒(méi)能用自帶的。等等前面不是說(shuō) PyTorch 自帶 CUDA 運(yùn)行時(shí)嗎是的但有些情況下它會(huì)去系統(tǒng)路徑找。比如你用 conda 裝的時(shí)候conda 可能裝了一個(gè)系統(tǒng)級(jí)的 CUDA 庫(kù)然后 PyTorch 去鏈接它結(jié)果版本對(duì)不上。排查方法ldd命令查看 torch 的動(dòng)態(tài)庫(kù)依賴ldd $(python -c import torch; print(torch.__file__)) | grep cuda如果看到某些 cuda 庫(kù)顯示 not found就是這個(gè)問(wèn)題。解決辦法通常是重裝 PyTorch確保用 pip 而不是 conda或者清理掉系統(tǒng)里沖突的 CUDA 庫(kù)。6.3 裝完 import 很慢或者卡住有時(shí)候import torch要等十幾秒甚至更久。這通常不是安裝問(wèn)題而是 PyTorch 在初始化時(shí)掃描 CUDA 設(shè)備、加載庫(kù)。如果機(jī)器上有多個(gè) CUDA 版本或者網(wǎng)絡(luò)文件系統(tǒng)慢會(huì)更明顯。一個(gè)緩解辦法是設(shè)置環(huán)境變量CUDA_MODULE_LOADINGLAZY讓 CUDA 模塊延遲加載。另一個(gè)辦法是確認(rèn)沒(méi)有多個(gè) CUDA 版本在 PATH 里打架。如果 import 直接卡死不動(dòng)可能是顯卡驅(qū)動(dòng)和 PyTorch 版本不兼容或者有其他進(jìn)程占用了 GPU。先nvidia-smi看看有沒(méi)有僵尸進(jìn)程占著顯存。6.4 Windows 上的特有問(wèn)題Windows 上裝 PyTorch 有幾個(gè)額外的坑。第一是路徑里有中文或空格可能導(dǎo)致某些庫(kù)加載失敗。建議把 Python 環(huán)境和項(xiàng)目都放在純英文、無(wú)空格的路徑下。第二是多個(gè) Python 版本共存。Windows 上可能同時(shí)裝了 Python 3.9、3.10、3.11你pip install裝到了 A 版本但運(yùn)行時(shí)用的是 B 版本。解決辦法是用python -m pip install而不是直接pip install確保裝到當(dāng)前python對(duì)應(yīng)的環(huán)境里。第三是驅(qū)動(dòng)簽名問(wèn)題。有些情況下 Windows 會(huì)攔截未簽名的驅(qū)動(dòng)導(dǎo)致 GPU 不可用。這個(gè)在正規(guī)渠道下載的 NVIDIA 驅(qū)動(dòng)上很少見(jiàn)但如果遇到了需要調(diào)整系統(tǒng)的驅(qū)動(dòng)簽名策略。6.5 排查問(wèn)題的通用思路遇到任何安裝問(wèn)題按這個(gè)順序排查確認(rèn)版本python --version、pip --version、nvidia-smi、torch.__version__把四個(gè)版本都打出來(lái)。確認(rèn)環(huán)境which pythonLinux或where pythonWindows確認(rèn)你操作的是哪個(gè) Python。確認(rèn)安裝位置python -c import torch; print(torch.__file__)看 torch 是從哪加載的?？赐暾麍?bào)錯(cuò)不要只看最后一行往上翻通常真正的錯(cuò)誤信息在前面。搜索報(bào)錯(cuò)關(guān)鍵詞把報(bào)錯(cuò)的核心句子去掉路徑和變量名拿去搜通常能找到遇到同樣問(wèn)題的人。這個(gè)順序的核心邏輯是先確認(rèn)事實(shí)再猜測(cè)原因。很多人一看到報(bào)錯(cuò)就開(kāi)始瞎試試了半小時(shí)才發(fā)現(xiàn)自己一直在錯(cuò)誤的 Python 環(huán)境里操作。7. 多版本共存和項(xiàng)目隔離的實(shí)戰(zhàn)建議如果你同時(shí)維護(hù)多個(gè)項(xiàng)目它們可能依賴不同版本的 PyTorch。這時(shí)候怎么管理7.1 一個(gè)項(xiàng)目一個(gè)環(huán)境最穩(wěn)妥的做法是每個(gè)項(xiàng)目一個(gè)獨(dú)立環(huán)境。用 venv 的話cd project_a python -m venv .venv source .venv/bin/activate # Linux/macOS pip install torch2.1.0 cd ../project_b python -m venv .venv source .venv/bin/activate pip install torch2.4.0每個(gè)項(xiàng)目的依賴記錄在requirements.txt里換機(jī)器時(shí)重建環(huán)境就行。這個(gè)做法看起來(lái)笨但最不容易出問(wèn)題。7.2 用 requirements.txt 鎖定版本requirements.txt里不要只寫(xiě)torch要寫(xiě)具體版本torch2.4.0 torchvision0.19.0 torchaudio2.4.0如果用了 CUDA 特定版本還要在安裝時(shí)指定索引。可以在 requirements 文件里加一行--index-url https://download.pytorch.org/whl/cu121 torch2.4.0這樣pip install -r requirements.txt就會(huì)從正確的索引裝正確的版本。7.3 導(dǎo)出和復(fù)現(xiàn)環(huán)境裝好一個(gè)能用的環(huán)境后導(dǎo)出完整依賴列表pip freeze requirements_lock.txt這個(gè)文件記錄了所有包的精確版本包括間接依賴。換機(jī)器時(shí)用這個(gè)文件重建能最大程度復(fù)現(xiàn)原環(huán)境。注意pip freeze會(huì)導(dǎo)出所有包包括你不需要的可以手動(dòng)清理一下。7.4 關(guān)于 Docker 的一點(diǎn)建議如果你的項(xiàng)目要部署到服務(wù)器或者需要嚴(yán)格的環(huán)境一致性用 Docker 是最省心的。PyTorch 官方提供了各種版本的鏡像直接FROM pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime就行。Docker 的好處是環(huán)境完全隔離不會(huì)和宿主機(jī)沖突。壞處是需要 GPU 支持時(shí)要裝 nvidia-container-toolkit多一層配置。如果你只是本地開(kāi)發(fā)用 venv 就夠了如果要部署Docker 值得投入時(shí)間學(xué)一下。8. 驗(yàn)證通過(guò)之后下一步做什么裝完、驗(yàn)證通過(guò)只是萬(wàn)里長(zhǎng)征第一步。接下來(lái)你大概率要做這幾件事我順帶說(shuō)幾個(gè)容易踩的點(diǎn)。第一件事是確認(rèn)你的數(shù)據(jù)能正常加載到 GPU。很多人驗(yàn)證時(shí)用的是隨機(jī)張量真到加載數(shù)據(jù)集時(shí)發(fā)現(xiàn) DataLoader 的num_workers設(shè)置不對(duì)或者 pin_memory 沒(méi)開(kāi)導(dǎo)致 GPU 利用率上不去。這些是性能問(wèn)題不是安裝問(wèn)題但裝完就該順手檢查。第二件事是確認(rèn)混合精度訓(xùn)練能用。如果你打算用torch.cuda.amp裝完可以跑個(gè)小例子驗(yàn)證一下from torch.cuda.amp import autocast, GradScaler scaler GradScaler() with autocast(): # 你的前向計(jì)算 pass如果這里報(bào)錯(cuò)可能是 PyTorch 版本和 CUDA 版本不匹配或者顯卡太老不支持。第三件事是記錄下你的環(huán)境信息。把torch.__version__、torch.version.cuda、nvidia-smi的輸出存一份以后出問(wèn)題時(shí)對(duì)比用。我習(xí)慣在項(xiàng)目根目錄放一個(gè)env_info.txt記錄這些信息團(tuán)隊(duì)協(xié)作時(shí)特別有用。最后分享一個(gè)我自己的習(xí)慣每次裝完新環(huán)境除了跑驗(yàn)證腳本我還會(huì)跑一個(gè)最小的訓(xùn)練循環(huán)用真實(shí)的數(shù)據(jù)集比如 MNIST訓(xùn)練幾個(gè) epoch確認(rèn)整個(gè)鏈路——數(shù)據(jù)加載、前向、反向、優(yōu)化器更新、驗(yàn)證——都正常。這個(gè)測(cè)試大概兩分鐘但能發(fā)現(xiàn)很多import torch發(fā)現(xiàn)不了的問(wèn)題。裝環(huán)境這件事多花十分鐘驗(yàn)證能省下后面幾小時(shí)的排查。