RTX 5090 跑 vLLM 要 CUDA 13.5 嗎?2026 環境排障
RTX 5090 上安裝 vLLM 時遇到 CUDA 錯誤,或模型載入後立即出現顯存不足?
先選與 vLLM 版本相符的官方建置,不要把 CUDA 13.5 當成 RTX 5090 的必要條件。截至 2026 年 9 月 30 日,NVIDIA 官方 CUDA 工具包歸檔列出的最新版本為 13.4.1;vLLM 官方安裝資料與發布頁列出的建置選項包括 CUDA 12.8、12.9 與 13.0,這些資料並未證實 RTX 5090 必須使用 CUDA 13.5。先核對驅動、PyTorch CUDA 後端、vLLM 建置與模型量化格式,再定位故障;不應僅憑參數量或 FP4 標示,認定單卡可以穩定推理任意大模型。
本文適合正準備在 RTX 5090 安裝或升級 vLLM、但不確定 CUDA 版本的開發者。
也適合正在嘗試大參數量或 FP4 模型,以及需要處理容器、PyTorch 與 CUDA 環境衝突的工程師和維運人員。
最後更新:2026 年 9 月 30 日;版本資訊依 NVIDIA CUDA 工具包歸檔、vLLM CUDA 安裝說明及官方發布頁核對。
RTX 5090 vLLM CUDA 13.5 的版本判斷
「CUDA 版本」容易被當成單一設定,實際上至少要分清楚幾個部分:GPU 驅動、宿主機或容器內的 CUDA 執行環境、PyTorch wheel 使用的 CUDA 後端,以及 vLLM 安裝套件或自行編譯時採用的版本。它們未必是同一個版本號,也不是只要安裝較新的 Toolkit,就能讓原有 wheel 自動相容。
NVIDIA 的 CUDA 相容性說明說明了 CUDA 與驅動之間的相容性條件;但這不代表所有 PyTorch wheel、vLLM 建置和 GPU 核心都會因此相容。判斷時應以實際使用的 vLLM 版本官方安裝說明為準,並確認相關套件的安裝來源與建置標籤。vLLM 的目前安裝指南也應與所選發布版本交叉核對,不宜把不同版本的安裝指令混用。
| 選項 | 適用條件 | 主要判斷點 |
|---|---|---|
| 官方列出的 wheel 或容器 | 目前 vLLM 版本明確提供對應建置,且 PyTorch 後端與驅動符合要求 | 優先依該版本安裝說明選擇,記下 wheel 或容器標籤;不要只看宿主機裝了哪版 Toolkit |
| 依官方文件自行編譯 | 必須使用文件未涵蓋的組合,或需要特定編譯選項 | 先確認編譯工具鏈、PyTorch 後端與 vLLM 版本一致;編譯成功不等於執行時每個算子都受支援 |
| 直接追升 CUDA 13.5 | 官方資料未確認它是目前 RTX 5090 的必要建置 | 不要把升級當作預設修復方式;若錯誤實際源自 wheel、驅動或套件混裝,升級可能掩蓋不了問題 |
RTX 5090 安裝 vLLM,應從哪個 CUDA 版本開始核對?先選定 vLLM 的目標版本,再依該版本的官方文件核實建置選項與安裝方式;截至上述核對日期,官方資料中可見 CUDA 12.8、12.9、13.0 等建置選項,並沒有據此確認 CUDA 13.5 是必要條件。不可將這份版本清單當成所有版本永久適用的相容性保證。
安裝與匯入錯誤的環境分流
安裝中斷、匯入擴充模組失敗,以及服務啟動後出現 CUDA 錯誤,表面上都像「CUDA 不支援」,但原因可能完全不同。先保存完整錯誤堆疊,再用以下檢查項目分類,不要先反覆重裝不同版本。
- [ ] 記錄執行邊界:確認命令是在宿主機、容器還是虛擬環境執行,並記下映像標籤或環境建立方式。
- [ ] 確認 GPU 與驅動可見性:檢查作業系統是否能識別 RTX 5090,以及容器執行時是否能存取 GPU。若 GPU 不可見,先處理驅動或容器裝置傳遞,不要從 vLLM 原始碼開始查。
- [ ] 記下 PyTorch CUDA 後端:保存 PyTorch 版本及其 CUDA 建置資訊,確認執行中的 Python 環境與安裝 vLLM 時使用的是同一個環境。
- [ ] 核對 vLLM 的安裝來源:記下套件版本、wheel 或容器標籤;若使用自行編譯版本,保留編譯命令與建置環境資訊。
- [ ] 只改一項變數再重測:例如先固定 vLLM 版本,只修正 PyTorch 後端;通過後才測試另一個建置選項。
編譯或匯入失敗時,怎樣區分 PyTorch 與 CUDA 不匹配?若 GPU 和驅動可用,但匯入擴充模組時出現符號或二進位相容性錯誤,優先比對 PyTorch wheel 與 vLLM 建置來源;若錯誤出現在 GPU 初始化或核心啟動階段,再核對驅動、容器可見性與該建置支援的 CUDA 組合。這是定位順序,不是僅憑一段錯誤訊息即可下定論。
FP4 載入錯誤的格式核驗
FP4 並非一個足以判定相容性的完整格式名稱。載入前先檢查模型卡、權重設定與量化工具鏈,確認模型標示的是哪一種 4-bit 浮點格式、採用何種轉換流程,以及所用 vLLM 版本是否支援對應檢查點和執行路徑。vLLM 的 NVFP4 格式選擇說明及 ModelOpt 檢查點支援資料可用來核對格式與支援條件。
NVFP4 這類 4-bit 浮點格式,不能與 INT4 整數量化視為同一種格式;「4-bit」只描述位寬,不能單獨證明格式、算子或模型權重能在目前後端執行。NVIDIA 對 RTX 5090 的官方規格列明其為 Blackwell 架構,配備 32 GB GDDR7。這是硬體規格,不等於可供模型權重獨占使用的顯存容量。
載入 FP4 模型報錯時,先檢查哪裡?依序確認權重實際格式與轉換來源、vLLM 版本對該格式的支援說明,以及錯誤發生在權重解析、算子建立還是生成階段。載入失敗、算子不支援與生成輸出異常是不同故障類型;即使模型成功載入,也仍要驗證輸出品質,不能只用載入結果宣稱量化可用。
Chunked Prefill 與顯存問題的分辨
Chunked Prefill 會影響提示詞處理和請求調度行為,但不能替代權重與 KV cache 的顯存預算。若啟用後才出現長提示詞錯誤或輸出異常,先做對照:在相同模型、輸入與其他啟動參數下,關閉或調整該功能再測試。每次僅改一項設定,避免同時更動批次大小、最大批處理 token 和並發數,導致無法判斷是哪項改動影響結果。
記錄每次測試的提示詞長度、並發請求、最大批處理 token 設定、錯誤位置及顯存狀態,並以正在使用的 vLLM 版本文件核對參數名稱與預設值。若關閉或調整 Chunked Prefill 後錯誤仍在,應轉查載入後顯存餘量、KV cache 配置和模型執行支援;若短提示詞正常、長提示詞才觸發,再集中測試長提示詞的排程路徑。
開啟 Chunked Prefill 後出現顯存不足或輸出異常,先排查什麼?先固定模型、輸入與其他啟動參數,做開啟與關閉的對照,再記錄提示詞長度、並發量和最大批處理 token。這項測試能幫助分辨調度路徑是否相關,但不能證明權重或 KV cache 已有足夠顯存。
單卡顯存邊界與模型規模
估算可否穩定推理時,應把權重、量化尺度、執行時工作區與 KV cache 分項處理,再用實際啟動和目標請求測試校正;只有理論估算時,必須明確標示量化方式、上下文長度及其他假設,不能將估算寫成實測占用。
尤其要避免把 MoE 的活躍參數量,當成需要常駐的權重規模。Meta 官方資料指出,Llama 4 Scout 是 109B 總參數、17B 活躍參數,Maverick 是 400B 總參數、17B 活躍參數;兩者不能籠統稱為同一個「120B 模型」。活躍參數描述每次處理所涉及的部分,不能直接用來推導完整權重是否能放入單張 GPU。相關模型規模與 MoE 說明可參閱 Meta 的 Llama 4 介紹。
因此,RTX 5090 的 32 GB 規格、權重標示的 FP4 位寬,以及某個 MoE 模型的活躍參數量,都不足以單獨判斷能否穩定推理。要驗收的不是「模型有沒有載入」而已,而是目標上下文、並發和請求模式下能否持續生成,且沒有因 KV cache 或執行時工作區而失敗。
建立可重現的排障紀錄
提交問題或交接給團隊前,整理以下資訊,才能讓別人重現,而不是只能猜測版本:
- [ ] GPU 型號、驅動版本,以及宿主機或容器的執行方式。
- [ ] PyTorch 版本與 CUDA 後端、vLLM 版本和安裝來源。
- [ ] 模型設定、量化格式、權重來源及相關轉換方式。
- [ ] 完整錯誤日誌、啟動參數,以及出錯時的顯存狀態。
- [ ] 分開記錄安裝通過、模型載入、短請求驗證與目標上下文測試的結果。
每次只調整一個因素,並留下調整前後的日誌;社群 issue 可提供調查線索,但單一個案不代表官方支援狀態,也不等同可重現結論。若問題只在特定模型或請求條件下出現,將該條件一併保存,避免把個別故障擴大解讀成所有 RTX 5090 的共通限制。
當本地 GPU 是主要推理節點時,版本組合的維護、顯存不足與測試環境干擾,都是實際成本;雲端 Mac 則不能取代 CUDA GPU,也不應被當成 RTX 5090 推理伺服器。若工作可拆成「本地 GPU 負責推理、Mac 環境處理程式編輯與非 CUDA 開發」,可先閱讀 KuzCloud 的使用說明,再到 KuzCloud 網站了解其服務,按實際工作流程評估是否需要租用 Mac。需要 CUDA 推理、長期固定重負載或實體 GPU 介面的工作,仍應保留本地 GPU 或合適的 GPU 環境;雲端 Mac 適合的是不依賴 CUDA 的開發環節。
GPU 排障之外,備妥專屬 Mac 開發環境
RTX 5090 與 vLLM 的 CUDA 測試可留在 GPU 環境進行;需要 macOS 工具鏈時,KuzCloud 提供 Apple M4 專屬實體 Mac mini。
透過 SSH 或瀏覽器 VNC 遠端連線,並以完整 root 權限安裝與管理開發工具。