說句實在話vLLM 這東西放到 Linux 上是真省心裝好驅動和 Python 環境pip install vllm就能把模型服務跑起來但如果你手里只有一臺 Windows 機器情況就開始變得有意思了。我在 Windows 上跑通 Qwen3-8B-FP8 之前翻了不少資料也踩了不少坑——vLLM 官方對 Windows 的支持長期停留在“實驗性”階段很多教程看了開頭就不想繼續。這篇文章是我完整的實操記錄從一臺 Windows 11 機器開始通過 WSL2 部署 vLLM把 Qwen3-8B-FP8 這個 FP8 量化模型拉起來暴露成 OpenAI 兼容的 HTTP API然后用 curl、Python requests 和 OpenAI SDK 三種方式完成調用。整個過程對顯存和系統要求說得比較清楚適合手里有 16GB 及以上顯存、又暫時不想換 Linux 環境的讀者。1. 為什么要在Windows上折騰vLLM想清楚再動手1.1 vLLM是什么為什么它這么挑環境vLLM 是目前大模型推理服務里使用率非常高的一個開源框架核心賣點是 PagedAttention 和 Continuous Batching。PagedAttention 這個機制你可以理解成“給顯存做虛擬內存”把 KV Cache 切成小塊按需分配解決了長上下文推理時顯存碎片化的問題Continuous Batching 則是把多個請求動態拼成一個 batch 去推理而不是等前一個請求完全結束才接下一個。這兩點疊加起來讓 vLLM 在并發場景下的吞吐量比樸素的推理腳本高出很多。但 vLLM 從誕生起就把 Linux 當成“默認生存環境”因為它的高性能路徑依賴 Linux 下成熟的 CUDA 生態比如 FlashAttention、NCCL、各種自定義算子。Windows 上不是不能跑只是很多算子需要單獨編譯碰上 FlashAttention 這類對編譯器版本敏感的庫一個坑接一個坑。社區從某個版本開始提供了 Windows 下的實驗性支持但性能沒法和 Linux 比綜合體驗也不穩定所以我的建議非常直接生產環境用 LinuxWindows 上想快速體驗就用 WSL2。WSL2 本質上就是 Windows 內置的輕量虛擬機里面跑的是真正的 Linux 內核。對顯卡用戶來說NVIDIA 驅動在 Windows 和 WSL2 之間是共享的WSL2 里可以直接拿到 GPU 的 CUDA 能力性能損耗很小。所以我選擇了 WSL2 路線而不是折騰原生 Windows 版 vLLM也不是再套一層 Docker。1.2 Windows上跑vLLM的三條路線對比這里我把常見的幾條路線拉出來對比一下方便你根據自己情況選。路線優點缺點適合場景WSL2 原生安裝 vLLM性能接近 Linux配置簡單社區資料最多需要先了解 WSL2虛擬磁盤占空間個人開發、跑實驗、學習部署Docker Desktop vLLM 鏡像環境隔離最干凈團隊復制方便多一層虛擬化磁盤占用更大已有 Docker 習慣或要做交付Windows 原生安裝 vLLM不用虛擬化路徑最直接官方支持實驗性算子編譯容易出問題只跑極小模型或者想嘗鮮我個人推薦 WSL2。理由不復雜性能上它最接近原生 Linux而且 vLLM 官方文檔里的常見問題、GitHub issue 基本都是圍繞 Linux 環境你在 WSL2 里遇到問題照著 Linux 的解決方案改一改就能用。Docker 路線雖然隔離性好但 GPU 透傳、鏡像版本、磁盤空間這些變量疊加起來排查起來更費勁不適合新手起步。1.3 Qwen3-8B-FP8為什么選這個模型當案例Qwen3-8B 是通義千問第三代的 8B 參數模型指令跟隨和代碼能力都很能打8B 這個規模意味著它對單卡用戶非常友好。FP8 是它的量化版本權重用 8 位浮點數E4M3存儲相比 BF16 版本的 8B 模型權重文件直接減半顯存占用明顯下降推理時內存帶寬壓力也更小而質量損失在大部分場景下很難感知到。這套組合對 Windows vLLM 實戰來說特別合適模型權重合計約 8GB 左右FP8 加載后顯存占用更小16GB 顯存能跑得比較寬松24GB 顯存可以留出大量空間給 KV Cache 做長上下文。相比那些動輒需要多卡部署的大模型Qwen3-8B-FP8 在成本和效果之間平衡得很好作為第一個跑通的模型不會讓你在硬件上就被勸退。2. 環境準備WSL2、驅動、Python環境一次配好2.1 開啟WSL2并安裝Ubuntu發行版在開始之前確認你的 Windows 版本。Windows 10 2004 及以上、Windows 11 都能直接用官方命令裝 WSL2如果你的系統比較老建議先手動開啟“適用于 Linux 的 Windows 子系統”和“虛擬機平臺”這兩個 Windows 功能再安裝 WSL2 內核更新包。我個人最常用的方式是管理員身份打開 PowerShell執行wsl --install -d Ubuntu-22.04如果之前沒有安裝過 WSL這個命令會自動啟用相關 Windows 功能、安裝 WSL2 內核并下載 Ubuntu 發行版。整個過程可能需要重啟一次。重啟后第一次進入 Ubuntu 會讓你設置用戶名和密碼這個用戶默認有 sudo 權限后續大部分操作都要在這個 Linux 環境里完成。裝完以后例行檢查wsl -l -v輸出結果里應該看到 Ubuntu 的 VERSION 列是 2。如果顯示的版本是 1需要用下面命令把默認版本切到 2wsl --set-default-version 2這里有個很容易忽略的細節WSL2 和 WSL1 對 GPU 的支持完全不同只有 WSL2 才有真正的 GPU 透傳能力切到 2 這一步別跳過。2.2 檢查顯卡驅動與CUDA環境WSL2 里不需要單獨安裝 NVIDIA 的 Linux 驅動這是一個讓很多人意外的點。你只需要在 Windows 側裝好 NVIDIA 官方驅動WSL2 里的 nvidia-smi 會自動對應到同一個驅動層。裝完驅動后進入 Ubuntu 終端執行nvidia-smi能看到顯卡型號和驅動版本就說明 GPU 透傳沒問題。我踩過的一個坑是驅動太老vLLM 加載時直接報 CUDA 版本不兼容后來把驅動升級到最新版才消停。建議你在動手前就把驅動更新到 550 或更高版本省得后面排查。vLLM 的 pip 安裝包已經自帶了 CUDA runtime 相關的庫所以你在 WSL2 里不需要手動安裝完整的 CUDA Toolkit只要顯卡驅動新到能支撐當前 CUDA 版本就行。這一點和原生 Linux 部署略有區別很多人在這里白白浪費了大量時間去裝 CUDA其實裝完 vLLM 之后CUDA 相關的東西基本都被 pip 依賴自動帶上了。2.3 Python環境準備用uv管理依賴更省心WSL2 里通常自帶 Python 3.10 或 3.12但直接拿系統 Python 裝 vLLM 容易出現依賴沖突。我的習慣是先裝 uv它是目前處理 Python 依賴速度最快、也最省心的工具之一。在 Ubuntu 的終端里執行curl -LsSf https://astral.sh/uv/install.sh | sh安裝好后創建一個虛擬環境并激活uv venv .venv source .venv/bin/activate后續所有 pip 安裝都走uv pip install不僅快還能避免很多 Python 包版本打架的問題。如果你更習慣 conda也不是不行但我實測下來 uv 在 WSL2 里體感更輕、裝大包時不容易超時。2.4 顯存、磁盤和基礎資源檢查開始部署之前建議先確認三件事顯存、磁盤空間、內存。nvidia-smi看顯存Qwen3-8B-FP8 權重約 8GB啟動時 vLLM 還會根據你的設置劃走一部分顯存做 KV Cache所以 16GB 顯存是起步線24GB 會比較舒服。磁盤方面模型倉庫加運行日志至少預留 20GB而且強烈建議放在 WSL2 內部的 Linux 文件系統里不要放在/mnt/c這種 Windows 掛載盤上跨文件系統讀寫會讓模型加載速度肉眼可見地變慢。內存建議至少有 16GB因為模型加載過程中需要先讀入內存再拷貝到顯存內存太小會出現看著像卡死、實際上在瘋狂換頁的表現。3. 安裝vLLM與下載Qwen3-8B-FP8模型3.1 安裝vLLM一行命令背后的版本選擇在剛才創建并激活的虛擬環境里安裝 vLLMuv pip install vllm默認會安裝當前最新穩定版我寫這篇實操時是 0.9.x。如果你希望更穩妥可以指定一個已知大版本號uv pip install vllm0.9,0.10官方 PyPI 上的 vLLM wheel 體積不小安裝耗時較長。國內網絡環境下如果下載慢或者超時可以臨時切換到清華 PyPI 鏡像uv pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple裝完以后驗證版本python -c import vllm; print(vllm.__version__)能正常輸出版本號說明 vLLM 主體安裝成功。這里有一個非常關鍵的細節vLLM 和 PyTorch 的版本綁定關系比較強你不需要也不應該手動指定 torch 版本直接裝 vllm 會讓 pip 自動解析出配套的 torch。手動亂裝 torch 很容易把環境搞崩回頭排查依賴沖突才是最耗時間的。3.2 下載Qwen3-8B-FP8模型兩條國內可用的路徑模型推薦直接下載到 WSL2 內部路徑用類似~/models/Qwen3-8B-FP8這種目錄。第一條路徑是使用 Hugging Face 的國內鏡像站點 hf-mirror。通過環境變量把下載源指到鏡像export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8如果你沒裝 huggingface_hub先執行uv pip install huggingface_hub。第二條路徑是 ModelScope。Qwen 系列在 ModelScope 上有官方倉庫下載速度在國內相當樂觀pip install modelscope modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ~/models/Qwen3-8B-FP8兩條路我都實測過ModelScope 對國內網絡更友好Hugging Face 鏡像勝在模型目錄結構和 vLLM 生態天然一致。下載完成后確認目錄里至少有 config.json、tokenizer.json 和若干個 .safetensors 權重文件缺文件的話后續加載一定會報錯。3.3 模型文件完整性與路徑規劃模型下載好以后我建議把路徑固定在一個地方避免每次啟動都找半天。比如統一放到~/models/下那么 vLLM 啟動時直接用--model ~/models/Qwen3-8B-FP8指定本地路徑即可不用每次寫完整的 HF 倉庫名。另外一個容易被忽略的點是vLLM 加載本地模型目錄時會自動讀取目錄里的 config.json里面已經包含了 FP8 量化的配置信息。也就是說正常情況下你不需要手動指定--quantization fp8vLLM 會自己識別。這點和加載某些第三方量化模型時需要手動傳參的體驗不太一樣對新手更友好。4. vLLM服務啟動實戰參數逐項拆解4.1 最小化啟動命令先跑通再說在 WSL2 終端里確保虛擬環境已激活然后執行vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000如果一切正常你會看到 vLLM 先加載模型權重再初始化推理引擎最后輸出類似下面的日志INFO: Started server process [12345] INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete就說明服務已經起來了。用瀏覽器打開http://localhost:8000再訪問/health或/healthz路徑通常能返回健康檢查狀態。不過“先跑通”的命令只是最小集實際使用中很少這樣裸跑。你大概率會遇到顯存不夠用、上下文長度不合適、端口被占用等問題。下面我把關鍵參數逐個拆開講你不需要全記住先按自己的硬件情況挑幾個改動跑通一次后再回頭細看就好。4.2 關鍵啟動參數說明每個參數為什么值得調參數作用我的建議--model指定模型路徑或 HF 倉庫名本地路徑更穩定建議用絕對路徑--host/--port服務監聽地址和端口默認 0.0.0.0:8000注意端口沖突--max-model-len模型最大上下文長度顯存緊張時設 8192 或 16384 立省顯存--gpu-memory-utilization允許 vLLM 占用顯存的比例默認 0.9單卡共享機器可以降到 0.6-0.7--tensor-parallel-size使用幾張卡做張量并行單卡千萬別設大于 1多卡也要謹慎--quantization強制指定量化方式本模型可省異常時顯式用fp8--served-model-name對外暴露的模型名稱方便對接已有客戶端配置--trust-remote-code允許加載倉庫里的自定義代碼部分模型需要Qwen 一般不需要--api-key為 API 增加訪問密鑰暴露公網時強烈建議開啟之所以把--max-model-len單獨拎出來說是因為這個參數對顯存影響巨大。Qwen3-8B 原生支持 32K 上下文但如果你只是做日常問答、代碼生成大部分請求的上下文也就是幾千 token。把--max-model-len從 32768 降到 8192KV Cache 占用直接少一大截在 16GB 顯存上體感非常明顯。4.3 FP8量化在vLLM里的處理細節Qwen3-8B-FP8 的 config.json 里自帶quantization_configvLLM 加載時會自動識別。如果你在日志中看到模型被當作 BF16 加載說明量化信息沒被正確解析這時候可以顯式指定vllm serve ~/models/Qwen3-8B-FP8 \ --quantization fp8 \ --kv-cache-dtype fp8_e4m3--kv-cache-dtype fp8_e4m3的作用是把 KV Cache 也切成 FP8 存儲進一步壓顯存。這個選項在 Ada Lovelace 及以上架構的顯卡上支持比較好如果你的顯卡是 RTX 30 系建議先不開啟實測一部分場景會有兼容性問題。另外注意FP8 權重在推理時會反量化回更高精度做計算所以它不會像整型量化那樣明顯犧牲模型質量這也是 FP8 這兩年被大規模采用的原因之一。在 vLLM 里使用 FP8 模型你不需要改動任何業務代碼API 層面和普通模型完全一致。4.4 啟動日志怎么看快速判斷服務健康狀態剛開始跑的時候日志非常長很多人一刷屏就慌了。其實不需要逐行讀重點盯這幾類信息顯存分配情況日志里會顯示類似GPU memory usage: xxx或Number of GPU blocks如果這里的數字很小說明可用 KV Cache 空間不足并發能力會受限模型加載完成提示出現Load avg weights took ...表示權重加載完成這里時間太久的話要懷疑是不是模型放到了/mnt/c下Starting vLLM server at ...和Application startup complete這兩行是服務可用的信號。如果啟動過程中卡在某一步不動大概率就是網絡問題還在下載或者顯存不足。前者檢查模型路徑是否指向本地目錄后者看 nvidia-smi 確認顯存沒被其他進程占滿。4.5 讓服務在后臺運行nohup和tmuxWSL2 終端一旦關閉前臺運行的 vLLM 服務也會跟著退出。為了避免反復重啟我習慣用 nohup 把服務放到后臺并把日志寫進文件nohup vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ vllm.log 21 要查日志就看tail -f vllm.log想殺掉服務就pkill -f vllm serve。這個操作方式在 Windows Terminal 里配合 WSL2 使用很順手不需要額外裝工具。5. 調用推理接口OpenAI兼容API從curl到SDK5.1 用curl快速驗證30秒確認服務正常vLLM 啟動后暴露的是 OpenAI 兼容 API所以最簡單的驗證方式就是 curl。打開一個新的終端Windows PowerShell 也可以因為 localhost 是通的curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B-FP8, messages: [ {role: user, content: 用一句話解釋什么是PagedAttention} ], max_tokens: 128, temperature: 0.7 }返回 JSON 里會出現choices[0].message.content字段里面就是模型生成的回答。這一步能通說明整個服務鏈路已經問題不大了。如果你啟動時指定了--served-model-name這里model字段要用你指定的名字。5.2 用Python requests調用不依賴額外庫很多人寫 demo 不想引入 OpenAI SDK那就直接用 requestsimport requests url http://localhost:8000/v1/chat/completions payload { model: Qwen3-8B-FP8, messages: [ {role: user, content: 寫一段Python代碼實現快速排序} ], max_tokens: 512, temperature: 0.3 } response requests.post(url, jsonpayload) data response.json() print(data[choices][0][message][content])注意返回結構里content是最終拼接好的完整回答。requests 的json參數會自動設置 Content-Type不用手動加 header這一點比 curl 命令省事。5.3 用OpenAI SDK調用復用現有代碼如果你的項目本來就用了 OpenAI 的 Python SDK只需要改一下 base_urlfrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) completion client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: system, content: 你是一個樂于助人的助手。}, {role: user, content: 介紹一下Qwen3主力模型的特點} ] ) print(completion.choices[0].message.content)api_key 填一個占位字符串就行因為 vLLM 默認不校驗密鑰。如果你啟動時設置了--api-key記得把這里換成真實密鑰。這套寫法最大的價值在于以后你想換成其他 OpenAI 兼容服務比如別的推理框架或云廠商接口代碼幾乎不用動。5.4 流式輸出實戰類ChatGPT打字機效果非流式接口要等模型完整生成完才返回長響應時會明顯感受到延遲。流式輸出可以讓 token 一個接一個蹦出來體感和 ChatGPT 網頁版接近。用 OpenAI SDK 的話只需加一個streamTruefrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) stream client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: user, content: 寫一段500字左右的產品介紹} ], streamTrue ) for chunk in stream: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)底層原理是 SSEServer-Sent EventsvLLM 會把每個生成的 token 通過 HTTP 長連接實時推給客戶端。對 Web 前端來說解析 SSE 流把內容渲染到頁面就可以了。流式響應對長文本生成體驗改善非常明顯建議對接業務時優先考慮。6. 性能調優與Windows/WSL2踩坑實錄6.1 性能和顯存之間的取舍三個關鍵參數先說明一個原則vLLM 的性能不是某個參數單獨決定的而是“顯存預算、批次大小、上下文長度”三者之間權衡的結果。我建議按順序調這三個參數--gpu-memory-utilization決定 vLLM 能占用多少顯存。留太少KV Cache 不夠并發能力上不去留太多會和桌面環境搶顯存導致其他應用崩潰。我一般設 0.85。--max-model-len直接決定單請求最長上下文。不需要超長上下文時調低它給 KV Cache 騰空間效果立竿見影。--max-num-seqs控制一次推理 batch 里最多有多少個請求。默認值通常會比較保守顯存寬裕時可以適度調高吞吐量隨之上升。下面這組是我在 24GB 顯存顯卡上實測比較舒服的配置vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 16384 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 64 \ --enable-prefix-caching--enable-prefix-caching開啟后重復的 prompt 前綴比如系統提示詞、固定模板會被緩存多輪對話場景下能省不少計算量。這個參數沒有副作用建議常開。6.2 常見問題排查表遇到報錯先看這張表現象可能原因解決辦法啟動報 CUDA out of memory顯存不足或max-model-len太大調低--max-model-len降--gpu-memory-utilization關掉其他吃顯存的應用加載模型時提示找不到量化配置模型目錄不完整或 config.json 讀取失敗檢查目錄文件完整性或顯式加--quantization fp8服務起來了但 curl 不返回端口被占用或請求地址錯誤換端口確認model字段與實際--served-model-name一致WSL2 內能訪問但 Windows 瀏覽器打不開老版本 WSL2 網絡模式不同新版本一般自動轉發不行就用netsh interface portproxy做端口轉發啟動特別慢日志卡在讀模型模型放在/mnt/c跨盤讀取把模型挪到 WSL2 內部目錄重新下載或復制多卡設置--tensor-parallel-size 2報 NCCL 錯誤WSL2 下多卡通信支持不穩定單卡先別開多卡或考慮 Docker Linux 環境Python 依賴沖突、torch 版本不對手動裝了 torch重開虛擬環境直接uv pip install vllm讓 pip 自動解析依賴6.3 WSL2里跑vLLM特有的三個坑第一個坑是顯存不釋放。Windows 桌面端一旦有進程加載了 CUDA 上下文即使程序退出了顯存也可能被系統占用一段時間。vLLM 啟動前先打開任務管理器看一眼如果顯存被某個殘留進程占著用wsl --shutdown重啟一下 WSL2 實例狀態會干凈很多。第二個坑是/mnt/c文件系統性能很慢。Windows 的 NTFS 掛載到 WSL2 里走的是 9P 協議IO 性能遠不如 WSL2 原生的 ext4。模型下載到 Linux 文件系統里看起來只是換個目錄的事實際體驗差異巨大模型放對了地方加載時間能差出一倍。所以我的習慣是模型一定放~/models絕不放/mnt/c/Users/xxx/...。第三個坑是 WSL2 的 IP 和端口轉發問題。新版本 WSL2 默認使用鏡像網絡模式mirrored networkingWindows 側直接訪問 localhost 就能通。如果你遇到 Windows 側始終訪問不了 WSL2 里的服務可以先在 WSL2 里執行ip addr show eth0拿到 WSL2 的 IP再從 Windows 訪問這個 IP 加端口實在不行再上端口轉發。6.4 一個簡單壓測看看Qwen3-8B-FP8能跑多快配置好以后我想大家都會好奇模型到底跑多快。這里分享一組我自己的實測數據僅供參考硬件與配置場景實測結果RTX 4090 24GBmax-model-len16384單請求流式生成500 token 輸出約 80-110 tokens/s同一配置并發 16 個請求批量推理整體吞吐總吞吐可以到 800 tokens/s2048 token prompt 預填充prefill 階段約 4000-6000 tokens/s數據會隨著輸入長度、并發數、驅動版本有波動但趨勢很明確單請求的速度取決于內存帶寬并發時 Continuous Batching 能把吞吐量拉得很高。這也是 vLLM 在生產環境里真正的價值所在——它不是把單次生成做多快而是讓 GPU 在大量請求面前不被浪費。如果你也想驗證自己的環境可以用 Python 并發發十幾個請求對比一下整體耗時就能直觀感受到“批量處理”和“逐個排隊”的巨大差異。這個測試不要在生產服務器上做本地開發機完全沒問題。寫到這里我發現自己每次在 Windows 上折騰這類工具最后都會得出同一個結論Windows 從來不是不能做只是很多坑需要人到場踩一遍才知道怎么繞。按我這套流程走下來你應該能在半小時到一小時左右跑通 Qwen3-8B-FP8然后再按自己的硬件條件微調那三個性能參數把它變成一臺真正能用的本地模型服務。如果你在啟動過程中遇到上面表格里沒寫到的報錯建議優先把完整日志發到 vLLM 的 GitHub issue 里搜一搜很多問題都有現成的討論和結論。最后再分享一個小技巧把啟動命令和常用參數寫成一個 shell 腳本放進 WSL2 的~/.local/bin里下次啟動模型服務只需要一行命令不用再翻歷史記錄找參數了。 Windows上跑通vLLM部署Qwen3-8B-FP8的完整實操指南
說句實在話vLLM 這東西放到 Linux 上是真省心裝好驅動和 Python 環境pip install vllm就能把模型服務跑起來但如果你手里只有一臺 Windows 機器情況就開始變得有意思了。我在 Windows 上跑通 Qwen3-8B-FP8 之前翻了不少資料也踩了不少坑——vLLM 官方對 Windows 的支持長期停留在“實驗性”階段很多教程看了開頭就不想繼續。這篇文章是我完整的實操記錄從一臺 Windows 11 機器開始通過 WSL2 部署 vLLM把 Qwen3-8B-FP8 這個 FP8 量化模型拉起來暴露成 OpenAI 兼容的 HTTP API然后用 curl、Python requests 和 OpenAI SDK 三種方式完成調用。整個過程對顯存和系統要求說得比較清楚適合手里有 16GB 及以上顯存、又暫時不想換 Linux 環境的讀者。1. 為什么要在Windows上折騰vLLM想清楚再動手1.1 vLLM是什么為什么它這么挑環境vLLM 是目前大模型推理服務里使用率非常高的一個開源框架核心賣點是 PagedAttention 和 Continuous Batching。PagedAttention 這個機制你可以理解成“給顯存做虛擬內存”把 KV Cache 切成小塊按需分配解決了長上下文推理時顯存碎片化的問題Continuous Batching 則是把多個請求動態拼成一個 batch 去推理而不是等前一個請求完全結束才接下一個。這兩點疊加起來讓 vLLM 在并發場景下的吞吐量比樸素的推理腳本高出很多。但 vLLM 從誕生起就把 Linux 當成“默認生存環境”因為它的高性能路徑依賴 Linux 下成熟的 CUDA 生態比如 FlashAttention、NCCL、各種自定義算子。Windows 上不是不能跑只是很多算子需要單獨編譯碰上 FlashAttention 這類對編譯器版本敏感的庫一個坑接一個坑。社區從某個版本開始提供了 Windows 下的實驗性支持但性能沒法和 Linux 比綜合體驗也不穩定所以我的建議非常直接生產環境用 LinuxWindows 上想快速體驗就用 WSL2。WSL2 本質上就是 Windows 內置的輕量虛擬機里面跑的是真正的 Linux 內核。對顯卡用戶來說NVIDIA 驅動在 Windows 和 WSL2 之間是共享的WSL2 里可以直接拿到 GPU 的 CUDA 能力性能損耗很小。所以我選擇了 WSL2 路線而不是折騰原生 Windows 版 vLLM也不是再套一層 Docker。1.2 Windows上跑vLLM的三條路線對比這里我把常見的幾條路線拉出來對比一下方便你根據自己情況選。路線優點缺點適合場景WSL2 原生安裝 vLLM性能接近 Linux配置簡單社區資料最多需要先了解 WSL2虛擬磁盤占空間個人開發、跑實驗、學習部署Docker Desktop vLLM 鏡像環境隔離最干凈團隊復制方便多一層虛擬化磁盤占用更大已有 Docker 習慣或要做交付Windows 原生安裝 vLLM不用虛擬化路徑最直接官方支持實驗性算子編譯容易出問題只跑極小模型或者想嘗鮮我個人推薦 WSL2。理由不復雜性能上它最接近原生 Linux而且 vLLM 官方文檔里的常見問題、GitHub issue 基本都是圍繞 Linux 環境你在 WSL2 里遇到問題照著 Linux 的解決方案改一改就能用。Docker 路線雖然隔離性好但 GPU 透傳、鏡像版本、磁盤空間這些變量疊加起來排查起來更費勁不適合新手起步。1.3 Qwen3-8B-FP8為什么選這個模型當案例Qwen3-8B 是通義千問第三代的 8B 參數模型指令跟隨和代碼能力都很能打8B 這個規模意味著它對單卡用戶非常友好。FP8 是它的量化版本權重用 8 位浮點數E4M3存儲相比 BF16 版本的 8B 模型權重文件直接減半顯存占用明顯下降推理時內存帶寬壓力也更小而質量損失在大部分場景下很難感知到。這套組合對 Windows vLLM 實戰來說特別合適模型權重合計約 8GB 左右FP8 加載后顯存占用更小16GB 顯存能跑得比較寬松24GB 顯存可以留出大量空間給 KV Cache 做長上下文。相比那些動輒需要多卡部署的大模型Qwen3-8B-FP8 在成本和效果之間平衡得很好作為第一個跑通的模型不會讓你在硬件上就被勸退。2. 環境準備WSL2、驅動、Python環境一次配好2.1 開啟WSL2并安裝Ubuntu發行版在開始之前確認你的 Windows 版本。Windows 10 2004 及以上、Windows 11 都能直接用官方命令裝 WSL2如果你的系統比較老建議先手動開啟“適用于 Linux 的 Windows 子系統”和“虛擬機平臺”這兩個 Windows 功能再安裝 WSL2 內核更新包。我個人最常用的方式是管理員身份打開 PowerShell執行wsl --install -d Ubuntu-22.04如果之前沒有安裝過 WSL這個命令會自動啟用相關 Windows 功能、安裝 WSL2 內核并下載 Ubuntu 發行版。整個過程可能需要重啟一次。重啟后第一次進入 Ubuntu 會讓你設置用戶名和密碼這個用戶默認有 sudo 權限后續大部分操作都要在這個 Linux 環境里完成。裝完以后例行檢查wsl -l -v輸出結果里應該看到 Ubuntu 的 VERSION 列是 2。如果顯示的版本是 1需要用下面命令把默認版本切到 2wsl --set-default-version 2這里有個很容易忽略的細節WSL2 和 WSL1 對 GPU 的支持完全不同只有 WSL2 才有真正的 GPU 透傳能力切到 2 這一步別跳過。2.2 檢查顯卡驅動與CUDA環境WSL2 里不需要單獨安裝 NVIDIA 的 Linux 驅動這是一個讓很多人意外的點。你只需要在 Windows 側裝好 NVIDIA 官方驅動WSL2 里的 nvidia-smi 會自動對應到同一個驅動層。裝完驅動后進入 Ubuntu 終端執行nvidia-smi能看到顯卡型號和驅動版本就說明 GPU 透傳沒問題。我踩過的一個坑是驅動太老vLLM 加載時直接報 CUDA 版本不兼容后來把驅動升級到最新版才消停。建議你在動手前就把驅動更新到 550 或更高版本省得后面排查。vLLM 的 pip 安裝包已經自帶了 CUDA runtime 相關的庫所以你在 WSL2 里不需要手動安裝完整的 CUDA Toolkit只要顯卡驅動新到能支撐當前 CUDA 版本就行。這一點和原生 Linux 部署略有區別很多人在這里白白浪費了大量時間去裝 CUDA其實裝完 vLLM 之后CUDA 相關的東西基本都被 pip 依賴自動帶上了。2.3 Python環境準備用uv管理依賴更省心WSL2 里通常自帶 Python 3.10 或 3.12但直接拿系統 Python 裝 vLLM 容易出現依賴沖突。我的習慣是先裝 uv它是目前處理 Python 依賴速度最快、也最省心的工具之一。在 Ubuntu 的終端里執行curl -LsSf https://astral.sh/uv/install.sh | sh安裝好后創建一個虛擬環境并激活uv venv .venv source .venv/bin/activate后續所有 pip 安裝都走uv pip install不僅快還能避免很多 Python 包版本打架的問題。如果你更習慣 conda也不是不行但我實測下來 uv 在 WSL2 里體感更輕、裝大包時不容易超時。2.4 顯存、磁盤和基礎資源檢查開始部署之前建議先確認三件事顯存、磁盤空間、內存。nvidia-smi看顯存Qwen3-8B-FP8 權重約 8GB啟動時 vLLM 還會根據你的設置劃走一部分顯存做 KV Cache所以 16GB 顯存是起步線24GB 會比較舒服。磁盤方面模型倉庫加運行日志至少預留 20GB而且強烈建議放在 WSL2 內部的 Linux 文件系統里不要放在/mnt/c這種 Windows 掛載盤上跨文件系統讀寫會讓模型加載速度肉眼可見地變慢。內存建議至少有 16GB因為模型加載過程中需要先讀入內存再拷貝到顯存內存太小會出現看著像卡死、實際上在瘋狂換頁的表現。3. 安裝vLLM與下載Qwen3-8B-FP8模型3.1 安裝vLLM一行命令背后的版本選擇在剛才創建并激活的虛擬環境里安裝 vLLMuv pip install vllm默認會安裝當前最新穩定版我寫這篇實操時是 0.9.x。如果你希望更穩妥可以指定一個已知大版本號uv pip install vllm0.9,0.10官方 PyPI 上的 vLLM wheel 體積不小安裝耗時較長。國內網絡環境下如果下載慢或者超時可以臨時切換到清華 PyPI 鏡像uv pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple裝完以后驗證版本python -c import vllm; print(vllm.__version__)能正常輸出版本號說明 vLLM 主體安裝成功。這里有一個非常關鍵的細節vLLM 和 PyTorch 的版本綁定關系比較強你不需要也不應該手動指定 torch 版本直接裝 vllm 會讓 pip 自動解析出配套的 torch。手動亂裝 torch 很容易把環境搞崩回頭排查依賴沖突才是最耗時間的。3.2 下載Qwen3-8B-FP8模型兩條國內可用的路徑模型推薦直接下載到 WSL2 內部路徑用類似~/models/Qwen3-8B-FP8這種目錄。第一條路徑是使用 Hugging Face 的國內鏡像站點 hf-mirror。通過環境變量把下載源指到鏡像export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download Qwen/Qwen3-8B-FP8 --local-dir ~/models/Qwen3-8B-FP8如果你沒裝 huggingface_hub先執行uv pip install huggingface_hub。第二條路徑是 ModelScope。Qwen 系列在 ModelScope 上有官方倉庫下載速度在國內相當樂觀pip install modelscope modelscope download --model Qwen/Qwen3-8B-FP8 --local_dir ~/models/Qwen3-8B-FP8兩條路我都實測過ModelScope 對國內網絡更友好Hugging Face 鏡像勝在模型目錄結構和 vLLM 生態天然一致。下載完成后確認目錄里至少有 config.json、tokenizer.json 和若干個 .safetensors 權重文件缺文件的話后續加載一定會報錯。3.3 模型文件完整性與路徑規劃模型下載好以后我建議把路徑固定在一個地方避免每次啟動都找半天。比如統一放到~/models/下那么 vLLM 啟動時直接用--model ~/models/Qwen3-8B-FP8指定本地路徑即可不用每次寫完整的 HF 倉庫名。另外一個容易被忽略的點是vLLM 加載本地模型目錄時會自動讀取目錄里的 config.json里面已經包含了 FP8 量化的配置信息。也就是說正常情況下你不需要手動指定--quantization fp8vLLM 會自己識別。這點和加載某些第三方量化模型時需要手動傳參的體驗不太一樣對新手更友好。4. vLLM服務啟動實戰參數逐項拆解4.1 最小化啟動命令先跑通再說在 WSL2 終端里確保虛擬環境已激活然后執行vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000如果一切正常你會看到 vLLM 先加載模型權重再初始化推理引擎最后輸出類似下面的日志INFO: Started server process [12345] INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000看到Application startup complete就說明服務已經起來了。用瀏覽器打開http://localhost:8000再訪問/health或/healthz路徑通常能返回健康檢查狀態。不過“先跑通”的命令只是最小集實際使用中很少這樣裸跑。你大概率會遇到顯存不夠用、上下文長度不合適、端口被占用等問題。下面我把關鍵參數逐個拆開講你不需要全記住先按自己的硬件情況挑幾個改動跑通一次后再回頭細看就好。4.2 關鍵啟動參數說明每個參數為什么值得調參數作用我的建議--model指定模型路徑或 HF 倉庫名本地路徑更穩定建議用絕對路徑--host/--port服務監聽地址和端口默認 0.0.0.0:8000注意端口沖突--max-model-len模型最大上下文長度顯存緊張時設 8192 或 16384 立省顯存--gpu-memory-utilization允許 vLLM 占用顯存的比例默認 0.9單卡共享機器可以降到 0.6-0.7--tensor-parallel-size使用幾張卡做張量并行單卡千萬別設大于 1多卡也要謹慎--quantization強制指定量化方式本模型可省異常時顯式用fp8--served-model-name對外暴露的模型名稱方便對接已有客戶端配置--trust-remote-code允許加載倉庫里的自定義代碼部分模型需要Qwen 一般不需要--api-key為 API 增加訪問密鑰暴露公網時強烈建議開啟之所以把--max-model-len單獨拎出來說是因為這個參數對顯存影響巨大。Qwen3-8B 原生支持 32K 上下文但如果你只是做日常問答、代碼生成大部分請求的上下文也就是幾千 token。把--max-model-len從 32768 降到 8192KV Cache 占用直接少一大截在 16GB 顯存上體感非常明顯。4.3 FP8量化在vLLM里的處理細節Qwen3-8B-FP8 的 config.json 里自帶quantization_configvLLM 加載時會自動識別。如果你在日志中看到模型被當作 BF16 加載說明量化信息沒被正確解析這時候可以顯式指定vllm serve ~/models/Qwen3-8B-FP8 \ --quantization fp8 \ --kv-cache-dtype fp8_e4m3--kv-cache-dtype fp8_e4m3的作用是把 KV Cache 也切成 FP8 存儲進一步壓顯存。這個選項在 Ada Lovelace 及以上架構的顯卡上支持比較好如果你的顯卡是 RTX 30 系建議先不開啟實測一部分場景會有兼容性問題。另外注意FP8 權重在推理時會反量化回更高精度做計算所以它不會像整型量化那樣明顯犧牲模型質量這也是 FP8 這兩年被大規模采用的原因之一。在 vLLM 里使用 FP8 模型你不需要改動任何業務代碼API 層面和普通模型完全一致。4.4 啟動日志怎么看快速判斷服務健康狀態剛開始跑的時候日志非常長很多人一刷屏就慌了。其實不需要逐行讀重點盯這幾類信息顯存分配情況日志里會顯示類似GPU memory usage: xxx或Number of GPU blocks如果這里的數字很小說明可用 KV Cache 空間不足并發能力會受限模型加載完成提示出現Load avg weights took ...表示權重加載完成這里時間太久的話要懷疑是不是模型放到了/mnt/c下Starting vLLM server at ...和Application startup complete這兩行是服務可用的信號。如果啟動過程中卡在某一步不動大概率就是網絡問題還在下載或者顯存不足。前者檢查模型路徑是否指向本地目錄后者看 nvidia-smi 確認顯存沒被其他進程占滿。4.5 讓服務在后臺運行nohup和tmuxWSL2 終端一旦關閉前臺運行的 vLLM 服務也會跟著退出。為了避免反復重啟我習慣用 nohup 把服務放到后臺并把日志寫進文件nohup vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 8192 \ vllm.log 21 要查日志就看tail -f vllm.log想殺掉服務就pkill -f vllm serve。這個操作方式在 Windows Terminal 里配合 WSL2 使用很順手不需要額外裝工具。5. 調用推理接口OpenAI兼容API從curl到SDK5.1 用curl快速驗證30秒確認服務正常vLLM 啟動后暴露的是 OpenAI 兼容 API所以最簡單的驗證方式就是 curl。打開一個新的終端Windows PowerShell 也可以因為 localhost 是通的curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3-8B-FP8, messages: [ {role: user, content: 用一句話解釋什么是PagedAttention} ], max_tokens: 128, temperature: 0.7 }返回 JSON 里會出現choices[0].message.content字段里面就是模型生成的回答。這一步能通說明整個服務鏈路已經問題不大了。如果你啟動時指定了--served-model-name這里model字段要用你指定的名字。5.2 用Python requests調用不依賴額外庫很多人寫 demo 不想引入 OpenAI SDK那就直接用 requestsimport requests url http://localhost:8000/v1/chat/completions payload { model: Qwen3-8B-FP8, messages: [ {role: user, content: 寫一段Python代碼實現快速排序} ], max_tokens: 512, temperature: 0.3 } response requests.post(url, jsonpayload) data response.json() print(data[choices][0][message][content])注意返回結構里content是最終拼接好的完整回答。requests 的json參數會自動設置 Content-Type不用手動加 header這一點比 curl 命令省事。5.3 用OpenAI SDK調用復用現有代碼如果你的項目本來就用了 OpenAI 的 Python SDK只需要改一下 base_urlfrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) completion client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: system, content: 你是一個樂于助人的助手。}, {role: user, content: 介紹一下Qwen3主力模型的特點} ] ) print(completion.choices[0].message.content)api_key 填一個占位字符串就行因為 vLLM 默認不校驗密鑰。如果你啟動時設置了--api-key記得把這里換成真實密鑰。這套寫法最大的價值在于以后你想換成其他 OpenAI 兼容服務比如別的推理框架或云廠商接口代碼幾乎不用動。5.4 流式輸出實戰類ChatGPT打字機效果非流式接口要等模型完整生成完才返回長響應時會明顯感受到延遲。流式輸出可以讓 token 一個接一個蹦出來體感和 ChatGPT 網頁版接近。用 OpenAI SDK 的話只需加一個streamTruefrom openai import OpenAI client OpenAI( api_keyEMPTY, base_urlhttp://localhost:8000/v1 ) stream client.chat.completions.create( modelQwen3-8B-FP8, messages[ {role: user, content: 寫一段500字左右的產品介紹} ], streamTrue ) for chunk in stream: delta chunk.choices[0].delta.content if delta: print(delta, end, flushTrue)底層原理是 SSEServer-Sent EventsvLLM 會把每個生成的 token 通過 HTTP 長連接實時推給客戶端。對 Web 前端來說解析 SSE 流把內容渲染到頁面就可以了。流式響應對長文本生成體驗改善非常明顯建議對接業務時優先考慮。6. 性能調優與Windows/WSL2踩坑實錄6.1 性能和顯存之間的取舍三個關鍵參數先說明一個原則vLLM 的性能不是某個參數單獨決定的而是“顯存預算、批次大小、上下文長度”三者之間權衡的結果。我建議按順序調這三個參數--gpu-memory-utilization決定 vLLM 能占用多少顯存。留太少KV Cache 不夠并發能力上不去留太多會和桌面環境搶顯存導致其他應用崩潰。我一般設 0.85。--max-model-len直接決定單請求最長上下文。不需要超長上下文時調低它給 KV Cache 騰空間效果立竿見影。--max-num-seqs控制一次推理 batch 里最多有多少個請求。默認值通常會比較保守顯存寬裕時可以適度調高吞吐量隨之上升。下面這組是我在 24GB 顯存顯卡上實測比較舒服的配置vllm serve ~/models/Qwen3-8B-FP8 \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 16384 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 64 \ --enable-prefix-caching--enable-prefix-caching開啟后重復的 prompt 前綴比如系統提示詞、固定模板會被緩存多輪對話場景下能省不少計算量。這個參數沒有副作用建議常開。6.2 常見問題排查表遇到報錯先看這張表現象可能原因解決辦法啟動報 CUDA out of memory顯存不足或max-model-len太大調低--max-model-len降--gpu-memory-utilization關掉其他吃顯存的應用加載模型時提示找不到量化配置模型目錄不完整或 config.json 讀取失敗檢查目錄文件完整性或顯式加--quantization fp8服務起來了但 curl 不返回端口被占用或請求地址錯誤換端口確認model字段與實際--served-model-name一致WSL2 內能訪問但 Windows 瀏覽器打不開老版本 WSL2 網絡模式不同新版本一般自動轉發不行就用netsh interface portproxy做端口轉發啟動特別慢日志卡在讀模型模型放在/mnt/c跨盤讀取把模型挪到 WSL2 內部目錄重新下載或復制多卡設置--tensor-parallel-size 2報 NCCL 錯誤WSL2 下多卡通信支持不穩定單卡先別開多卡或考慮 Docker Linux 環境Python 依賴沖突、torch 版本不對手動裝了 torch重開虛擬環境直接uv pip install vllm讓 pip 自動解析依賴6.3 WSL2里跑vLLM特有的三個坑第一個坑是顯存不釋放。Windows 桌面端一旦有進程加載了 CUDA 上下文即使程序退出了顯存也可能被系統占用一段時間。vLLM 啟動前先打開任務管理器看一眼如果顯存被某個殘留進程占著用wsl --shutdown重啟一下 WSL2 實例狀態會干凈很多。第二個坑是/mnt/c文件系統性能很慢。Windows 的 NTFS 掛載到 WSL2 里走的是 9P 協議IO 性能遠不如 WSL2 原生的 ext4。模型下載到 Linux 文件系統里看起來只是換個目錄的事實際體驗差異巨大模型放對了地方加載時間能差出一倍。所以我的習慣是模型一定放~/models絕不放/mnt/c/Users/xxx/...。第三個坑是 WSL2 的 IP 和端口轉發問題。新版本 WSL2 默認使用鏡像網絡模式mirrored networkingWindows 側直接訪問 localhost 就能通。如果你遇到 Windows 側始終訪問不了 WSL2 里的服務可以先在 WSL2 里執行ip addr show eth0拿到 WSL2 的 IP再從 Windows 訪問這個 IP 加端口實在不行再上端口轉發。6.4 一個簡單壓測看看Qwen3-8B-FP8能跑多快配置好以后我想大家都會好奇模型到底跑多快。這里分享一組我自己的實測數據僅供參考硬件與配置場景實測結果RTX 4090 24GBmax-model-len16384單請求流式生成500 token 輸出約 80-110 tokens/s同一配置并發 16 個請求批量推理整體吞吐總吞吐可以到 800 tokens/s2048 token prompt 預填充prefill 階段約 4000-6000 tokens/s數據會隨著輸入長度、并發數、驅動版本有波動但趨勢很明確單請求的速度取決于內存帶寬并發時 Continuous Batching 能把吞吐量拉得很高。這也是 vLLM 在生產環境里真正的價值所在——它不是把單次生成做多快而是讓 GPU 在大量請求面前不被浪費。如果你也想驗證自己的環境可以用 Python 并發發十幾個請求對比一下整體耗時就能直觀感受到“批量處理”和“逐個排隊”的巨大差異。這個測試不要在生產服務器上做本地開發機完全沒問題。寫到這里我發現自己每次在 Windows 上折騰這類工具最后都會得出同一個結論Windows 從來不是不能做只是很多坑需要人到場踩一遍才知道怎么繞。按我這套流程走下來你應該能在半小時到一小時左右跑通 Qwen3-8B-FP8然后再按自己的硬件條件微調那三個性能參數把它變成一臺真正能用的本地模型服務。如果你在啟動過程中遇到上面表格里沒寫到的報錯建議優先把完整日志發到 vLLM 的 GitHub issue 里搜一搜很多問題都有現成的討論和結論。最后再分享一個小技巧把啟動命令和常用參數寫成一個 shell 腳本放進 WSL2 的~/.local/bin里下次啟動模型服務只需要一行命令不用再翻歷史記錄找參數了。