修復 GPU 模型在更換伺服器環境後無法運行的問題

你重構了一部分基礎設施，把工作負載遷移到日本機房的一台新的 GPU 伺服器或者一台新的 日本伺服器 上，按下執行……然後模型直接掛掉。程式碼沒改，倉庫還是同一個，但到處都是 CUDA 錯誤與缺失的函式庫。如果這聽起來像典型的 GPU 伺服器環境遷移問題，那這篇指南就是為你準備的。

1. 當你「只是換了一台伺服器」時，哪些東西真的變了

從開發者視角來看，你可能只是換了一個 IP，改了一個 SSH 目標。從整個技術棧的視角來看，你可能已經更換了：GPU 架構、NVIDIA 驅動版本、CUDA 工具包、Linux 發行版、核心、Python 建置版本，甚至是細微的 glibc 差異。任何一個環節的變化，都足以讓原本穩定的深度學習環境瞬間崩盤。

• 新的 GPU 世代：你的舊機器可能是 V100，而新的日本 GPU 伺服器租用方案給你的是 A100 或 RTX 4090。
• 新的系統映像檔：舊環境是 Ubuntu 18.04，新環境是 22.04，預設函式庫和系統行為都有所變化。
• 不同的部署棧：之前是裸機部署，現在全部切到 Docker 或由 Kubernetes 管理。
• 網路拓撲變化：遷移到日本區域後，模型和資料集的下載來源可能發生改變，逾時與 DNS 行為也都會跟著變。

與其反覆「重裝碰運氣」，不如把這個問題當成正規的除錯流程：從硬體到 Python 程式碼逐層驗證，逐層鎖定到底是哪裡發生了變化。

2. 建立心智模型：把 GPU 技術棧按層拆開看

在排查遷移之後詭異的執行時錯誤時，要學會分層思考。如果底層某一層出問題，上層再乾淨的程式碼也會表現得一團糟。

1. 硬體層：實體 GPU、PCIe 拓撲、電源、散熱。
2. 主機 OS + 驅動層：核心、NVIDIA 驅動、主機上的 CUDA runtime。
3. 容器 / 虛擬化層：Docker、nvidia-container-toolkit、虛擬化設定。
4. 語言執行階段層：Python 版本、Conda / virtualenv。
5. 框架層：PyTorch、TensorFlow、JAX、MXNet 以及各自編譯綁定的 CUDA。
6. 應用層：你的訓練 / 推論程式碼、設定、環境變數。

除錯策略很簡單：從最底層開始往上排查，永遠不要因為「之前在舊伺服器上沒問題」就武斷地認為某一層一定是正常的。

3. 先確認：新機器上的 GPU 真的還活著嗎

在和 CUDA 吵架之前，先確保硬體是可見而且健康的。SSH 登入日本節點，先跑一些看起來很無聊的指令。

• nvidia-smi：你能看到所有顯示卡嗎？型號正確嗎？閒置狀態下溫度和功耗是否合理？
• lspci | grep -i nvidia：確認 PCIe 裝置是否存在，在驅動有問題、nvidia-smi 跑不起來時特別有用。
• dmesg | grep -i nvidia：查看驅動載入問題、ECC 錯誤或重啟後的 PCIe 問題。

此階段的一些紅色信號：

• nvidia-smi 中完全看不到 GPU。
• 出現「no devices were found」之類的錯誤。
• GPU 數量明顯少於你在伺服器租用或伺服器託管方案中實際購買的數量。

如果硬體層已經不對勁，在動軟體棧之前，先聯絡你的日本 GPU 伺服器租用服務商或機房。壞掉的 PCIe 通道、損壞的顯示卡、接線錯誤的轉接板，這些都不是透過 pip 能解決的問題。

4. 驅動和 CUDA 的現實檢查

大部分遷移後的模型故障，本質上都是某種形式的驅動與 CUDA 不相容。驅動裝在主機上，而 Python 或容器中的框架是針對特定 CUDA runtime 編譯的。

先做一個快速基線檢查：

• nvidia-smi 會顯示驅動版本以及暴露出來的 CUDA runtime 版本。
• nvcc --version（如果安裝了）會顯示 CUDA toolkit 版本，這個可能和 runtime 不同。
• 在 Python 裡執行：
  • import torch; print(torch.version.cuda)
  • import tensorflow as tf; print(tf.__version__)

你需要一個被官方支援的「版本三角」：

