系列第 1 篇（共 4 篇）｜難度：L2-進階

前置知識：基本 Linux/終端機操作、Python 環境、知道什麼是 LLM 推論與 OpenAI API 格式。

一句話說明

vLLM 是一台「會自己做批次」的高吞吐 LLM 伺服器——你用它把一個開源模型架成一個 OpenAI 相容的 API，讓很多人同時打也不會卡。

如果 Ollama 是「在你筆電上跑個模型玩玩」，那 vLLM 就是「把模型架成正式服務，扛得住一票人同時用」。

這一篇不談底層理論（PagedAttention、continuous batching 那些留到後面），只帶你：搞清楚什麼時候該從 Ollama 換到 vLLM、把第一個服務跑起來、看懂啟動指令每個參數在幹嘛。

先搞清楚：vLLM 和 Ollama 到底差在哪

很多人第一個問題是「我已經有 Ollama 了，為什麼要學 vLLM？」

一句話：Ollama 是給「人」用的，vLLM 是給「服務」用的。

什麼時候該換？

• 🟢 繼續用 Ollama：只有你自己用、跑在筆電/沒有像樣 GPU、只是想試模型效果。
• 🔴 該換 vLLM：要架成 API 給多人或後端服務用、有一張（或多張）GPU、在意「同時很多人打的時候還快不快」。

白話比喻：Ollama 像家裡的瓦斯爐，一次煮一兩人份很方便；vLLM 像餐廳的爐灶，一次出幾十份也穩。你自己吃不需要餐廳爐灶，但要開店就得換。

環境需求：先確認你有沒有本錢跑

vLLM 幾乎是為 GPU 而生的。動手前先確認三件事：

1. 有 NVIDIA GPU 且裝好驅動——跑 nvidia-smi，看得到你的顯卡和 CUDA 版本才算過關。
2. 顯存夠不夠——這是最容易翻車的地方。模型參數量 × 每個參數的位元組數，大概就是最低顯存需求。一個粗略的抓法：

> 7B 模型用 FP16（半精度）跑，光模型權重就約 14GB，再加上 KV cache 和其他開銷，實務上要抓 16GB 以上顯存才比較安全。

1. Python 環境——建議用虛擬環境（venv 或 uv），別直接裝進系統 Python。

安裝與冒煙測試

# 建個乾淨的虛擬環境（這裡用 uv，換成 venv 也行）
uv venv && source .venv/bin/activate

# 裝 vLLM（它會一起帶進對應的 PyTorch / CUDA 相依）
pip install vllm

# 冒煙測試：確認裝起來、import 得到、版本印得出來
python -c "import vllm; print(vllm.__version__)"
Code language: PHP (php)

✅ **這在幹嘛**：最後那行 python -c "..." 是「一句話 Python」——不進互動模式，直接跑引號裡的程式。能印出版本號，代表 vLLM 至少裝對了、載得進來。印不出來（報錯）就別往下走，先把環境修好。

跑起第一個服務：vllm serve

裝好之後，一行指令就能把模型架成一個 OpenAI 相容的 API：

vllm serve Qwen/Qwen2.5-7B-Instruct

逐段翻譯

• vllm serve：啟動 vLLM 的 API 伺服器模式。
• Qwen/Qwen2.5-7B-Instruct：要載入的模型。這是 Hugging Face 上的模型 ID（組織名/模型名），vLLM 會自動幫你下載。

跑起來後，預設會在 http://localhost:8000 開一個服務，而且長得跟 OpenAI 的 API 一模一樣。這點很重要——意思是你原本打 OpenAI 的程式碼，幾乎只要改個網址就能改打你自己的 vLLM。

⏳ 第一次跑會卡很久很正常——它在下載幾 GB 到幾十 GB 的模型權重。看到類似 Uvicorn running on http://0.0.0.0:8000 這行，才代表服務真的起來了。

打通它：curl 與 Python

用 curl 打（最快確認服務活著）

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "你好，一句話自我介紹"}]
  }'
Code language: PHP (php)

逐行翻譯：

• /v1/chat/completions：這就是 OpenAI 的聊天 API 路徑，vLLM 原封不動照抄。
• -H "Content-Type: application/json"：告訴伺服器「我送的是 JSON」。
• -d '{...}'：要送出去的內容。model 要跟你 serve 時的模型 ID 一致，messages 是對話內容。

用 Python 的 OpenAI SDK 打（實務上都這樣接）

from openai import OpenAI

# 重點：base_url 指到你自己的 vLLM，不是 OpenAI
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY",   # vLLM 預設不驗證金鑰，隨便填一個非空字串即可
)

resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=[{"role": "user", "content": "你好，一句話自我介紹"}],
)

print(resp.choices[0].message.content)
Code language: PHP (php)

這段在幹嘛：用官方 openai 套件，但把 base_url 換成本機的 vLLM。除了這一行，其他寫法跟你打真正 OpenAI 完全一樣——這就是「OpenAI 相容」最實際的好處：你的應用程式碼幾乎不用改。

📌 **知道就好**：api_key="EMPTY" 是因為 vLLM 預設沒開驗證。這代表**任何能連到這個位址的人都能用你的模型**——上線前務必加上 --api-key 或用反向代理擋一層（後面會提）。

看懂啟動參數：AI 幫你生指令時，你要看得懂

實務上 vllm serve 後面常常掛一串參數。AI 幫你生出來的指令，你至少要看懂這四個最常見的：

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --tensor-parallel-size 2

逐個白話

