境搭建與踩坑記錄)
一直覺得在 Windows 上跑大模型推理是一件很折騰的事。前陣子我拿到一臺帶 NVIDIA 顯卡的 Windows 筆記本想把它變成一臺能隨時(shí)調(diào)用的本地推理服務(wù)試了一圈方案最后老老實(shí)實(shí)回到 WSL 2 把 vLLM 完整裝了一遍。整個(gè)過程踩了不少坑但走通之后體驗(yàn)確實(shí)穩(wěn)定現(xiàn)在把一步步流程和教訓(xùn)完整整理出來給同樣想用 Windows WSL 2 部署 vLLM 的同學(xué)一條可以直接照抄的路。這篇內(nèi)容適合下面幾類人想在 Windows 機(jī)器上跑 vLLM 服務(wù)、本地開發(fā)大模型應(yīng)用、做模型效果驗(yàn)證或者單純想搞清楚 WSL 2 里 GPU 環(huán)境到底怎么配的。跟著這套流程走不需要你有很深的 Linux 經(jīng)驗(yàn)但至少要知道命令行基本操作。1. vLLM 為什么值得裝以及為什么 Windows 上必須走 WSL 2 這條路先把結(jié)論說在前面vLLM 是目前本地部署大模型時(shí)吞吐量表現(xiàn)最好的推理框架之一它最大的價(jià)值來自兩項(xiàng)設(shè)計(jì)——PagedAttention 顯存管理機(jī)制和 Continuous Batching 連續(xù)批處理策略。PagedAttention 的原理可以類比操作系統(tǒng)的虛擬內(nèi)存管理。傳統(tǒng)的推理框架在計(jì)算注意力時(shí)需要把完整的 KV Cache 放在連續(xù)顯存里模型一長、并發(fā)一高顯存碎片就出來了明明總量夠用卻報(bào) OOM。vLLM 把 KV Cache 切割成固定大小的塊類似內(nèi)存分頁可以零散存放并在計(jì)算時(shí)按索引取用顯存利用率明顯提升。加上它會在每個(gè) step 動態(tài)合并多個(gè)請求一起計(jì)算而不是等一個(gè)請求完整跑完再處理下一個(gè)GPU 的算力基本不會閑著。實(shí)際跑 Qwen2.5 系列模型時(shí)并發(fā)請求的吞吐量比樸素 Hugging Face transformers 實(shí)現(xiàn)高出數(shù)倍這一點(diǎn)在長文本、多路請求場景下體感特別明顯。那為什么 Windows 原生環(huán)境裝 vLLM 很難受vLLM 從設(shè)計(jì)上就是面向 Linux 的。它的安裝包依賴 CUDA 工具鏈的鏈接方式、Linux 的共享內(nèi)存機(jī)制、以及大量在 Linux 上默認(rèn)開啟的內(nèi)核級能力Windows 要么不支持要么行為不一致。而且官方 README 從沒承諾過原生 Windows 支持遇到編譯錯(cuò)誤基本屬于自己修非常痛苦。WSL 2 在這里的作用是提供一個(gè)與虛擬機(jī)類似的真實(shí) Linux 內(nèi)核但虛擬化開銷比傳統(tǒng)虛擬機(jī)低很多。對 vLLM 來說WSL 2 里的 Ubuntu 環(huán)境和一臺普通的 Linux 服務(wù)器幾乎沒區(qū)別可以正常訪問 GPU 驅(qū)動、使用共享內(nèi)存、跑 CUDA 程序。更重要的是WSL 2 的 GPU 透傳機(jī)制并不是把 GPU 完全模擬一遍而是通過宿主機(jī)驅(qū)動直接讓 Linux 側(cè)程序調(diào)用顯卡性能損耗可以忽略不計(jì)。我實(shí)測過同一模型在同硬件上跑 WSL 2 和原生 Ubuntu單請求延遲和并發(fā)吞吐都非常接近。所以結(jié)論是Windows 用戶跑 vLLMWSL 2 是當(dāng)前綜合考慮下最順的一條路。原生 Linux 雙啟動性能雖然更好但日常使用不方便虛擬機(jī)方案 GPU 透傳配置復(fù)雜且性能損耗明顯Docker Desktop 的 WSL 2 后端本質(zhì)上還是在 WSL 2 里跑不如直接在 WSL 2 里操作來得透明。2. WSL 2 安裝與系統(tǒng)資源配置把基礎(chǔ)打穩(wěn)2.1 安裝 WSL 2 并確認(rèn)版本在 Windows 11 或較新的 Windows 10 上安裝 WSL 2 比想象中簡單。以管理員身份打開 PowerShell執(zhí)行wsl --install這個(gè)命令會默認(rèn)安裝 Ubuntu 發(fā)行版并啟用 WSL 2 所需的 Windows 功能組件。如果是 Windows 10 的舊版本可能會需要手動開啟“適用于 Linux 的 Windows 子系統(tǒng)”和“虛擬機(jī)平臺”兩項(xiàng)功能然后重啟并安裝 WSL 2 內(nèi)核更新包。安裝完成后重啟系統(tǒng)首次啟動 Ubuntu 時(shí)會要求設(shè)置用戶名和密碼。用戶名會作為 Linux 下的默認(rèn)用戶比如我用的用戶名是will后續(xù)所有文件路徑都從這個(gè)用戶目錄展開。重啟后先確認(rèn)發(fā)行版跑的是 WSL 2在 PowerShell 里執(zhí)行wsl -l -v輸出里應(yīng)該能看到Ubuntu的 VERSION 列是2。如果還是 1執(zhí)行wsl --set-version Ubuntu 2這一步很重要。WSL 1 沒有真正的 Linux 內(nèi)核很多系統(tǒng)調(diào)用不兼容vLLM 跑不起來。2.2 用 .wslconfig 控制內(nèi)存、CPU 和交換分區(qū)WSL 2 默認(rèn)會吃掉宿主機(jī)一半的內(nèi)存這在跑大模型時(shí)經(jīng)常不夠用。vLLM 加載模型時(shí)需要較大的內(nèi)存來放權(quán)重、tokenizer 和運(yùn)行時(shí)數(shù)據(jù)同時(shí)還要給緩存留空間。默認(rèn)配置下經(jīng)常出現(xiàn)內(nèi)存不足導(dǎo)致進(jìn)程被殺。解決辦法是在 Windows 用戶目錄C:\Users\你的用戶名\下創(chuàng)建一個(gè).wslconfig文件例如我的配置[wsl2] memory16GB processors8 swap8GB localhostForwardingtruememory是 WSL 2 能使用的最大內(nèi)存我這里設(shè)置 16GBprocessors分配 8 核swap設(shè)置交換分區(qū)大小在內(nèi)存不夠時(shí)可以把部分?jǐn)?shù)據(jù)換到磁盤localhostForwardingtrue保證 Windows 側(cè)能通過localhost直接訪問 WSL 2 里啟動的服務(wù)這個(gè)開關(guān)默認(rèn)就是開啟的但顯式寫出來更安心。改完配置后需要重啟 WSL 2 才會生效wsl --shutdown然后重新進(jìn)入 Ubuntu?？梢杂胒ree -h檢查內(nèi)存是否生效。2.3 系統(tǒng)更新與基礎(chǔ)工具安裝進(jìn)入 Ubuntu 后先把系統(tǒng)包索引更新一遍sudo apt update sudo apt upgrade -y然后安裝后面的步驟一定會用到的工具sudo apt install -y python3-venv python3-pip curl gitUbuntu 22.04 和 24.04 都自帶 Python 3python3-venv 一定要裝后面創(chuàng)建虛擬環(huán)境依賴它。git 和 curl 主要用于下載模型腳本和測試接口。這里補(bǔ)充一個(gè)建議如果不是有特殊原因不要直接改系統(tǒng)的全局 Python 環(huán)境。vLLM 的依賴項(xiàng)很多包括特定版本的 PyTorch、transformers、tokenizers 等直接裝進(jìn)系統(tǒng)環(huán)境很容易和已有的包沖突。后面都基于 venv 用。3. WSL 2 里的 GPU 透傳與 CUDA 環(huán)境驗(yàn)證3.1 WSL 2 的 GPU 訪問機(jī)制WSL 2 支持 GPU 透傳但它的實(shí)現(xiàn)方式和 Docker GPU 直通不太一樣。在 WSL 2 里你不需要也不應(yīng)該在 Linux 側(cè)單獨(dú)安裝 NVIDIA 驅(qū)動。WSL 2 啟動時(shí)會自動把 Windows 宿主機(jī)已經(jīng)裝好的 NVIDIA 驅(qū)動映射到 Linux 側(cè)你在 WSL 里看到的 GPU 實(shí)際上是由 Windows 驅(qū)動管理的。所以在 Windows 宿主機(jī)上你需要先確認(rèn)已經(jīng)安裝了較新的 NVIDIA 驅(qū)動?？梢源蜷_ NVIDIA 控制面板或者直接運(yùn)行nvidia-smi確認(rèn)版本。我用的是 560 系列的驅(qū)動實(shí)測對 WSL 2 的 GPU 透傳支持很好。驅(qū)動太舊會導(dǎo)致 WSL 里nvidia-smi報(bào)錯(cuò)或者 CUDA 調(diào)用失敗。3.2 在 WSL 2 里驗(yàn)證 GPU 和 CUDA進(jìn)入 Ubuntu 終端直接運(yùn)行nvidia-smi重點(diǎn)看驅(qū)動的右上角版本信息。在 WSL 2 里如果顯示的是 Windows 宿主機(jī)的驅(qū)動版本說明 GPU 已經(jīng)成功透傳進(jìn)來了。比如我的輸出頂部寫著 “Driver Version: 566.03”這就是 Windows 宿主機(jī)驅(qū)動版本說明鏈路是通的。接下來驗(yàn)證 CUDA。vLLM 安裝時(shí)依賴 CUDA runtime這里有兩種選擇只使用 pip 安裝的 PyTorch 自帶的 CUDA 庫不裝系統(tǒng)級 CUDA Toolkit額外安裝 CUDA Toolkit包含 nvcc 編譯器等。如果只是跑 vLLM第一種就夠用了。但如果你之后想自己編譯 CUDA 擴(kuò)展、調(diào)試 kernel 或者跑一些需要 nvcc 的腳本建議順手裝一個(gè) CUDA Toolkit。官方推薦從 NVIDIA 官網(wǎng)裝但 Ubuntu 的 apt 源也可以雖然版本可能舊一些。我用的是在系統(tǒng)里安裝 CUDA Toolkit 12.4 版本用起來沒碰到兼容問題。裝好后驗(yàn)證nvcc --version如果只是想快速確認(rèn) PyTorch 能調(diào)用 GPU不需要急著裝完整 Toolkit。先創(chuàng)建虛擬環(huán)境后再裝 torch 驗(yàn)證也不晚。3.3 常見 GPU 驗(yàn)證失敗原因這里列舉我遇到過的兩個(gè)比較典型的問題。第一個(gè)是nvidia-smi報(bào) “command not found”。這種情況經(jīng)常發(fā)生在 WSL 剛裝完、還沒執(zhí)行過 Windows 側(cè)驅(qū)動更新的時(shí)候。在 Windows 宿主機(jī)上更新到最新 NVIDIA 驅(qū)動然后執(zhí)行wsl --shutdown重啟 WSL再進(jìn)來就能看到了。第二個(gè)是 PyTorch 能裝上但torch.cuda.is_available()返回 False。這個(gè)我之前排查了很久最后發(fā)現(xiàn)是 WSL 2 內(nèi)核版本太舊導(dǎo)致的。執(zhí)行wsl --update把 WSL 本身更新到最新版本就解決了。4. 創(chuàng)建 Python 虛擬環(huán)境并安裝 vLLM4.1 創(chuàng)建項(xiàng)目目錄與虛擬環(huán)境我比較習(xí)慣把所有模型相關(guān)的東西整理在一個(gè)固定目錄里便于管理。在 WSL 2 里執(zhí)行mkdir -p ~/projects/vllm-playground cd ~/projects/vllm-playground python3 -m venv vllm-env創(chuàng)建完成后激活source vllm-env/bin/activate看到終端行首出現(xiàn)(vllm-env)前綴就說明激活成功了。這個(gè)環(huán)境是獨(dú)立的一套 Python 解釋器和包管理空間所有安裝操作都隔離在這個(gè)目錄下不會污染系統(tǒng)環(huán)境。4.2 安裝 vLLM安裝 vLLM 本身只需要一條命令pip install vllm但這條命令的耗時(shí)和踩坑概率都不小。vLLM 依賴的 PyTorch 體積很大而且 pip 需要根據(jù)當(dāng)前平臺的 CUDA 版本決定下載哪一個(gè) wheel。在國內(nèi)網(wǎng)絡(luò)環(huán)境下建議把 pip 換成清華源或阿里源下載速度會快很多pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple安裝過程中 pip 會自動拉取匹配的 PyTorch 版本。常見的坑是 pip 默認(rèn)拉取的是 CPU 版 PyTorch導(dǎo)致 GPU 不可用。vLLM 的官方 wheel 會強(qiáng)制指定帶 CUDA 的 PyTorch 版本正常情況下不會裝錯(cuò)。裝上之后可以先確認(rèn)一下python -c import torch; print(torch.__version__, torch.cuda.is_available())輸出里應(yīng)該能看到torch 2.x.xcu12x這樣的版本號并且torch.cuda.is_available()是True。如果這里顯示 False請回到上一章排查驅(qū)動和 WSL 版本。如果網(wǎng)絡(luò)環(huán)境不好或者你想避免官方源下載過慢可以考慮先手動安裝 PyTorch 的 CUDA 版本pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124然后再裝 vLLM。vLLM 檢測到已有對應(yīng)版本的 PyTorch 就不會重復(fù)下載了。不過要注意vLLM 和 PyTorch 版本有對應(yīng)關(guān)系安裝時(shí)盡量選接近官方文檔要求的版本避免出現(xiàn)“不支持的組合”告警。4.3 檢查 vLLM 是否安裝成功還沒下載模型之前可以先用一個(gè)無模型的命令快速確認(rèn) vLLM 能正常導(dǎo)入python -c from vllm import LLM; print(vLLM import success)這一步主要檢查動態(tài)鏈接庫是否完整。vLLM 包含一些編譯好的 CUDA kernel導(dǎo)入時(shí)如果缺少依賴比如libcudnn.so或者libnccl.so會直接報(bào)ImportError。我在第一次裝的時(shí)候遇到過libcublas.so.12: cannot open shared object file這個(gè)報(bào)錯(cuò)原因是我用 apt 裝過一個(gè)舊版 CUDA系統(tǒng)里的庫路徑被覆蓋了。解決辦法是把虛擬環(huán)境里的site-packages下 vLLM 依賴的nvidia/cublas庫路徑加到LD_LIBRARY_PATHexport LD_LIBRARY_PATH$VIRTUAL_ENV/lib/python3.10/site-packages/nvidia/cublas/lib:$LD_LIBRARY_PATH如果想每次進(jìn)入環(huán)境自動生效可以把這個(gè) export 寫到~/projects/vllm-playground/vllm-env/bin/activate文件的末尾。4.4 關(guān)于 Python 版本的選擇vLLM 對 Python 版本有明確要求舊版本不支持太新的 Python新版本對舊 Python 也有最低限制。官方安裝文檔會列出支持的 Python 版本范圍。以 Ubuntu 22.04 自帶的 Python 3.10 為例配合較新版本的 vLLM 是沒問題的。如果你用的是 Ubuntu 24.04 自帶 Python 3.12需要確認(rèn)你安裝的 vLLM 版本是否支持 3.12不支持的話用update-alternatives切換 Python 版本或者在創(chuàng)建 venv 時(shí)顯式指定python3.10 -m venv vllm-env需要注意Ubuntu 24.04 默認(rèn)可能沒有安裝 python3.10需要從 deadsnakes PPA 或者源碼安裝。這部分操作比較啰嗦我建議新手直接用 Ubuntu 22.04省去一堆兼容性問題。5. 模型下載與目錄規(guī)劃5.1 選模型顯存匹配是第一優(yōu)先級vLLM 能跑的模型很多包括 LLaMA、Qwen、Mistral、Gemma 等。選模型的第一步不是看能力而是看你的顯卡顯存。權(quán)重加載需要顯存KV Cache 也需要顯存而且 KV Cache 往往是大頭。這里列出我實(shí)測時(shí)常見的顯存匹配關(guān)系GPU 顯存推薦模型示例說明8GBQwen2.5-1.5B-Instruct / Qwen2.5-3B-Instruct直接跑max_model_len 不要開太大12GBQwen2.5-7B-Instruct / Llama-3.1-8B量化7B 全精度比較緊張需要調(diào)低 max_model_len16GBQwen2.5-7B-Instruct比較舒服可以開 8192 上下文24GBQwen2.5-14B-Instruct / 32B 量化14B 全精度能跑上下文長度適中40GBQwen2.5-72B 量化 / 開源大模型基本能嘗試各種模型如果顯存不滿足模型需求vLLM 啟動時(shí)會報(bào) OOM 或者直接退出。你可以通過降低--max-model-len參數(shù)來縮小 KV Cache 占用但模型權(quán)重占用的顯存是固定的低于權(quán)重需求就沒法跑。5.2 下載模型ModelScope 鏡像更穩(wěn)模型下載方式主要有兩個(gè)來源Hugging Face 和 ModelScope。Hugging Face 是全球最大的模型倉庫但國內(nèi)網(wǎng)絡(luò)訪問不穩(wěn)定。ModelScope 是國內(nèi)平臺下載速度通常更快而且 vLLM 官方支持通過環(huán)境變量直接使用 ModelScope。我這邊推薦的做法是優(yōu)先從 ModelScope 下載因?yàn)樗俣瓤臁⒕W(wǎng)絡(luò)穩(wěn)定。步驟如下pip install modelscope然后下載模型拿 Qwen2.5-7B-Instruct 舉例modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ~/models/qwen2.5-7b-instruct這個(gè)命令會把模型的權(quán)重、配置文件、tokenizer 等全部下載到~/models/qwen2.5-7b-instruct目錄下。下載速度取決于網(wǎng)絡(luò)Qwen2.5-7B 的權(quán)重文件大約 15GBModelScope 一般拉滿帶寬比 Hugging Face 快不少。如果你已經(jīng)下載了 Hugging Face 格式的模型vLLM 能直接使用。關(guān)鍵是記住模型目錄的絕對路徑比如~/models/qwen2.5-7b-instruct。5.3 模型存放位置不要放 /mnt/c這是我在實(shí)際使用中踩過的大坑。WSL 2 訪問 Windows 文件系統(tǒng)也就是/mnt/c下的路徑走的是 9P 協(xié)議讀寫速率比 WSL 內(nèi)部的 ext4 文件系統(tǒng)慢得多。把十幾個(gè) GB 的模型文件放在C:\models之類的位置vLLM 加載權(quán)重時(shí)需要從 /mnt/c 遷到內(nèi)存那個(gè)速度簡直讓人懷疑人生。我曾經(jīng)實(shí)測過同一個(gè)模型放在 /mnt/c 和放在 ~/models 下的加載時(shí)間差異前者慢了近 5 倍。所以模型優(yōu)先放在 WSL 2 內(nèi)部的 Linux 文件系統(tǒng)里。如果擔(dān)心 WSL 磁盤占用太大可以在下載前規(guī)劃好空間用df -h檢查。模型很占空間刪掉要謹(jǐn)慎。5.4 配置環(huán)境變量為了讓 vLLM 正確找到模型常用兩種方式在啟動命令里直接傳模型路徑設(shè)置HF_HOME環(huán)境變量指向你存放模型緩存的目錄。我習(xí)慣在~/.bashrc里追加export HF_HOME~/models export VLLM_USE_MODELSCOPEtrueVLLM_USE_MODELSCOPEtrue表示當(dāng) vLLM 在模型加載時(shí)找不到本地模型、需要去線上找時(shí)優(yōu)先走 ModelScope 而非 Hugging Face。這對國內(nèi)用戶非常友好。設(shè)置完后source ~/.bashrc6. 離線推理驗(yàn)證與 OpenAI 兼容 API 服務(wù)啟動6.1 用 Python 腳本做離線推理測試安裝完成且模型下載好之后先用一個(gè)簡單的 Python 腳本驗(yàn)證整個(gè)鏈路。創(chuàng)建一個(gè)test_infer.pyfrom vllm import LLM, SamplingParams llm LLM(model~/models/qwen2.5-7b-instruct, max_model_len8192) params SamplingParams(temperature0.7, top_p0.8, max_tokens512) prompts [ 用一句話介紹 WSL 2, 寫一段 Python 代碼實(shí)現(xiàn)快速排序 ] outputs llm.generate(prompts, params) for output in outputs: prompt output.prompt generated_text output.outputs[0].text print(fPrompt: {prompt}) print(fGenerated: {generated_text}) print(- * 50)運(yùn)行python test_infer.py第一次執(zhí)行時(shí)vLLM 會做 CUDA kernel 預(yù)熱和模型加載耗時(shí)可能比較長屏幕上會打印類似Starting vLLM using 1 GPUs和Loading model weights took ... GB的信息。這一步正常輸出就說明安裝沒白費(fèi)。如果這里報(bào)錯(cuò)重點(diǎn)看是不是模型路徑不對、顯存不足、或者 CUDA 驅(qū)動版本過舊。6.2 啟動 OpenAI 兼容 API 服務(wù)vLLM 最常用的場景之一是啟動一個(gè) OpenAI 兼容的 HTTP 服務(wù)這樣你本地的任何 OpenAI SDK 或者工具都可以直接把 base_url 指過去。啟動命令vllm serve ~/models/qwen2.5-7b-instruct --host 0.0.0.0 --port 8000參數(shù)說明--host 0.0.0.0監(jiān)聽所有網(wǎng)卡包括 WSL 2 的虛擬網(wǎng)卡--port 8000服務(wù)端口如果需要降低顯存占用可以加上--max-model-len 4096。啟動成功后在 Windows 宿主機(jī)瀏覽器直接訪問http://localhost:8000/v1/models會看到 JSON 格式的模型列表。這就是很典型的驗(yàn)證接口是否正常的方式。如果想從命令行測試對話可以用 curlcurl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: ~/models/qwen2.5-7b-instruct, messages: [{role: user, content: 你好}], max_tokens: 128}返回內(nèi)容里會包含choices字段里面的message.content就是模型生成的回復(fù)。從 Windows 側(cè)訪問localhost:8000能通是因?yàn)?WSL 2 默認(rèn)開啟了 localhost 轉(zhuǎn)發(fā)。如果你的 Windows 10 版本較舊可能需要手動在 PowerShell 里用netsh interface portproxy做端口映射把 Windows 的 8000 端口轉(zhuǎn)發(fā)到 WSL 2 的虛擬 IP 上。不過一般情況下默認(rèn)配置已經(jīng)夠用了。6.3 寫一個(gè)小工具腳本提升體驗(yàn)為了提高后續(xù)使用效率我給 API 服務(wù)封裝了一個(gè)簡單的對話腳本放在chat.py里from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) response client.chat.completions.create( model~/models/qwen2.5-7b-instruct, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)需要先pip install openai。用這個(gè)腳本可以快速測試服務(wù)是否在正常工作比 curl 直觀很多。這套 API 兼容性的好處是你可以直接在本地把 base_url 換成 vLLM 服務(wù)地址然后繼續(xù)用 LangChain、Dify 或者其他框架而不改代碼。7. 實(shí)測中的十大坑與調(diào)優(yōu)經(jīng)驗(yàn)整個(gè)流程走下來我踩了不少問題這里集中記錄一下很多問題不裝到那時(shí)候根本想不到。7.1 共享內(nèi)存不足導(dǎo)致進(jìn)程崩潰vLLM 在多并發(fā)或處理長上下文時(shí)tokenizer 和調(diào)度器會在共享內(nèi)存里臨時(shí)放數(shù)據(jù)。WSL 2 里/dev/shm的默認(rèn)大小是物理內(nèi)存的一半如果內(nèi)存不夠大服務(wù)運(yùn)行一段時(shí)間后可能直接報(bào)錯(cuò)RuntimeError: Shared memory area is too small排查方式df -h /dev/shm如果 Size 很小可以臨時(shí)擴(kuò)容sudo mount -o remount,size32G /dev/shm這條命令只在當(dāng)前會話生效重啟后會恢復(fù)默認(rèn)。要持久化的話可以在/etc/fstab里加一條配置但更簡單的做法是把這條命令放在啟動腳本里。我當(dāng)時(shí)直接把 WSL 的內(nèi)存設(shè)置到了 32GB/dev/shm跟著變成 16GB實(shí)際使用沒再觸發(fā)過這個(gè)錯(cuò)誤。7.2 首次啟動長時(shí)間無輸出不是卡死是編譯vLLM 第一次加載模型時(shí)會根據(jù)當(dāng)前 GPU 環(huán)境和模型配置現(xiàn)場編譯部分 CUDA kernel。編譯過程可能持續(xù)幾分鐘屏幕上甚至沒有明顯進(jìn)度提示期間 CPU 占用很高。很多同學(xué)以為是安裝壞了直接 CtrlC 取消結(jié)果下次啟動又重新編譯。其實(shí)一遍編譯完成后結(jié)果會緩存在~/.cache/vllm目錄下下次啟動就快多了。遇到這個(gè)情況建議心態(tài)放穩(wěn)等 5 到 10 分鐘。也可以先執(zhí)行nvidia-smi看看 GPU 是否在滿載計(jì)算如果 GPU 利用率高說明正在編譯或加載正常等待就行。7.3 模型放 /mnt/c 導(dǎo)致加載極慢這個(gè)問題前面提過但我愿意再強(qiáng)調(diào)一遍。WSL 2 的磁盤 IO 性能分兩層訪問 Linux 內(nèi)部目錄和訪問 Windows 掛載盤差異非常大。模型權(quán)重文件動輒十幾 GB放在 /mnt/c 下每次加載都像在用機(jī)械硬盤跑重負(fù)載。一定要把模型放到 WSL 2 自己的文件系統(tǒng)里比如~/models。同理如果未來把模型放到新掛載的磁盤也注意避免跨文件系統(tǒng)。7.4 宿主機(jī)需要關(guān)閉快速啟動但影響不大和我之前用 Docker Desktop 時(shí)的經(jīng)驗(yàn)不同WSL 2 里跑 vLLM 不用太糾結(jié) Windows 的快速啟動功能。不過在宿主機(jī)上長時(shí)間待機(jī)后偶爾會遇到 GPU 透傳異常導(dǎo)致 CUDA 程序無響應(yīng)。最有效的解決手段wsl --shutdown然后重新進(jìn)入 WSL 2。這個(gè)操作會把 WSL 里所有進(jìn)程關(guān)掉對日常開發(fā)來說損失不大但對剛啟動的 vLLM 服務(wù)需要重新拉起。7.5 端口被占用如果啟動vllm serve時(shí)提示端口被占用先確認(rèn)是不是同一臺機(jī)器上已經(jīng)有一個(gè)舊的 vLLM 進(jìn)程。用ps aux | grep vllm查看并清理舊進(jìn)程。如果確認(rèn)沒有進(jìn)程占用但端口起不來檢查 Windows 側(cè)的端口轉(zhuǎn)發(fā)是否有殘留。執(zhí)行netsh interface portproxy show v4tov4必要時(shí)清理舊的 portproxy 規(guī)則。7.6 同時(shí)跑多個(gè)模型時(shí)顯存不夠vLLM 一個(gè)實(shí)例綁定一個(gè)模型如果同時(shí)想在多個(gè)模型間切換最直接的辦法是先停掉一個(gè)服務(wù)再啟動另一個(gè)。WSL 2 里 GPU 顯存不會自動釋放到 Windows 側(cè)可能會出現(xiàn) Windows 任務(wù)管理器顯示顯存占用不降的情況。這是正常的等進(jìn)程消失一會兒后顯存會慢慢釋放。如果你經(jīng)常需要切多個(gè)模型可以考慮把兩個(gè)模型合成一個(gè)目錄或者使用支持多模型的入口方案但那樣復(fù)雜度會高很多。7.7 WSL 2 網(wǎng)絡(luò) IP 變化的問題WSL 2 每次重啟虛擬機(jī)的 IP 地址都會變。如果你設(shè)置過基于具體 IP 的端口轉(zhuǎn)發(fā)重啟后就會失效。這也是我推薦直接通過localhost訪問服務(wù)的原因。如果一定要從局域網(wǎng)里其他設(shè)備訪問這臺 WSL 里的 vLLM 服務(wù)建議用 Windows 側(cè)做端口轉(zhuǎn)發(fā)把 Windows 8000 端口轉(zhuǎn)發(fā)到 WSL 2 的當(dāng)前 IP但 IP 變化會導(dǎo)致配置失效得定期更新。這個(gè)場景更適合用一個(gè)固定內(nèi)網(wǎng) IP 的 Linux 機(jī)器來做WSL 2 定位在本地開發(fā)足夠。7.8 當(dāng) max_model_len 過小時(shí)長文本對話被截?cái)鄓LLM 的max_model_len參數(shù)決定 KV Cache 最多存多少 token。如果設(shè)置太小長文本對話或長文檔輸入會被直接截?cái)鄵p失內(nèi)容。調(diào)大一點(diǎn)雖然顯存占用增加但換來的是更自然的交互體驗(yàn)。開啟服務(wù)時(shí)記得根據(jù)顯存規(guī)模和實(shí)際場景設(shè)置這個(gè)參數(shù)。我在 16GB 顯存下用 Qwen2.5-7B設(shè)置--max-model-len 8192是沒問題的。7.9 單機(jī)多卡支持如果你的電腦有多張 NVIDIA 顯卡vLLM 可以自動使用所有 GPU只要設(shè)置環(huán)境變量export CUDA_VISIBLE_DEVICES0,1然后正常啟動即可。WSL 2 對多卡透傳的支持依賴 Windows 驅(qū)動版本如果你是雙卡用戶建議先確認(rèn)nvidia-smi能看到兩張卡再嘗試混卡推理。我這邊只有單卡沒有深度驗(yàn)證過雙卡但官方文檔說明 vLLM 天然支持張量并行和流水線并行WSL 2 環(huán)境不會額外增加限制。7.10 對比純 CPU 模式和 Ollama最后說幾句題外話。如果你將來遇到?jīng)]有 NVIDIA GPU 的設(shè)備想用 WSL 2 vLLM 跑純 CPU 模式直接勸退vLLM 官方不支持純 CPU 推理它從底層依賴 CUDA GPU。這種情況下建議直接用 llama.cpp 或者 Ollama它們對 CPU 環(huán)境更友好。而且 Ollama 在 WSL 2 里安裝也很方便直接把模型目錄映射過來即可。vLLM 的優(yōu)勢始終是 GPU 吞吐和多路并發(fā)場景對了才是利器。就我個(gè)人這段時(shí)間的使用體驗(yàn)來說WSL 2 vLLM 這套組合非常適合在 Windows 機(jī)器上做本地模型服務(wù)和開發(fā)調(diào)試。想把它當(dāng)生產(chǎn)服務(wù)器用還是建議換到純 Linux 環(huán)境畢竟 WSL 2 本身的定位是開發(fā)工具而非生產(chǎn)部署平臺。如果你正在用 Windows 又受夠了各種環(huán)境問題按這篇流程走一遍基本能把踩坑概率降到最低。裝好后你也能在 Windows 上得到一個(gè)響應(yīng)很快的本地大模型 API 服務(wù)。 Windows 上用 WSL 2 部署 vLLM 完整指南：GPU 推理環(huán)境搭建與踩坑記錄
一直覺得在 Windows 上跑大模型推理是一件很折騰的事。前陣子我拿到一臺帶 NVIDIA 顯卡的 Windows 筆記本想把它變成一臺能隨時(shí)調(diào)用的本地推理服務(wù)試了一圈方案最后老老實(shí)實(shí)回到 WSL 2 把 vLLM 完整裝了一遍。整個(gè)過程踩了不少坑但走通之后體驗(yàn)確實(shí)穩(wěn)定現(xiàn)在把一步步流程和教訓(xùn)完整整理出來給同樣想用 Windows WSL 2 部署 vLLM 的同學(xué)一條可以直接照抄的路。這篇內(nèi)容適合下面幾類人想在 Windows 機(jī)器上跑 vLLM 服務(wù)、本地開發(fā)大模型應(yīng)用、做模型效果驗(yàn)證或者單純想搞清楚 WSL 2 里 GPU 環(huán)境到底怎么配的。跟著這套流程走不需要你有很深的 Linux 經(jīng)驗(yàn)但至少要知道命令行基本操作。1. vLLM 為什么值得裝以及為什么 Windows 上必須走 WSL 2 這條路先把結(jié)論說在前面vLLM 是目前本地部署大模型時(shí)吞吐量表現(xiàn)最好的推理框架之一它最大的價(jià)值來自兩項(xiàng)設(shè)計(jì)——PagedAttention 顯存管理機(jī)制和 Continuous Batching 連續(xù)批處理策略。PagedAttention 的原理可以類比操作系統(tǒng)的虛擬內(nèi)存管理。傳統(tǒng)的推理框架在計(jì)算注意力時(shí)需要把完整的 KV Cache 放在連續(xù)顯存里模型一長、并發(fā)一高顯存碎片就出來了明明總量夠用卻報(bào) OOM。vLLM 把 KV Cache 切割成固定大小的塊類似內(nèi)存分頁可以零散存放并在計(jì)算時(shí)按索引取用顯存利用率明顯提升。加上它會在每個(gè) step 動態(tài)合并多個(gè)請求一起計(jì)算而不是等一個(gè)請求完整跑完再處理下一個(gè)GPU 的算力基本不會閑著。實(shí)際跑 Qwen2.5 系列模型時(shí)并發(fā)請求的吞吐量比樸素 Hugging Face transformers 實(shí)現(xiàn)高出數(shù)倍這一點(diǎn)在長文本、多路請求場景下體感特別明顯。那為什么 Windows 原生環(huán)境裝 vLLM 很難受vLLM 從設(shè)計(jì)上就是面向 Linux 的。它的安裝包依賴 CUDA 工具鏈的鏈接方式、Linux 的共享內(nèi)存機(jī)制、以及大量在 Linux 上默認(rèn)開啟的內(nèi)核級能力Windows 要么不支持要么行為不一致。而且官方 README 從沒承諾過原生 Windows 支持遇到編譯錯(cuò)誤基本屬于自己修非常痛苦。WSL 2 在這里的作用是提供一個(gè)與虛擬機(jī)類似的真實(shí) Linux 內(nèi)核但虛擬化開銷比傳統(tǒng)虛擬機(jī)低很多。對 vLLM 來說WSL 2 里的 Ubuntu 環(huán)境和一臺普通的 Linux 服務(wù)器幾乎沒區(qū)別可以正常訪問 GPU 驅(qū)動、使用共享內(nèi)存、跑 CUDA 程序。更重要的是WSL 2 的 GPU 透傳機(jī)制并不是把 GPU 完全模擬一遍而是通過宿主機(jī)驅(qū)動直接讓 Linux 側(cè)程序調(diào)用顯卡性能損耗可以忽略不計(jì)。我實(shí)測過同一模型在同硬件上跑 WSL 2 和原生 Ubuntu單請求延遲和并發(fā)吞吐都非常接近。所以結(jié)論是Windows 用戶跑 vLLMWSL 2 是當(dāng)前綜合考慮下最順的一條路。原生 Linux 雙啟動性能雖然更好但日常使用不方便虛擬機(jī)方案 GPU 透傳配置復(fù)雜且性能損耗明顯Docker Desktop 的 WSL 2 后端本質(zhì)上還是在 WSL 2 里跑不如直接在 WSL 2 里操作來得透明。2. WSL 2 安裝與系統(tǒng)資源配置把基礎(chǔ)打穩(wěn)2.1 安裝 WSL 2 并確認(rèn)版本在 Windows 11 或較新的 Windows 10 上安裝 WSL 2 比想象中簡單。以管理員身份打開 PowerShell執(zhí)行wsl --install這個(gè)命令會默認(rèn)安裝 Ubuntu 發(fā)行版并啟用 WSL 2 所需的 Windows 功能組件。如果是 Windows 10 的舊版本可能會需要手動開啟“適用于 Linux 的 Windows 子系統(tǒng)”和“虛擬機(jī)平臺”兩項(xiàng)功能然后重啟并安裝 WSL 2 內(nèi)核更新包。安裝完成后重啟系統(tǒng)首次啟動 Ubuntu 時(shí)會要求設(shè)置用戶名和密碼。用戶名會作為 Linux 下的默認(rèn)用戶比如我用的用戶名是will后續(xù)所有文件路徑都從這個(gè)用戶目錄展開。重啟后先確認(rèn)發(fā)行版跑的是 WSL 2在 PowerShell 里執(zhí)行wsl -l -v輸出里應(yīng)該能看到Ubuntu的 VERSION 列是2。如果還是 1執(zhí)行wsl --set-version Ubuntu 2這一步很重要。WSL 1 沒有真正的 Linux 內(nèi)核很多系統(tǒng)調(diào)用不兼容vLLM 跑不起來。2.2 用 .wslconfig 控制內(nèi)存、CPU 和交換分區(qū)WSL 2 默認(rèn)會吃掉宿主機(jī)一半的內(nèi)存這在跑大模型時(shí)經(jīng)常不夠用。vLLM 加載模型時(shí)需要較大的內(nèi)存來放權(quán)重、tokenizer 和運(yùn)行時(shí)數(shù)據(jù)同時(shí)還要給緩存留空間。默認(rèn)配置下經(jīng)常出現(xiàn)內(nèi)存不足導(dǎo)致進(jìn)程被殺。解決辦法是在 Windows 用戶目錄C:\Users\你的用戶名\下創(chuàng)建一個(gè).wslconfig文件例如我的配置[wsl2] memory16GB processors8 swap8GB localhostForwardingtruememory是 WSL 2 能使用的最大內(nèi)存我這里設(shè)置 16GBprocessors分配 8 核swap設(shè)置交換分區(qū)大小在內(nèi)存不夠時(shí)可以把部分?jǐn)?shù)據(jù)換到磁盤localhostForwardingtrue保證 Windows 側(cè)能通過localhost直接訪問 WSL 2 里啟動的服務(wù)這個(gè)開關(guān)默認(rèn)就是開啟的但顯式寫出來更安心。改完配置后需要重啟 WSL 2 才會生效wsl --shutdown然后重新進(jìn)入 Ubuntu?？梢杂胒ree -h檢查內(nèi)存是否生效。2.3 系統(tǒng)更新與基礎(chǔ)工具安裝進(jìn)入 Ubuntu 后先把系統(tǒng)包索引更新一遍sudo apt update sudo apt upgrade -y然后安裝后面的步驟一定會用到的工具sudo apt install -y python3-venv python3-pip curl gitUbuntu 22.04 和 24.04 都自帶 Python 3python3-venv 一定要裝后面創(chuàng)建虛擬環(huán)境依賴它。git 和 curl 主要用于下載模型腳本和測試接口。這里補(bǔ)充一個(gè)建議如果不是有特殊原因不要直接改系統(tǒng)的全局 Python 環(huán)境。vLLM 的依賴項(xiàng)很多包括特定版本的 PyTorch、transformers、tokenizers 等直接裝進(jìn)系統(tǒng)環(huán)境很容易和已有的包沖突。后面都基于 venv 用。3. WSL 2 里的 GPU 透傳與 CUDA 環(huán)境驗(yàn)證3.1 WSL 2 的 GPU 訪問機(jī)制WSL 2 支持 GPU 透傳但它的實(shí)現(xiàn)方式和 Docker GPU 直通不太一樣。在 WSL 2 里你不需要也不應(yīng)該在 Linux 側(cè)單獨(dú)安裝 NVIDIA 驅(qū)動。WSL 2 啟動時(shí)會自動把 Windows 宿主機(jī)已經(jīng)裝好的 NVIDIA 驅(qū)動映射到 Linux 側(cè)你在 WSL 里看到的 GPU 實(shí)際上是由 Windows 驅(qū)動管理的。所以在 Windows 宿主機(jī)上你需要先確認(rèn)已經(jīng)安裝了較新的 NVIDIA 驅(qū)動?？梢源蜷_ NVIDIA 控制面板或者直接運(yùn)行nvidia-smi確認(rèn)版本。我用的是 560 系列的驅(qū)動實(shí)測對 WSL 2 的 GPU 透傳支持很好。驅(qū)動太舊會導(dǎo)致 WSL 里nvidia-smi報(bào)錯(cuò)或者 CUDA 調(diào)用失敗。3.2 在 WSL 2 里驗(yàn)證 GPU 和 CUDA進(jìn)入 Ubuntu 終端直接運(yùn)行nvidia-smi重點(diǎn)看驅(qū)動的右上角版本信息。在 WSL 2 里如果顯示的是 Windows 宿主機(jī)的驅(qū)動版本說明 GPU 已經(jīng)成功透傳進(jìn)來了。比如我的輸出頂部寫著 “Driver Version: 566.03”這就是 Windows 宿主機(jī)驅(qū)動版本說明鏈路是通的。接下來驗(yàn)證 CUDA。vLLM 安裝時(shí)依賴 CUDA runtime這里有兩種選擇只使用 pip 安裝的 PyTorch 自帶的 CUDA 庫不裝系統(tǒng)級 CUDA Toolkit額外安裝 CUDA Toolkit包含 nvcc 編譯器等。如果只是跑 vLLM第一種就夠用了。但如果你之后想自己編譯 CUDA 擴(kuò)展、調(diào)試 kernel 或者跑一些需要 nvcc 的腳本建議順手裝一個(gè) CUDA Toolkit。官方推薦從 NVIDIA 官網(wǎng)裝但 Ubuntu 的 apt 源也可以雖然版本可能舊一些。我用的是在系統(tǒng)里安裝 CUDA Toolkit 12.4 版本用起來沒碰到兼容問題。裝好后驗(yàn)證nvcc --version如果只是想快速確認(rèn) PyTorch 能調(diào)用 GPU不需要急著裝完整 Toolkit。先創(chuàng)建虛擬環(huán)境后再裝 torch 驗(yàn)證也不晚。3.3 常見 GPU 驗(yàn)證失敗原因這里列舉我遇到過的兩個(gè)比較典型的問題。第一個(gè)是nvidia-smi報(bào) “command not found”。這種情況經(jīng)常發(fā)生在 WSL 剛裝完、還沒執(zhí)行過 Windows 側(cè)驅(qū)動更新的時(shí)候。在 Windows 宿主機(jī)上更新到最新 NVIDIA 驅(qū)動然后執(zhí)行wsl --shutdown重啟 WSL再進(jìn)來就能看到了。第二個(gè)是 PyTorch 能裝上但torch.cuda.is_available()返回 False。這個(gè)我之前排查了很久最后發(fā)現(xiàn)是 WSL 2 內(nèi)核版本太舊導(dǎo)致的。執(zhí)行wsl --update把 WSL 本身更新到最新版本就解決了。4. 創(chuàng)建 Python 虛擬環(huán)境并安裝 vLLM4.1 創(chuàng)建項(xiàng)目目錄與虛擬環(huán)境我比較習(xí)慣把所有模型相關(guān)的東西整理在一個(gè)固定目錄里便于管理。在 WSL 2 里執(zhí)行mkdir -p ~/projects/vllm-playground cd ~/projects/vllm-playground python3 -m venv vllm-env創(chuàng)建完成后激活source vllm-env/bin/activate看到終端行首出現(xiàn)(vllm-env)前綴就說明激活成功了。這個(gè)環(huán)境是獨(dú)立的一套 Python 解釋器和包管理空間所有安裝操作都隔離在這個(gè)目錄下不會污染系統(tǒng)環(huán)境。4.2 安裝 vLLM安裝 vLLM 本身只需要一條命令pip install vllm但這條命令的耗時(shí)和踩坑概率都不小。vLLM 依賴的 PyTorch 體積很大而且 pip 需要根據(jù)當(dāng)前平臺的 CUDA 版本決定下載哪一個(gè) wheel。在國內(nèi)網(wǎng)絡(luò)環(huán)境下建議把 pip 換成清華源或阿里源下載速度會快很多pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple安裝過程中 pip 會自動拉取匹配的 PyTorch 版本。常見的坑是 pip 默認(rèn)拉取的是 CPU 版 PyTorch導(dǎo)致 GPU 不可用。vLLM 的官方 wheel 會強(qiáng)制指定帶 CUDA 的 PyTorch 版本正常情況下不會裝錯(cuò)。裝上之后可以先確認(rèn)一下python -c import torch; print(torch.__version__, torch.cuda.is_available())輸出里應(yīng)該能看到torch 2.x.xcu12x這樣的版本號并且torch.cuda.is_available()是True。如果這里顯示 False請回到上一章排查驅(qū)動和 WSL 版本。如果網(wǎng)絡(luò)環(huán)境不好或者你想避免官方源下載過慢可以考慮先手動安裝 PyTorch 的 CUDA 版本pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124然后再裝 vLLM。vLLM 檢測到已有對應(yīng)版本的 PyTorch 就不會重復(fù)下載了。不過要注意vLLM 和 PyTorch 版本有對應(yīng)關(guān)系安裝時(shí)盡量選接近官方文檔要求的版本避免出現(xiàn)“不支持的組合”告警。4.3 檢查 vLLM 是否安裝成功還沒下載模型之前可以先用一個(gè)無模型的命令快速確認(rèn) vLLM 能正常導(dǎo)入python -c from vllm import LLM; print(vLLM import success)這一步主要檢查動態(tài)鏈接庫是否完整。vLLM 包含一些編譯好的 CUDA kernel導(dǎo)入時(shí)如果缺少依賴比如libcudnn.so或者libnccl.so會直接報(bào)ImportError。我在第一次裝的時(shí)候遇到過libcublas.so.12: cannot open shared object file這個(gè)報(bào)錯(cuò)原因是我用 apt 裝過一個(gè)舊版 CUDA系統(tǒng)里的庫路徑被覆蓋了。解決辦法是把虛擬環(huán)境里的site-packages下 vLLM 依賴的nvidia/cublas庫路徑加到LD_LIBRARY_PATHexport LD_LIBRARY_PATH$VIRTUAL_ENV/lib/python3.10/site-packages/nvidia/cublas/lib:$LD_LIBRARY_PATH如果想每次進(jìn)入環(huán)境自動生效可以把這個(gè) export 寫到~/projects/vllm-playground/vllm-env/bin/activate文件的末尾。4.4 關(guān)于 Python 版本的選擇vLLM 對 Python 版本有明確要求舊版本不支持太新的 Python新版本對舊 Python 也有最低限制。官方安裝文檔會列出支持的 Python 版本范圍。以 Ubuntu 22.04 自帶的 Python 3.10 為例配合較新版本的 vLLM 是沒問題的。如果你用的是 Ubuntu 24.04 自帶 Python 3.12需要確認(rèn)你安裝的 vLLM 版本是否支持 3.12不支持的話用update-alternatives切換 Python 版本或者在創(chuàng)建 venv 時(shí)顯式指定python3.10 -m venv vllm-env需要注意Ubuntu 24.04 默認(rèn)可能沒有安裝 python3.10需要從 deadsnakes PPA 或者源碼安裝。這部分操作比較啰嗦我建議新手直接用 Ubuntu 22.04省去一堆兼容性問題。5. 模型下載與目錄規(guī)劃5.1 選模型顯存匹配是第一優(yōu)先級vLLM 能跑的模型很多包括 LLaMA、Qwen、Mistral、Gemma 等。選模型的第一步不是看能力而是看你的顯卡顯存。權(quán)重加載需要顯存KV Cache 也需要顯存而且 KV Cache 往往是大頭。這里列出我實(shí)測時(shí)常見的顯存匹配關(guān)系GPU 顯存推薦模型示例說明8GBQwen2.5-1.5B-Instruct / Qwen2.5-3B-Instruct直接跑max_model_len 不要開太大12GBQwen2.5-7B-Instruct / Llama-3.1-8B量化7B 全精度比較緊張需要調(diào)低 max_model_len16GBQwen2.5-7B-Instruct比較舒服可以開 8192 上下文24GBQwen2.5-14B-Instruct / 32B 量化14B 全精度能跑上下文長度適中40GBQwen2.5-72B 量化 / 開源大模型基本能嘗試各種模型如果顯存不滿足模型需求vLLM 啟動時(shí)會報(bào) OOM 或者直接退出。你可以通過降低--max-model-len參數(shù)來縮小 KV Cache 占用但模型權(quán)重占用的顯存是固定的低于權(quán)重需求就沒法跑。5.2 下載模型ModelScope 鏡像更穩(wěn)模型下載方式主要有兩個(gè)來源Hugging Face 和 ModelScope。Hugging Face 是全球最大的模型倉庫但國內(nèi)網(wǎng)絡(luò)訪問不穩(wěn)定。ModelScope 是國內(nèi)平臺下載速度通常更快而且 vLLM 官方支持通過環(huán)境變量直接使用 ModelScope。我這邊推薦的做法是優(yōu)先從 ModelScope 下載因?yàn)樗俣瓤臁⒕W(wǎng)絡(luò)穩(wěn)定。步驟如下pip install modelscope然后下載模型拿 Qwen2.5-7B-Instruct 舉例modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ~/models/qwen2.5-7b-instruct這個(gè)命令會把模型的權(quán)重、配置文件、tokenizer 等全部下載到~/models/qwen2.5-7b-instruct目錄下。下載速度取決于網(wǎng)絡(luò)Qwen2.5-7B 的權(quán)重文件大約 15GBModelScope 一般拉滿帶寬比 Hugging Face 快不少。如果你已經(jīng)下載了 Hugging Face 格式的模型vLLM 能直接使用。關(guān)鍵是記住模型目錄的絕對路徑比如~/models/qwen2.5-7b-instruct。5.3 模型存放位置不要放 /mnt/c這是我在實(shí)際使用中踩過的大坑。WSL 2 訪問 Windows 文件系統(tǒng)也就是/mnt/c下的路徑走的是 9P 協(xié)議讀寫速率比 WSL 內(nèi)部的 ext4 文件系統(tǒng)慢得多。把十幾個(gè) GB 的模型文件放在C:\models之類的位置vLLM 加載權(quán)重時(shí)需要從 /mnt/c 遷到內(nèi)存那個(gè)速度簡直讓人懷疑人生。我曾經(jīng)實(shí)測過同一個(gè)模型放在 /mnt/c 和放在 ~/models 下的加載時(shí)間差異前者慢了近 5 倍。所以模型優(yōu)先放在 WSL 2 內(nèi)部的 Linux 文件系統(tǒng)里。如果擔(dān)心 WSL 磁盤占用太大可以在下載前規(guī)劃好空間用df -h檢查。模型很占空間刪掉要謹(jǐn)慎。5.4 配置環(huán)境變量為了讓 vLLM 正確找到模型常用兩種方式在啟動命令里直接傳模型路徑設(shè)置HF_HOME環(huán)境變量指向你存放模型緩存的目錄。我習(xí)慣在~/.bashrc里追加export HF_HOME~/models export VLLM_USE_MODELSCOPEtrueVLLM_USE_MODELSCOPEtrue表示當(dāng) vLLM 在模型加載時(shí)找不到本地模型、需要去線上找時(shí)優(yōu)先走 ModelScope 而非 Hugging Face。這對國內(nèi)用戶非常友好。設(shè)置完后source ~/.bashrc6. 離線推理驗(yàn)證與 OpenAI 兼容 API 服務(wù)啟動6.1 用 Python 腳本做離線推理測試安裝完成且模型下載好之后先用一個(gè)簡單的 Python 腳本驗(yàn)證整個(gè)鏈路。創(chuàng)建一個(gè)test_infer.pyfrom vllm import LLM, SamplingParams llm LLM(model~/models/qwen2.5-7b-instruct, max_model_len8192) params SamplingParams(temperature0.7, top_p0.8, max_tokens512) prompts [ 用一句話介紹 WSL 2, 寫一段 Python 代碼實(shí)現(xiàn)快速排序 ] outputs llm.generate(prompts, params) for output in outputs: prompt output.prompt generated_text output.outputs[0].text print(fPrompt: {prompt}) print(fGenerated: {generated_text}) print(- * 50)運(yùn)行python test_infer.py第一次執(zhí)行時(shí)vLLM 會做 CUDA kernel 預(yù)熱和模型加載耗時(shí)可能比較長屏幕上會打印類似Starting vLLM using 1 GPUs和Loading model weights took ... GB的信息。這一步正常輸出就說明安裝沒白費(fèi)。如果這里報(bào)錯(cuò)重點(diǎn)看是不是模型路徑不對、顯存不足、或者 CUDA 驅(qū)動版本過舊。6.2 啟動 OpenAI 兼容 API 服務(wù)vLLM 最常用的場景之一是啟動一個(gè) OpenAI 兼容的 HTTP 服務(wù)這樣你本地的任何 OpenAI SDK 或者工具都可以直接把 base_url 指過去。啟動命令vllm serve ~/models/qwen2.5-7b-instruct --host 0.0.0.0 --port 8000參數(shù)說明--host 0.0.0.0監(jiān)聽所有網(wǎng)卡包括 WSL 2 的虛擬網(wǎng)卡--port 8000服務(wù)端口如果需要降低顯存占用可以加上--max-model-len 4096。啟動成功后在 Windows 宿主機(jī)瀏覽器直接訪問http://localhost:8000/v1/models會看到 JSON 格式的模型列表。這就是很典型的驗(yàn)證接口是否正常的方式。如果想從命令行測試對話可以用 curlcurl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: ~/models/qwen2.5-7b-instruct, messages: [{role: user, content: 你好}], max_tokens: 128}返回內(nèi)容里會包含choices字段里面的message.content就是模型生成的回復(fù)。從 Windows 側(cè)訪問localhost:8000能通是因?yàn)?WSL 2 默認(rèn)開啟了 localhost 轉(zhuǎn)發(fā)。如果你的 Windows 10 版本較舊可能需要手動在 PowerShell 里用netsh interface portproxy做端口映射把 Windows 的 8000 端口轉(zhuǎn)發(fā)到 WSL 2 的虛擬 IP 上。不過一般情況下默認(rèn)配置已經(jīng)夠用了。6.3 寫一個(gè)小工具腳本提升體驗(yàn)為了提高后續(xù)使用效率我給 API 服務(wù)封裝了一個(gè)簡單的對話腳本放在chat.py里from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) response client.chat.completions.create( model~/models/qwen2.5-7b-instruct, messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)需要先pip install openai。用這個(gè)腳本可以快速測試服務(wù)是否在正常工作比 curl 直觀很多。這套 API 兼容性的好處是你可以直接在本地把 base_url 換成 vLLM 服務(wù)地址然后繼續(xù)用 LangChain、Dify 或者其他框架而不改代碼。7. 實(shí)測中的十大坑與調(diào)優(yōu)經(jīng)驗(yàn)整個(gè)流程走下來我踩了不少問題這里集中記錄一下很多問題不裝到那時(shí)候根本想不到。7.1 共享內(nèi)存不足導(dǎo)致進(jìn)程崩潰vLLM 在多并發(fā)或處理長上下文時(shí)tokenizer 和調(diào)度器會在共享內(nèi)存里臨時(shí)放數(shù)據(jù)。WSL 2 里/dev/shm的默認(rèn)大小是物理內(nèi)存的一半如果內(nèi)存不夠大服務(wù)運(yùn)行一段時(shí)間后可能直接報(bào)錯(cuò)RuntimeError: Shared memory area is too small排查方式df -h /dev/shm如果 Size 很小可以臨時(shí)擴(kuò)容sudo mount -o remount,size32G /dev/shm這條命令只在當(dāng)前會話生效重啟后會恢復(fù)默認(rèn)。要持久化的話可以在/etc/fstab里加一條配置但更簡單的做法是把這條命令放在啟動腳本里。我當(dāng)時(shí)直接把 WSL 的內(nèi)存設(shè)置到了 32GB/dev/shm跟著變成 16GB實(shí)際使用沒再觸發(fā)過這個(gè)錯(cuò)誤。7.2 首次啟動長時(shí)間無輸出不是卡死是編譯vLLM 第一次加載模型時(shí)會根據(jù)當(dāng)前 GPU 環(huán)境和模型配置現(xiàn)場編譯部分 CUDA kernel。編譯過程可能持續(xù)幾分鐘屏幕上甚至沒有明顯進(jìn)度提示期間 CPU 占用很高。很多同學(xué)以為是安裝壞了直接 CtrlC 取消結(jié)果下次啟動又重新編譯。其實(shí)一遍編譯完成后結(jié)果會緩存在~/.cache/vllm目錄下下次啟動就快多了。遇到這個(gè)情況建議心態(tài)放穩(wěn)等 5 到 10 分鐘。也可以先執(zhí)行nvidia-smi看看 GPU 是否在滿載計(jì)算如果 GPU 利用率高說明正在編譯或加載正常等待就行。7.3 模型放 /mnt/c 導(dǎo)致加載極慢這個(gè)問題前面提過但我愿意再強(qiáng)調(diào)一遍。WSL 2 的磁盤 IO 性能分兩層訪問 Linux 內(nèi)部目錄和訪問 Windows 掛載盤差異非常大。模型權(quán)重文件動輒十幾 GB放在 /mnt/c 下每次加載都像在用機(jī)械硬盤跑重負(fù)載。一定要把模型放到 WSL 2 自己的文件系統(tǒng)里比如~/models。同理如果未來把模型放到新掛載的磁盤也注意避免跨文件系統(tǒng)。7.4 宿主機(jī)需要關(guān)閉快速啟動但影響不大和我之前用 Docker Desktop 時(shí)的經(jīng)驗(yàn)不同WSL 2 里跑 vLLM 不用太糾結(jié) Windows 的快速啟動功能。不過在宿主機(jī)上長時(shí)間待機(jī)后偶爾會遇到 GPU 透傳異常導(dǎo)致 CUDA 程序無響應(yīng)。最有效的解決手段wsl --shutdown然后重新進(jìn)入 WSL 2。這個(gè)操作會把 WSL 里所有進(jìn)程關(guān)掉對日常開發(fā)來說損失不大但對剛啟動的 vLLM 服務(wù)需要重新拉起。7.5 端口被占用如果啟動vllm serve時(shí)提示端口被占用先確認(rèn)是不是同一臺機(jī)器上已經(jīng)有一個(gè)舊的 vLLM 進(jìn)程。用ps aux | grep vllm查看并清理舊進(jìn)程。如果確認(rèn)沒有進(jìn)程占用但端口起不來檢查 Windows 側(cè)的端口轉(zhuǎn)發(fā)是否有殘留。執(zhí)行netsh interface portproxy show v4tov4必要時(shí)清理舊的 portproxy 規(guī)則。7.6 同時(shí)跑多個(gè)模型時(shí)顯存不夠vLLM 一個(gè)實(shí)例綁定一個(gè)模型如果同時(shí)想在多個(gè)模型間切換最直接的辦法是先停掉一個(gè)服務(wù)再啟動另一個(gè)。WSL 2 里 GPU 顯存不會自動釋放到 Windows 側(cè)可能會出現(xiàn) Windows 任務(wù)管理器顯示顯存占用不降的情況。這是正常的等進(jìn)程消失一會兒后顯存會慢慢釋放。如果你經(jīng)常需要切多個(gè)模型可以考慮把兩個(gè)模型合成一個(gè)目錄或者使用支持多模型的入口方案但那樣復(fù)雜度會高很多。7.7 WSL 2 網(wǎng)絡(luò) IP 變化的問題WSL 2 每次重啟虛擬機(jī)的 IP 地址都會變。如果你設(shè)置過基于具體 IP 的端口轉(zhuǎn)發(fā)重啟后就會失效。這也是我推薦直接通過localhost訪問服務(wù)的原因。如果一定要從局域網(wǎng)里其他設(shè)備訪問這臺 WSL 里的 vLLM 服務(wù)建議用 Windows 側(cè)做端口轉(zhuǎn)發(fā)把 Windows 8000 端口轉(zhuǎn)發(fā)到 WSL 2 的當(dāng)前 IP但 IP 變化會導(dǎo)致配置失效得定期更新。這個(gè)場景更適合用一個(gè)固定內(nèi)網(wǎng) IP 的 Linux 機(jī)器來做WSL 2 定位在本地開發(fā)足夠。7.8 當(dāng) max_model_len 過小時(shí)長文本對話被截?cái)鄓LLM 的max_model_len參數(shù)決定 KV Cache 最多存多少 token。如果設(shè)置太小長文本對話或長文檔輸入會被直接截?cái)鄵p失內(nèi)容。調(diào)大一點(diǎn)雖然顯存占用增加但換來的是更自然的交互體驗(yàn)。開啟服務(wù)時(shí)記得根據(jù)顯存規(guī)模和實(shí)際場景設(shè)置這個(gè)參數(shù)。我在 16GB 顯存下用 Qwen2.5-7B設(shè)置--max-model-len 8192是沒問題的。7.9 單機(jī)多卡支持如果你的電腦有多張 NVIDIA 顯卡vLLM 可以自動使用所有 GPU只要設(shè)置環(huán)境變量export CUDA_VISIBLE_DEVICES0,1然后正常啟動即可。WSL 2 對多卡透傳的支持依賴 Windows 驅(qū)動版本如果你是雙卡用戶建議先確認(rèn)nvidia-smi能看到兩張卡再嘗試混卡推理。我這邊只有單卡沒有深度驗(yàn)證過雙卡但官方文檔說明 vLLM 天然支持張量并行和流水線并行WSL 2 環(huán)境不會額外增加限制。7.10 對比純 CPU 模式和 Ollama最后說幾句題外話。如果你將來遇到?jīng)]有 NVIDIA GPU 的設(shè)備想用 WSL 2 vLLM 跑純 CPU 模式直接勸退vLLM 官方不支持純 CPU 推理它從底層依賴 CUDA GPU。這種情況下建議直接用 llama.cpp 或者 Ollama它們對 CPU 環(huán)境更友好。而且 Ollama 在 WSL 2 里安裝也很方便直接把模型目錄映射過來即可。vLLM 的優(yōu)勢始終是 GPU 吞吐和多路并發(fā)場景對了才是利器。就我個(gè)人這段時(shí)間的使用體驗(yàn)來說WSL 2 vLLM 這套組合非常適合在 Windows 機(jī)器上做本地模型服務(wù)和開發(fā)調(diào)試。想把它當(dāng)生產(chǎn)服務(wù)器用還是建議換到純 Linux 環(huán)境畢竟 WSL 2 本身的定位是開發(fā)工具而非生產(chǎn)部署平臺。如果你正在用 Windows 又受夠了各種環(huán)境問題按這篇流程走一遍基本能把踩坑概率降到最低。裝好后你也能在 Windows 上得到一個(gè)響應(yīng)很快的本地大模型 API 服務(wù)。