1. NVIDIA 驅動版本。
2. nvidia-smi 報告的 CUDA runtime 版本。
3. 框架建置（PyTorch / TF）及其編譯時所綁定的 CUDA 版本。

如果你在新伺服器上「重新裝了一遍環境順手全都升到最新版」，那這個三角很可能已經和舊環境完全對不上號了。為 CUDA 11.3 建置的模型輪子，在一個只暴露 CUDA 12.2 的主機上（又沒有合適的相容層）大多數情況是跑不動的。

5. 把舊環境抓緊：遷移前先做快照

如果你的遷移還沒開始，最專業的做法就是先凍結當前環境。如果已經遷移完畢，那就盡可能透過日誌和設定把舊環境還原出來。

• 匯出 Conda 環境：
  • conda env export > env-old.yaml
• 記錄 pip 相依：
  • pip freeze > requirements-old.txt
• 記下 OS 和核心：
  • lsb_release -a，uname -r
• 記錄 GPU 和驅動資訊：
  • 儲存舊環境下 nvidia-smi 的完整輸出。

在日本的新伺服器上，盡量忠實地重放這些資訊，而不是「順手升級一波」。你離原環境越近，遷移中踩到的邊角坑就越少。

6. Python 版本與虛擬環境的地雷

最容易被忽視的一種失敗模式是：程式碼在你本機和舊伺服器上的 Python 3.8 跑得好好的，新 GPU 伺服器預設切到了 3.11，於是各種相依錯誤和編譯問題紛紛冒出來。

1. 確認直譯器：
   • 執行 python --version 或 python3 --version。
   • 確認真正排在 $PATH 最前面的到底是哪個 Python 可執行檔。
2. 檢查虛擬環境：
   • Conda 環境：conda env list，然後 conda activate your-env。
   • virtualenv：使用對應的 bin/activate 指令稿進行啟用。
3. 不要依賴系統 Python：
   • 為每個專案明確指定 Python 版本。如果你的建置是 3.9，就裝 3.9，而不是隨機。

如果你使用的是日本機房的預裝映像檔或某種平台服務，它們通常會預裝多個 Python 版本。把 GPU 版 PyTorch 裝進了錯誤的直譯器，是一種非常常見的遷移坑：看起來像是「GPU 不見了」，本質卻是你用的是 CPU-only 的輪子。

7. 框架層除錯：PyTorch、TensorFlow、JAX

當驅動和直譯器確認無誤之後，接下來就要載入框架，問問它對當前 GPU 狀態的看法。一定要在應用實際使用的環境裡執行（同一個 venv 或 Conda 環境、同一個容器）。

• PyTorch：
  • torch.cuda.is_available() 應該回傳 True。
  • torch.cuda.get_device_name(0) 應該顯示你在日本節點上的真實 GPU 型號。
• TensorFlow：
  • tf.config.list_physical_devices('GPU') 應該列出所有可見的 GPU。
• JAX：
  • jax.devices() 應該能看到 GPU（或相關 TPU）。

遷移後在框架層常見的問題包括：

• 不小心安裝了 CPU-only 版本覆蓋了 GPU 版本。
• 系統中存在多個 CUDA 版本，連結器選了錯的那一個。
• 舊的已編譯擴充套件與當前 ABI 不再相容。

如果匯入框架時出現包含 CUDA、cuDNN 或 libcudart 的錯誤訊息，先確認你安裝的版本是否明確被 GPU 和驅動文件支援，並且和伺服器租用或伺服器託管提供商當前在跑的版本是相容的。

8. 容器、編排系統與「看不見的主機」

在許多日本地區的 GPU 伺服器租用平台上，容器已經是預設部署方式。這會引入額外一層：主機配置完美，但容器內部完全看不到 GPU。

1. 檢查 Docker runtime：
   • 使用 --gpus all 或在預設 runtime 中設定 nvidia。
   • 執行 docker run --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi 驗證 GPU 透傳是否正常。
2. 確認 nvidia-container-toolkit：
   • 如果主機上的 nvidia-smi 正常，而容器裡失敗，多半是 toolkit 設定問題。
3. 警惕驅動「混搭」：
   • 不要在映像檔裡再打包一套與主機衝突的驅動，顯示卡驅動應該完全由主機接管。

如果你用的是 Kubernetes 或託管平台，記得確認日本區域的 GPU 節點池是否正確向 Pod 暴露了裝置，並且 Pod 資源請求寫對了。一個 YAML 拼寫錯誤，有時會偽裝成「深度框架內部 bug」。