• --gpu-memory-utilization 0.9：跟 vLLM 說「這張卡的顯存，你最多用九成」。留一成給系統和其他程式喘息。不是設 0.9 就一定用滿，而是設一個上限。
• --max-model-len 8192：一次對話（你問的 + 它答的）加起來最多 8192 個 token。設太大很吃顯存，設太小長文會被截。
• --tensor-parallel-size 2：一張 GPU 裝不下 70B 這種大模型時，用兩張卡把模型「切開」一起扛。這個數字不能超過你實際有的 GPU 數量，也通常要能整除模型的注意力頭數（設錯會直接啟動失敗）。

✅ **必看懂**：--gpu-memory-utilization 和 --max-model-len 這兩個是你最常被迫調整的，因為它們直接關係到「跑不跑得起來」。

📌 **知道就好**：--tensor-parallel-size 只有你玩多卡 / 大模型時才用得到，單卡跑 7B 用不到。

🚩 第一次跑不起來的紅旗

AI 生的啟動指令「看起來永遠很對」，但 vLLM 對硬體很誠實——不對就是起不來。以下是最常撞的幾個，教你認得症狀、知道下一步。

🔴 紅旗 1：OOM（顯存爆了）

torch.OutOfMemoryError: CUDA out of memory.
Code language: CSS (css)

為什麼：模型 + KV cache 要的顯存超過你的卡。這是 vLLM 新手第一名死因。

怎麼救（由溫和到激進）：

1. 調低 --gpu-memory-utilization（如 0.85）——有時只是留給系統的太少。
2. 調小 --max-model-len（如從 8192 降到 4096）——KV cache 直接省一半。
3. 換更小的模型，或用量化版本（後面篇章會談）。

跟 AI 這樣說：「我的 GPU 只有 16GB 顯存，跑 7B 模型 OOM 了，幫我調整 --max-model-len 和 --gpu-memory-utilization，並解釋為什麼這樣改。」

🔴 紅旗 2：max-model-len 超過模型上限

ValueError: User-specified max_model_len (32768) is greater than
the derived max_model_len (8192) ...

為什麼：你設的 --max-model-len 超過這個模型本身支援的上下文長度。不是顯存問題，是設定值本身不合法。

怎麼救：把 --max-model-len 設回模型支援的範圍內（錯誤訊息裡的 derived max_model_len 就是上限）。

跟 AI 這樣說：「這個模型的最大上下文長度是多少？我的 --max-model-len 設多少才合法？」

🟡 紅旗 3：Port 被占用

[Errno 98] Address already in use
Code language: CSS (css)

為什麼：8000 埠已經有東西在跑（可能是上一次沒關乾淨的 vLLM，或別的服務）。

怎麼救：換個埠 --port 8001，或先把占用 8000 的程序關掉（lsof -i:8000 找出來）。

跟 AI 這樣說：「8000 埠被占用了，幫我改用別的埠啟動，並提醒我打 API 時網址要跟著改。」

🟡 紅旗 4：api_key="EMPTY" 直接上線

client = OpenAI(base_url="http://0.0.0.0:8000/v1", api_key="EMPTY")
Code language: JavaScript (javascript)

看到服務綁在 0.0.0.0（對外全開）又沒設金鑰，代表任何連得到的人都能免費用你的 GPU。本機測試無所謂，但要對外就是紅旗。

跟 AI 這樣說：「這個服務要對外開放，幫我加上 --api-key 驗證，並說明還有哪些安全設定該補（例如限制綁定位址、加反向代理）。」

Vibe Coder 驗收檢查點

跟著做，做得到就代表你這篇通關了：

1. 確認裝好：跑
2. 確認服務起來：跑 vllm serve <你的模型> 後，終端機出現 Uvicorn running on http://0.0.0.0:8000 這類訊息。
3. 確認打得通：另開一個終端機跑上面的 curl 指令，應該收到一段 JSON，裡面 choices[0].message.content 有模型的回答。
4. 確認自己看得懂參數：把你的啟動指令貼給 AI，問「這幾個參數各自在控制什麼？如果我 OOM 了該先動哪一個？」——你要能判斷它的回答對不對，而不是照單全收。

看不懂就這樣問 AI

「用白話解釋 vllm serve 這行指令的每個參數在幹嘛，我是第一次用 vLLM，只有一張 16GB 的 GPU。」

「我跑 vLLM 出現這個錯誤（貼上錯誤訊息），這是顯存不夠、參數設錯、還是埠被占用？下一步該怎麼做？」

「我原本這段程式碼是打 OpenAI 的（貼上程式碼），要改成打我本機的 vLLM 服務，需要改哪幾行？」

小結

• vLLM 和 Ollama 不是誰取代誰：自己玩用 Ollama，架服務用 vLLM。分野在「要不要扛併發」。
• vLLM 幾乎綁 GPU，跑之前先確認顯存夠不夠——這是最容易翻車的點。
• vllm serve <模型> 一行就能開一個 OpenAI 相容 的 API，你原本的程式改個 base_url 就能接。
• 四個必認參數：--model、--gpu-memory-utilization、--max-model-len、--tensor-parallel-size。前兩個關係到「跑不跑得起來」，最常被迫調。
• 跑不起來時的四大紅旗：OOM、max-model-len 超上限、埠被占、金鑰全開。認得症狀，就知道該問 AI 什麼。

下一篇，我們會進到「怎麼讓它跑得更快、更省」——調參數、看吞吐量指標，把這台伺服器榨出價值。