1. 為什么是這個組合vLLM、DeepSeek與顯存焦慮我知道很多人都是從Ollama或者LM Studio開始玩本地大模型的那玩意兒確實方便點兩下就能跑起來一個Chat接口。但你一旦想把它放到生產(chǎn)環(huán)境、想讓并發(fā)請求別卡死、想真正吃滿一張卡而不是看著顯存瘋狂碎片化就會碰壁。這時候vLLM幾乎是必選項。我的第一套vLLM部署純粹是被顯存逼出來的——當(dāng)時用transformers直接跑一個70B量化模型單請求都要四五秒兩個請求一起來直接OOM氣得我差點摔鍵盤。后來換成vLLM同樣的卡同樣的模型并發(fā)上去了不說顯存占用反而降下來了。這背后的核心是它把KV Cache用PagedAttention管理成了一個個“顯存頁”像操作系統(tǒng)的虛擬內(nèi)存一樣按需分配而不是像transformers那樣一次性預(yù)留整塊顯存。這個概念你不需要背你只需要知道用vLLM跑生成模型同樣的硬件能塞下更長的上下文、扛住更高的并發(fā)。所以這篇文章我計劃從零開始帶著你走一遍完整的路環(huán)境準(zhǔn)備、安裝、啟動服務(wù)、顯存調(diào)優(yōu)最后把我踩過的幾個深坑也攤開講省得你再摔一遍。不管你是想本地部署DeepSeek還是想用Docker拉起一個OpenAI兼容接口看完這一篇應(yīng)該都能跑通。要注意的是這里講的不只是“敲幾條命令”更多是背后的判斷邏輯——為什么選這個鏡像版本、為什么參數(shù)這樣配、為什么顯存這么調(diào)。畢竟網(wǎng)上教程版本五花八門抄錯了項目就歇菜。2. 環(huán)境準(zhǔn)備GPU驅(qū)動、CUDA、Python版本三個坑位2.1 GPU驅(qū)動和CUDA先確認(rèn)你的卡能干什么vLLM目前的主力還是NVIDIA的CUDA環(huán)境AMD的ROCm和華為的昇騰也逐步支持了但你要是新手建議老老實實用CUDA。你的顯卡建議至少8GB顯存。8GB也能玩但只能跑很小尺寸的模型比如7B量化版上下文一長還是懸。我的主力是RTX 4090 24GB基本能跑DeepSeek-R1的AWQ量化版再大就得靠多卡了。安裝之前先用nvidia-smi看三樣?xùn)|西驅(qū)動版本、CUDA版本、顯存大小。你不需要精確記住每個CUDA對應(yīng)哪個驅(qū)動只需要保證驅(qū)動版本不低于你選擇的CUDA運(yùn)行時所需要的最低驅(qū)動。提示vLLM官方發(fā)布的wheel包通常對應(yīng)某一版CUDA比如cu12.1或cu12.4。如果你機(jī)器上的驅(qū)動版本太老vLLM會提示缺少CUDA動態(tài)庫直接加不了載。我見過一個朋友拿2019年的老驅(qū)動跑v0.6.x折騰一晚上沒跑起來實際就是驅(qū)動不認(rèn)PTX。2.2 Python版本別用客戶端嘗鮮版vLLM對Python版本有明確要求一般來說3.10到3.12比較穩(wěn)。我個人習(xí)慣用Anaconda管理環(huán)境因為分開環(huán)境真的能救命。你要是同時搞Ollama、transformers、Torch項目互相依賴沖突是家常便飯。我是這么建的conda create -n vllm_env python3.10 -y conda activate vllm_env為什么卡在3.10因為我吃過多版本兼容的虧。3.12雖然新但某些編譯型依賴比如flash-attn可能來不及出對應(yīng)wheel而3.10基本是各個大模型框架的“黃金版本”。你要是想用3.11或3.12也可以但出問題先別怪vLLM先查依賴兼容性。2.3 虛擬環(huán)境里的Torch選擇裝vLLM之前你機(jī)器上可能已經(jīng)有PyTorch了。但注意vLLM對Torch的版本約束很緊它要的torch版本是經(jīng)過它測試并編譯的你手頭升級過的torch沒準(zhǔn)會導(dǎo)致它加載時直接報一堆符號錯誤。穩(wěn)妥做法是在干凈的conda環(huán)境里安裝vLLM讓pip自動解析依賴它會給你裝一個特定版本的torch別用你自己的環(huán)境強(qiáng)行融合。這里要給新手一個心理準(zhǔn)備vLLM安裝過程中會拉下來一堆編譯好的二進(jìn)制包看起來占空間但這是正常的。它不像transformers那樣純Python調(diào)庫vLLM有大量CUDA擴(kuò)展安裝體積大加載也慢但換來的是推理吞吐。3. 安裝vLLMpip、源碼、Docker三條路3.1 pip直接裝最省心的選擇如果你的環(huán)境干凈最推薦的安裝方式就是pip。簡單到令人發(fā)指pip install vllm但這里有一個細(xì)節(jié)默認(rèn)的pypi包會跟著vLLM團(tuán)隊的發(fā)布節(jié)奏走你要指定版本的話就加后綴比如pip install vllm0.6.1.post1版本號里.post1這種就是修復(fù)了某個bug后的補(bǔ)丁版。我建議你先查一下官方GitHub的Release說明別直接裝最新未穩(wěn)定版本尤其在生產(chǎn)環(huán)境。vLLM迭代速度真的太快我見過0.5.x到0.6.x就把命令行參數(shù)改得全家不認(rèn)識的。如果你想用最新的CUDA優(yōu)化特性也可以指定源pip install vllm --extra-index-url https://download.pytorch.org/whl/cu124這樣能把配套的torch也定位到CUDA 12.4版本。3.2 源碼編譯只有特殊需求才走這條路源碼編譯能讓你改vLLM內(nèi)核代碼或者適配特殊硬件但對大多數(shù)人來說性價比極低。我編譯過一次光等flash-attention的編譯就午飯外賣都到了而且編譯失敗率不低。除非你是想給某個架構(gòu)打補(bǔ)丁或者要用最新的未發(fā)版功能不然直接pip裝吧真的。3.3 Docker安裝最推薦的老手方案這次我要特別強(qiáng)調(diào)Docker因為熱搜詞里出現(xiàn)了“docker vllm/vllm-openai:v0.27.1加載qwen3-embedding-0.6b”。用Docker的好處是把CUDA環(huán)境、Python版本、依賴全部封裝在鏡像里宿主機(jī)只需要裝好NVIDIA Container Toolkit。我之前在網(wǎng)吧式電腦上裝驅(qū)動搞得滿屏黑塊后來干脆服務(wù)器上全用Docker再也沒擔(dān)心過系統(tǒng)環(huán)境被搞壞。常用的官方鏡像長這樣docker pull vllm/vllm-openai:v0.27.1注意這個版本號不是vLLM的版本而是vLLM官方鏡像的發(fā)布版本。你需要去查看鏡像tag對應(yīng)關(guān)系比如v0.27.1這個鏡像內(nèi)置的可能是v0.6.x的vLLM。如果你要加載qwen3-embedding-0.6b這類嵌入模型也得確保鏡像版本足夠新。啟動一個vLLM服務(wù)容器最簡單是這樣docker run --gpus all \ -v ~/models:/models \ -p 8000:8000 \ vllm/vllm-openai:v0.27.1 \ --model /models/qwen3-embedding-0.6b \ --task embed注意我加了--task embed這是加載嵌入模型的必需參數(shù)。如果還是當(dāng)生成模型啟動它會嘗試訪問不存在的大模型配置文件然后bang。這個坑我在后面專門說。4. 啟動推理服務(wù)命令行參數(shù)里的門道4.1 最簡單的一行跑通一個生成模型先把最基礎(chǔ)的啟動學(xué)會。假設(shè)你拉了一個DeepSeek模型放在本地路徑/models/deepseek-r1-7b-awq啟動服務(wù)vllm serve /models/deepseek-r1-7b-awq \ --served-model-name deepseek \ --max-model-len 8192 \ --gpu-memory-utilization 0.9這條命令直接打開一個OpenAI兼容的HTTP服務(wù)默認(rèn)監(jiān)聽http://0.0.0.0:8000。你把--served-model-name改成一個響亮的名字后面請求時model字段就填這個名字。--max-model-len是上下文長度上限8192就是最多允許8192個token的輸入輸出。這個參數(shù)直接決定KV Cache占多少顯存設(shè)太大模型沒跑起來就爆顯存了。我一般設(shè)置一個期望值再根據(jù)實際顯存余量反推后面細(xì)說。--gpu-memory-utilization表示vLLM最多能用多少比例的顯存0.9就是90%。剩下10%留給模型權(quán)重和CUDA上下文。別設(shè)成1.0你不想系統(tǒng)畫UI都卡成PPT吧。4.2 并發(fā)與并行別以為默認(rèn)就夠用vLLM默認(rèn)是連續(xù)批處理continuous batching意思是多個請求進(jìn)來它會動態(tài)把它們拼成一個批次每個token生成完就退出新的請求再補(bǔ)進(jìn)來這樣吞吐最大化。但并發(fā)數(shù)到底能開多大由顯存和max-model-len共同決定。你可以顯式加--max-num-seqs控制最大并發(fā)序列數(shù)。比如--max-num-seqs 3232并發(fā)的意思是同時最多積壓32個對話請求。設(shè)太高會瘋狂擠占KV Cache進(jìn)而導(dǎo)致OOM或請求變慢。設(shè)太低浪費(fèi)吞吐。我一般做法先把并發(fā)調(diào)到最小跑幾個請求看顯存和延遲再逐步往上頂。如果你有兩張或多張卡可以用--tensor-parallel-size 2來張量并行把一張卡放不下的模型切到兩張卡上。這是分布式推理的基礎(chǔ)用法前提是你有PCIe連接多張卡。注意這個參數(shù)改動后每個請求的調(diào)度方式都會變顯存分配邏輯也不一樣后面調(diào)優(yōu)時得很小心。4.3 加載Embedding模型的特殊姿勢熱搜詞里“docker vllm/vllm-openai:v0.27.1加載qwen3-embedding-0.6b”這個使用場景很多人碰到。vLLM不只跑生成模型從0.6.x開始也能跑embedding模型。但你得顯式給它說明任務(wù)類型不然vLLM以為你的模型是個decoder-only大模型一頓狂加載然后報錯。具體啟動方式vllm serve /models/qwen3-embedding-0.6b \ --task embed \ --served-model-name qwen3-embedding \ --max-model-len 4096 \ --gpu-memory-utilization 0.8啟動之后你用OpenAI的embeddings接口調(diào)用curl http://localhost:8000/v1/embeddings \ -H Content-Type: application/json \ -d {model: qwen3-embedding, input: 你好世界}讓它返回向量。注意embedding模型通常對max-model-len很敏感太短的上下文可能導(dǎo)致句子被截斷太長又浪費(fèi)顯存。實際業(yè)務(wù)里建議按文本分布的中位數(shù)設(shè)定。5. 顯存調(diào)優(yōu)實戰(zhàn)從OOM到優(yōu)雅奔跑5.1 先搞懂顯存到底花在哪這可能是整篇文章最值得你反復(fù)看的部分。vLLM請求顯存大致分三塊模型權(quán)重、KV Cache、運(yùn)行時開銷CUDA上下文、激活值等。其中KV Cache是動態(tài)的也是調(diào)優(yōu)重點。它的計算邏輯里藏著兩個關(guān)鍵參數(shù)max-model-len和gpu-memory-utilization。vLLM會在啟動時根據(jù)這兩個值估算KV Cache能開多大然后給每一層預(yù)留若干塊。你給模型設(shè)的上下文越長KV Cache總?cè)萘吭骄o張能支持的并發(fā)請求越少。一個常見現(xiàn)象是你剛啟動服務(wù)時看著顯存余量挺大一跑長上下文對話就OOM。原因是vLLM預(yù)留的KV Cache塊被長序列吃光了新的請求無法分配新塊。錯誤信息往往是Request exceeds available block capacity。調(diào)這個問題的思路很直白要么縮短上下限要么調(diào)高顯存利用率要么開prefix caching省塊。5.2 參數(shù)組合拳max-model-len、gpu-memory-utilization、block-size我實際調(diào)試一個DeepSeek-7B量化模型時卡是RTX 409024GB模型權(quán)重大約6GB。啟動參數(shù)我這樣試第一次--max-model-len 32768 --gpu-memory-utilization 0.9結(jié)果顯存爆了根本起不來。因為wights加上預(yù)留的KV Cache太貪心CUDA直接報out of memory。改成--max-model-len 16384 --gpu-memory-utilization 0.85先能起來但并發(fā)4個請求時有一個超過一定長度會報block capacity不足。說明KV Cache還是不夠。再調(diào)開prefix caching--enable-prefix-caching這個功能會緩存相同前綴的KV Cache塊比如多輪對話里歷史部分重合很多能大幅降低重復(fù)計算。實際測試下來長對話場景的顯存壓力降了差不多40%。代價是額外一點管理開銷但絕對劃算。--block-size默認(rèn)是16 token的塊大小。你可以試著設(shè)置成8或32。塊越小碎片化越少但管理開銷越大塊越大長序列時分配效率更高但短序列浪費(fèi)放大。我平時固定用默認(rèn)16除非遇到特定碎片問題才去動它。5.3 量化方案從AWQ到FP8如果你模型權(quán)重就占了卡上大半顯存再怎么做KV Cache也是杯水車薪終極辦法是給權(quán)重瘦身。當(dāng)前最主流的做法是AWQ和GPTQ量化。AWQ在精度損失和性能之間平衡得不錯很多開源模型都有AWQ權(quán)重直接下。啟動AWQ模型非常方便只要模型是AWQ格式vLLM自動識別量化類型你什么都不用改vllm serve /models/deepseek-awq-4bit要是你用的是FP8權(quán)重新版vLLM支持--quantization fp8顯式指定。FP8比AWQ還能省一點顯存但硬件需要適配好我的卡和推理庫版本配合不太好FP8偶爾會慢一些得看具體型號。經(jīng)驗之談先跑AWQ穩(wěn)定第一再玩FP8提速提容量。5.4 Chunked Prefill把長輸入的顯存尖峰削掉長文本一次性進(jìn)入模型時Prefill階段會把一個超長提示詞變成一個巨大的激活矩陣瞬間把顯存頂?shù)奖?。vLLM從0.5.x開始支持chunked prefill意思是在CUDA層面把Prefill分塊處理避免出現(xiàn)顯存尖峰。啟動時加--enable-chunked-prefill然后你可以配一個--max-num-batched-tokens來控制一次處理多少token比如4096或8192。這個值設(shè)得太低會導(dǎo)致模型需要多次調(diào)度吞吐下降太高又回到尖峰問題。我的經(jīng)驗是先開著chunked prefill設(shè)成和max-model-len/8差不多再根據(jù)壓力測試微調(diào)。如果你的業(yè)務(wù)輸入大多是短文本那chunked prefill帶來的收益不明顯但長文檔問答場景里它幾乎是救命稻草你不想一個5萬token的法律文件直接把服務(wù)搞掛吧。6. 踩坑實錄部署DeepSeek到加載Embedding模型的彎路6.1 模型保存路徑亂套服務(wù)啟動即退我第二次部署DeepSeek時直接把Hugging Face緩存路徑當(dāng)作模型路徑丟給vLLM結(jié)果它一頓報錯說找不到safetensors文件。這是因為HF緩存目錄下面往往還有一層哈希目錄vLLM需要的是模型文件的上一級也就是包含config.json那個目錄。正確的做法是huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-7B --local-dir /models/deepseek-7b把模型完整拉到本地然后再傳給vLLM別讓它去緩存里猜。6.2 端口占用和鏡像版本對應(yīng)關(guān)系你在Docker里跑服務(wù)時如果8000端口被其他進(jìn)程占了vLLM會給你端口沖突的報錯但錯誤信息不太直觀。需要先用ss -lntp查是誰占著端口。鏡像版本和vLLM版本的對應(yīng)關(guān)系一定要看鏡像tag頁面或README別只看鏡像名字帶個v0.27.1就當(dāng)是vLLM版本號我吃過虧裝了個新鏡像命令卻按老寫法傳參結(jié)果新參數(shù)根本不認(rèn)識退出碼給個0日志里一片空。6.3 顯存明明沒占滿卻OOM有朋友跑來問我nvidia-smi顯示顯存才用了60%但vLLM還是OOM。這是因為vLLM的KV Cache預(yù)留在你看不到的地方nvidia-smi顯示的是當(dāng)前內(nèi)存占用而vLLM的block management把那40%預(yù)留給了未來的KV Cache。所以你在外面看顯存沒滿里面實際已經(jīng)分配完了。判斷是不是這種情況就看服務(wù)日志里的KV Cache相關(guān)指標(biāo)比如kv cache size和free block數(shù)量。用/v1/...接口問服務(wù)狀態(tài)其實vLLM自帶的/metrics接口能輸出prometheus格式指標(biāo)里面能看到KV Cache利用率這才是判斷顯存壓力的第一手?jǐn)?shù)據(jù)。6.4 加載Embedding模型老報錯其實是任務(wù)類型忘寫熱搜詞里那個操作不算復(fù)雜但翻車概率很高用Docker鏡像跑qwen3-embedding-0.6b怎么傳都報錯。最常見就是忘了加--task embedvLLM默認(rèn)認(rèn)為你要跑生成模型于是嘗試找generation_config和lm_head等自然失敗。加了--task embed后還要確認(rèn)鏡像支持0.6.x之后的版本一般沒問題0.5.x就別想了。還有一個小坑embedding的并發(fā)癥是--max-model-len設(shè)太大顯存本來就緊結(jié)果每個embedding請求還占了一大塊KV Cache對embedding也會分配序列KV Cache只是生成階段短。所以加載embedding模型時顯存利用率不要調(diào)滿適當(dāng)留buffer比如設(shè)0.7否則多個embedding并發(fā)也會OOM。6.5 長上下文對話無故變慢檢查前綴緩存部署完DeepSeek后我發(fā)現(xiàn)多輪長對話越跑越慢。后來看了監(jiān)控發(fā)現(xiàn)大部分時間不是生成慢而是每一輪都把歷史全部重新算了。開了--enable-prefix-caching之后相同會話前綴能復(fù)用緩存的KV塊實際多輪速度提升非常明顯顯存占用也降了。如果你跑的是智能客服、代碼助手這種高頻多輪場景一定要測這個參數(shù)。注意prefix caching不是免費(fèi)午餐。它會額外記錄緩存塊的管理信息對多樣化的用戶輸入可能收益不大但如果你的對話風(fēng)格有大量重復(fù)歷史收益遠(yuǎn)大于開銷。7. 我的壓箱底調(diào)優(yōu)流程與補(bǔ)充建議最后分享一個我實際跑業(yè)務(wù)時反復(fù)打磨出來的調(diào)優(yōu)套餐你可以直接抄第一步先用最小參數(shù)起來服務(wù)vllm serve /models/你的模型 \ --max-model-len 4096 \ --gpu-memory-utilization 0.7第二步拿一個典型長文本樣本打進(jìn)服務(wù)觀察顯存和延遲。如果正常逐步把--gpu-memory-utilization往上加比如0.75、0.8、0.85。第三步把--max-model-len提高到目標(biāo)值比如16384再壓并發(fā)到預(yù)期水位。一旦出現(xiàn)KV Cache不足的報錯就不要硬頂了去調(diào)低單請求長度或加更多緩存復(fù)用策略。第四步對于生成類模型優(yōu)先開--enable-chunked-prefill和--enable-prefix-caching這兩個參數(shù)組合下來長文本場景能扛住更多并發(fā)。補(bǔ)充一個很多人忽略的點vLLM的日志很重要你別跑起來就不管了。我習(xí)慣在啟動命令里加上--log-stats --log-requests它會周期性輸出當(dāng)前服務(wù)的token吞吐、KV緩存利用率、排隊請求數(shù)。有了這些數(shù)據(jù)調(diào)參就能變成“看儀表盤”而不是“瞎猜”。再提一句Docker部署時的資源限制。如果你在Kubernetes里跑容器別只設(shè)置limits.memory還要給limits.nvidia.com/gpu: 1。另外把host IPC設(shè)置成hostIPC: true防止shared memory不夠?qū)е聉LLM加載數(shù)據(jù)時卡住。這個坑我遇到過一次服務(wù)起來了但加載大模型總在某個進(jìn)度條卡死后來才發(fā)現(xiàn)是默認(rèn)共享內(nèi)存只有64MB。對于顯存真的很緊張的小顯卡用戶我的建議是優(yōu)先調(diào)低max-model-len這比換量化方案還簡單。你想想如果業(yè)務(wù)里單個用戶最多只發(fā)2000字你卻給模型開32768的上下文那純粹是自找麻煩。此外啟動模型前最好確認(rèn)模型的chat_template是否正確。DeepSeek這類模型默認(rèn)模板在Hugging Face上一般沒問題但從別的渠道下載的老文件可能模板是空的會導(dǎo)致服務(wù)能起、請求卻報錯。你可以用tokenizer_config.json里的chat_template字段核對。寫到這里我回想起自己第一次啟動vLLM時對著滿屏英文日志手足無措的樣子。其實只要你把環(huán)境、版本、參數(shù)這三件事控制住剩下的都是水磨工夫。希望這篇經(jīng)驗?zāi)軒湍闵倮@幾個彎早點把模型真正用起來而不是一直在折騰部署。