9. 系統函式庫與原生相依的伏擊

即使 CUDA 和框架都正常運作，原生系統函式庫也會在遷移後暗中出手。不同 Linux 發行版和版本對系統函式庫的打包名稱、路徑、版本可能完全不同。

• 典型症狀：OSError: libXYZ.so.6: cannot open shared object file。
• 常見原因：系統套件沒有安裝，或者函式庫版本不相容。
• 常見嫌疑對象：
  • OpenCV 及其相依（例如 libglib2.0）。
  • 影像編解碼函式庫如 libjpeg，影音相關函式庫如 ffmpeg。
  • blas/lapack、MKL 或 cuBLAS 等相關元件衝突。

在新伺服器上的排查策略：

1. 在做任何操作之前，先把完整的堆疊追蹤資訊讀一遍。
2. 對失敗的二進位檔或 Python 擴充套件使用 ldd，查看它期望連結哪些符號。
3. 用新系統對應的套件管理器安裝缺失的系統函式庫。

當你從本地機房遷移到日本機房的 GPU 伺服器託管時，也可能順帶從一個發行版家族切換到另一個（例如從 Debian 系到 RHEL 系）。這一變化本身，就足以讓你必須重新梳理一遍系統層級相依。

10. 模型檔案、路徑與權限

並不是所有的崩潰都是 CUDA 惹的禍。有時只是模型根本不在程式碼認為的位置，或者作業系統直接不讓你的行程碰那些檔案。

• 硬編碼路徑：很多遺留程式碼中寫死了只能在舊伺服器成立的絕對路徑。
• 相對路徑：在新機器上從不同的工作目錄啟動程式，會讓相對路徑的匯入和檔案查找徹底失效。
• 權限問題：在伺服器託管或共用伺服器租用環境中，uid/gid 對應關係發生變化，結果就是只有 root 能讀你的 checkpoint。

一個基礎檢查清單：

1. 每次程式碼開啟模型或資料集檔案時，都把完整路徑列印到日誌裡。
2. 在相關目錄下執行 ls -l，看看到底是誰在擁有和存取這些檔案。
3. 在多台機器之間對齊使用者與群組，尤其是把磁碟實體遷到新的日本伺服器託管機櫃時。

路徑和權限錯誤看起來「很低級」，卻非常耗時間——尤其是在你先入為主地認為「機房一換，檔案系統還是原來那一套」的情況下。

11. 網路、下載與「卡死在那裡」的場景

切換到日本區域之後，模型擷取外部資源的方式可能會發生根本變化。如果你的啟動流程需要從遠端倉庫或公共儲存桶下載權重，下載逾時或被限流，很可能會偽裝成「算力問題」。

• 你是不是每次啟動都要從 Hugging Face、PyPI 或某個 model zoo 擷取資源？
• 日本機房中的公司防火牆或資料中心防火牆是否封鎖了部分外部位址？
• DNS 是否解析到了和以往不同的鏡像，延遲非常大？

為了降低風險，你可以：

1. 把關鍵模型權重和資料集快取到 GPU 伺服器本機。
2. 在接近日本環境的位置建立製品倉庫，鏡像核心相依。
3. 讓所有外部下載行為都是顯性的、有清晰日誌和指數退避，而不是悄無聲息地「無限等待」。

如果程式在新機器上一再「卡死」，先檢查它是不是其實在等網路，而不是在等 GPU。

12. 一套實用、可重複的除錯流程

為了避免像無頭蒼蠅一樣亂試，把上面的內容整合成一套任何團隊成員都能照著執行的流程，每當模型在環境變更後拒絕運行時，就按這套流程來。

1. 基礎健康檢查：
   • 執行 nvidia-smi 和一個極簡 CUDA 範例，確認顯示卡本身沒問題。
2. 版本清單：
   • 記錄 OS、核心、驅動、CUDA runtime、Python 和框架版本。
3. 環境對比：
   • 把新環境和原生產環境逐項對比，先修補那些顯而易見的差異。
4. 最小重現：
   • 寫一個最小腳本來重現問題，不要帶複雜設定，也不要帶花式訓練器。
5. 升級路徑：
   • 如果你連單卡的玩具腳本都跑不通，就先別動多節點或多 GPU 叢集。

一旦這套流程被寫進文件，就把它分享給整個團隊，並把它作為今後所有環境遷移（無論是本地機房、雲區域還是日本 GPU 資料中心）的 Runbook 之一。

13. 面向日本機房的伺服器租用與伺服器託管注意事項

當你的 GPU 落地在日本時，在遷移前後會多出一些需要額外關注的旋鈕。這些更多是關於基礎設施與區域、服務商的互動，而不只是 CUDA 本身。

• 延遲感知的架構設計：
  • 如果你的使用者或資料湖還在其他區域，訓練和推論的端到端延遲可能會變高，從而影響你對預取和快取策略的設計。
• 頻寬與出網策略：
  • 有些日本 GPU 伺服器租用方案會限制出網頻寬或按 GiB 收費，持續從其他區域同步資料集可能會變成意料之外的大成本。
• 伺服器託管機房的供電與散熱上限：
  • 如果你自己採購高密度 GPU 伺服器放進日本伺服器託管機櫃，要提前核對機櫃的功率密度上限。被動限電往往會表現為效能忽高忽低。

把伺服器租用或伺服器託管服務商的文件當成技術棧的一部分，而不是「合約附件的小字」。當遷移出現異常時，掌握平台的真實能力邊界，有助於你區分「環境 Bug」與「基礎設施硬限制」。

14. 一個更穩定遷移的配置示例

為了更直觀，我們可以給出一個「已知穩定」的極簡配置大綱，方便你在遷移到日本或在日本區域內部遷移工作負載時，用作對照基線：

• OS：Ubuntu LTS（20.04 或 22.04），固定版本並及時打補丁。
• 驅動：明確被當前 GPU 世代和 CUDA toolkit 官方支援的版本。
• CUDA：每個節點只保留一個主版本，避免殘留半升級的工具包。
• Python：每個專案一個版本，有清晰的環境檔案並納入版本控制。
• 框架：鎖定具體版本的 PyTorch 或 TensorFlow，而不是盲目用 latest。

再寫一個短腳本，列印上述所有版本資訊以及 torch.cuda.is_available() 或你所用框架的等價檢查。把它納入每台新 GPU 伺服器上線後的檢查清單中，每次環境遷移之後先跑一遍。

15. 「人味內容」與反 AI 風格的自覺

越來越多的工程師會在意：他們正在讀的運維指南，看起來像是一個真的在機房熬過夜的人寫的，還是某種通用範本自動產生的。在 Pager 響個不停的時候，你當然只想看前一種內容。

• 避免那種從不提真實指令或錯誤訊息的空洞「三步法」口號。
• 多給出具體的探針（nvidia-smi、torch.cuda.is_available()、特定日誌片段），少給抽象空話。
• 保持一點點「有態度」：寫出你真踩過的坑，以及那些確實幫你省過時間的實戰技巧。

如果你的內部文件或對外 Runbook 看起來像是千篇一律的 AI 範本，工程師在壓力之下是很難信任它們的。反之，多嵌入一些真實的案例、典型的失敗模式以及可以直接複製進終端機的精簡指令，才更像是真人寫出來、可救火的內容。

16. 把技術棧「畫」出來

有時候，一張圖比一千行日誌更有用。哪怕是一張粗糙的草圖，把硬體、驅動、容器、框架和應用程式碼之間的關係畫出來，也能讓排障討論不至於太抽象。

每當你引入一種新環境——無論是新的日本區域、新的伺服器租用服務商，還是新的伺服器託管機櫃——都更新那張圖。它能防止團隊成員在實際上配置差異巨大的節點之間，想當然地假設「一切都一樣」。

17. 收尾：讓遷移重新變得「無聊」

如果遷移做得足夠好，它本該是無聊的。不會有凌晨三點的救火，不會有一整天炸鍋的 Slack 頻道，只是一份清單被悄悄地執行並通過驗證。本文從硬體、驅動、CUDA、容器、Python、框架、路徑到網路，一層一層拆開，把「神祕的 GPU 伺服器環境遷移問題」變成了一組有限而可驗證的排查任務，而不是一團黑盒。

下次你把模型遷移到日本的新 GPU 節點上，無論是透過標準的伺服器租用方案，還是透過重型 GPU 伺服器託管方案，都要把「環境」當作一等公民：為它做版本管理，為它寫文件，在預生產環境中演練遷移，並在宣佈遷移完成前跑過最小重現腳本。做到這一點，更換伺服器就不再是賭運氣，而只是一場可預期的工程實踐。