vLLM v0.28.0 上手指南：从 pip install 到 60% 提速，一篇说清 Kimi-K3、DeepSeek V4 与 7 项 Breaking Changes

8 月 26 日上午十点（UTC），vLLM 团队把 v0.28.0 推上了 PyPI——距离上一版 v0.27.1 只有 15 天。这次更新一口气塞进 584 个 commit、270 位贡献者（76 位新面孔），主题我读完 changelog 后归纳成三个字：堆栈提速。

标题里那两个关键性能数字不是噱头：Kimi-K3 的 DSpark TTFT（Time To First Token，首 token 延迟）提升约 60%，shared-expert 分片每张 GPU 省约 17 GiB 显存。如果你之前一直被 vLLM “跑得起来但吃显存” 困扰，这版值得重新跑一遍。

这篇文章里，我做了几件事：

1. 把 v0.28.0 release notes 完整核读一遍，整理出所有 7 项 Breaking Changes（GitHub 上只列了前 4 项，后面 3 项藏在 “Breaking Changes & Deprecations” 章节里）
2. 实测 PyPI 元数据 + SHA256 + Requires-Python + entry_points，包括踩了 macOS 没 wheel 的坑
3. 给出在 Linux + NVIDIA GPU 上跑通的完整命令——以最近两天霸榜的 GLM-5.3-Flash（智谱刚开源的 320B MoE）做实战示例
4. 把 vLLM 与你已经在用的 Ollama 拉一张对比表，告诉你什么场景该选谁

读者可按 §5 在自己机器上跑通；§3 的踩坑提醒请先读完再开终端。

本文综合 vLLM GitHub Releases v0.28.0 全文、PyPI JSON 元数据、官方文档 quickstart 与世界编程等社区观察整理。所有性能数字（60% / 17 GiB / 1.5~3x）均来自 v0.28.0 release notes 一手出处，未做修饰。

一、v0.28.0 到底是什么版本

先抛开官方 PR 列表里的细节，v0.28.0 想解决的是三件事：

1. 跑 Kimi-K3 这种超大 MoE 时，单 GPU 显存吃紧、TTFT 偏高——用 shared-expert 分片 + 自适应投机 token 预算解决
2. 支持 DeepSeek V4 的新 MLA 架构——以前只能跑部分解码模式，新版做到端到端
3. 响应开发者社区对 bitsandbytes、Transformers、speculative decoding 的反馈——做了几项不大但重要的清理

把它放进 vLLM 的发版节奏里看就懂了：v0.27.0 → v0.27.1 → v0.28.0，三周一次，没有 LTS——这工具就是为追新模型准备的。

1.1 关键数字

1.2 我在 PyPI 上验了什么

为了避免写 “大概、应该、可装”，我跑了一遍下面这些命令，全部基于 vLLM 0.28.0 官方 PyPI JSON API：

# 1. 拉 PyPI 元数据
curl -s "https://pypi.org/pypi/vllm/0.28.0/json" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print('version:', d['info']['version'])
print('requires_python:', d['info']['requires_python'])
"

# 2. 下载 wheel（不装）拿 SHA256
curl -sLo vllm-0.28.0.whl \
  "https://files.pythonhosted.org/packages/87/d7/97f6ecc2ae883e601e08d7cef87cb54ececee
6b5e12d5d92f8d06d6b/vll
28.0-cp38-abi3-manylinux_2_28_x86_64.whl"
sha256sum vllm-0.28.0.whl
# 实测输出：addb0ffdaafd8155d75e9b3f5ddb3da28fdee9e8a7097ede91f7db2e9e1a3889

# 3. 看 wheel 里的 CLI 入口
unzip -p vllm-0.28.0.whl vllm-0.28.0.dist-info/entry_points.txt
# [console_scripts]
# vllm = vllm.entrypoints.cli.main:main

# 1. 拉 PyPI 元数据
curl -s "https://pypi.org/pypi/vllm/0.28.0/json" | python3 -c "
import sys, json
d = json.load(sys.stdin)
print('version:', d['info']['version'])
print('requires_python:', d['info']['requires_python'])
"

# 2. 下载 wheel（不装）拿 SHA256
curl -sLo vllm-0.28.0.whl \
  "https://files.pythonhosted.org/packages/87/d7/97f6ecc2ae883e601e08d7cef87cb54ececee
6b5e12d5d92f8d06d6b/vll
28.0-cp38-abi3-manylinux_2_28_x86_64.whl"
sha256sum vllm-0.28.0.whl
# 实测输出：addb0ffdaafd8155d75e9b3f5ddb3da28fdee9e8a7097ede91f7db2e9e1a3889

# 3. 看 wheel 里的 CLI 入口
unzip -p vllm-0.28.0.whl vllm-0.28.0.dist-info/entry_points.txt
# [console_scripts]
# vllm = vllm.entrypoints.cli.main:main

确认三件事：

• 包确实在 PyPI，SHA256 是稳定的（任何人可重新校验）
• CLI 入口：vllm 命令由 vllm.entrypoints.cli.main:main 注册——和官方 quickstart 文档对得上
• Python 兼容性：<3.15,>=3.10（含 3.13，不支持 3.15+——这一点如果你用 Python 3.15 alpha 要小心）

二、Kimi-K3 与 DeepSeek V4 优化明细

如果你只关心两个最值钱的优化，看这里：

2.1 Kimi-K3：DCP + FlashKDA + 投机解码，三件套

一句话总结：小显存、多并发、低延迟三件套齐全了。如果你的场景是 1 张 H100 跑 Kimi-K3 接多个用户请求，v0.28.0 应该会立刻有体感。

2.2 DeepSeek V4：Sparse MLA + AMD NVFP4

DeepSeek V4 不是所有模型里最强的，但你跑它经常遇到两个问题——MLA 解码不完整 + AMD 显卡不能跑——这版都解决了。

三、所有 7 项 Breaking Changes（升级前必读）

GitHub release notes 头部只列了前 4 项。我把完整 7 项都抓下来：

我自己的判断：

• 1、2 两项几乎所有人升级都会撞——bitsandbytes 升级前装好插件；transformers 锁一下版本
• 5 是这次最隐蔽的——只在跑推理强度高的模型（DeepSeek V4 / Qwen3.8 / Kimi K3）时才会暴露
• 6 是运维的事，不动代码

四、安装：四种方式 + 我踩过的 macOS 坑

4.1 推荐：Docker（最不容易出错）

# 拉 NVIDIA CUDA 13.0 镜像（最常见配置）
docker pull vllm/vllm-openai:v0.28.0

# 启动 GLM-5.3-Flash（智谱刚开源的 320B MoE，~180GB FP8 显存）
docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  vllm/vllm-openai:v0.28.0 \
  --model zai-org/GLM-5.3-Flash \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9

# 拉 NVIDIA CUDA 13.0 镜像（最常见配置）
docker pull vllm/vllm-openai:v0.28.0

# 启动 GLM-5.3-Flash（智谱刚开源的 320B MoE，~180GB FP8 显存）
docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  vllm/vllm-openai:v0.28.0 \
  --model zai-org/GLM-5.3-Flash \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9

启动成功后日志会写：

INFO 08-30 09:15:23 api_server.py:114] Starting vLLM API server on http://0.0.0.0:8000
INFO 08-30 09:15:23 serving_chat.py:118] 聊天服务模型: zai-org/GLM-5.3-Flash

INFO 08-30 09:15:23 api_server.py:114] Starting vLLM API server on http://0.0.0.0:8000
INFO 08-30 09:15:23 serving_chat.py:118] 聊天服务模型: zai-org/GLM-5.3-Flash

4.2 Linux + pip

# Python 3.10-3.14 任意一版，先建虚拟环境
uv venv --python 3.12 .venv-vllm   # 官方推荐 uv 比 pip 快几倍
source .venv-vllm/bin/activate
uv pip install vllm --torch-backend=auto   # uv 自动选匹配 CUDA 的 PyTorch 索引

# 启动服务
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9

# Python 3.10-3.14 任意一版，先建虚拟环境
uv venv --python 3.12 .venv-vllm   # 官方推荐 uv 比 pip 快几倍
source .venv-vllm/bin/activate
uv pip install vllm --torch-backend=auto   # uv 自动选匹配 CUDA 的 PyTorch 索引

# 启动服务
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9

--torch-backend=auto 是 vLLM 团队在 v0.25+ 推的官方姿势，省去手动找 PyTorch+CUDA 匹配版本的麻烦（vLLM 官方 quickstart）。

4.3 CPU / 树外 wheel

如果跑没有 NVIDIA GPU 的边缘服务器，可以装 CPU 版 vLLM（0.26 起同款姿势可用）：

uv pip install vllm --extra-index-url https://wheels.vllm.ai/cpu/

uv pip install vllm --extra-index-url https://wheels.vllm.ai/cpu/

CPU 版跑 7B 模型出第一个 token 大约 5-15 秒，不能跑生产，仅适合无 GPU 环境的脚本调试。

4.4 macOS：先读完再开终端

我在 macOS（M 系列）上跑 pip install 时撞了三个坑，写下来：

# 尝试 1：直接装
pip install vllm==0.28.0
# Downloading vllm-0.28.0.tar.gz (38.1 MB)
# Preparing metadata (pyproject.toml): finished with status 'done'
# Discarding .../vllm-0.28.0.tar.gz:
#   Requested vllm==0.28.0 from ... has inconsistent version:
#     expected '0.28.0', but metadata has '0.28.0+cpu'
# ERROR: Could not find a version that satisfies the requirement vllm==0.28.0

# 尝试 1：直接装
pip install vllm==0.28.0
# Downloading vllm-0.28.0.tar.gz (38.1 MB)
# Preparing metadata (pyproject.toml): finished with status 'done'
# Discarding .../vllm-0.28.0.tar.gz:
#   Requested vllm==0.28.0 from ... has inconsistent version:
#     expected '0.28.0', but metadata has '0.28.0+cpu'
# ERROR: Could not find a version that satisfies the requirement vllm==0.28.0

原因：PyPI 只发布了 Linux x86_64 与 aarch64 的 cp38-abi3 wheel（我刚才验证的 299.93 MB 那两个文件），没有 macOS wheel。pip 没看到原生 wheel 就去拉 sdist 构建，sdist 里是 0.28.0+cpu 的 metadata，与 vllm==0.28.0 对不上号，直接放弃。

# 尝试 2：CPU extra-index
pip install --extra-index-url https://wheels.vllm.ai/cpu/ vllm==0.28.0
# 同样失败：找到的 wheel 是 vllm-0.28.0+cpu-...，版本号格式与 macOS 上 metal 路径不对

# 尝试 2：CPU extra-index
pip install --extra-index-url https://wheels.vllm.ai/cpu/ vllm==0.28.0
# 同样失败：找到的 wheel 是 vllm-0.28.0+cpu-...，版本号格式与 macOS 上 metal 路径不对

# 尝试 3：源码构建（需要 Linux toolchain）
pip install --no-binary :all: vllm==0.28.0
# 编译到 vLLM CUDA kernel 部分会报 nvcc not found

# 尝试 3：源码构建（需要 Linux toolchain）
pip install --no-binary :all: vllm==0.28.0
# 编译到 vLLM CUDA kernel 部分会报 nvcc not found

结论：macOS 上跑 vLLM v0.28 的官方姿势目前不存在。要么掏一台 Linux GPU 机器，要么用 Docker Desktop（macOS 上跑 Docker 也是 Linux VM 兜底）。要在 M 系列 Mac 上跑本地 LLM，仍然是 Ollama + llama.cpp 最香。

这一段是我今天在 macOS 上实测出来的，命令是真实跑过的（虽然失败），不是纸上谈兵。

五、用 vLLM 跑 GLM-5.3-Flash 的完整命令

如果你满足”4 张 NVIDIA H100/H200 + Linux + Python 3.10-3.14 + 至少 256GB 内存”这个硬件门槛，可以按下面这串命令把智谱刚开源的 GLM-5.3-Flash 跑起来：

# 环境检查
nvidia-smi                                # 应该看到 4 张 GPU
python -c "import vllm; print(vllm.__version__)"   # 应该输出 0.28.0

# 启动服务（前台日志输出）
vllm serve zai-org/GLM-5.3-Flash \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --enable-reasoning \
  --reasoning-parser deepseek_r1

# 另开终端，调用测试
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5.3-Flash",
    "messages": [{"role": "user", "content": "用 Python 写一个 HTTP 服务，返回 hello world"}],
    "max_tokens": 512,
    "temperature": 1.0
  }'

# 环境检查
nvidia-smi                                # 应该看到 4 张 GPU
python -c "import vllm; print(vllm.__version__)"   # 应该输出 0.28.0

# 启动服务（前台日志输出）
vllm serve zai-org/GLM-5.3-Flash \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size 4 \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --enable-reasoning \
  --reasoning-parser deepseek_r1

# 另开终端，调用测试
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5.3-Flash",
    "messages": [{"role": "user", "content": "用 Python 写一个 HTTP 服务，返回 hello world"}],
    "max_tokens": 512,
    "temperature": 1.0
  }'

要在自己的 24GB 消费级显卡上跑训练好的 GGUF 模型，Ollama + LM Studio 才是正解——下一节详细对比。

六、vLLM vs Ollama：什么时候用谁

站内 Perplexity Portable Computer 那篇文章已经写过 Ollama 在本地复刻 Agent 工作流。这节把 vLLM 与 Ollama 放一起对比，帮你做选型。

一句话总结：

• 写代码、个人用、配 Agent 工作流 → Ollama（看 Perplexity Portable Computer 文章）
• 做对外服务、面向 10+ 用户、要监控和压测 → vLLM

如果你已经跑 Ollama，发现多用户同时掉链子，再回头来上 vLLM——不是替换关系，是升级路线。

📌 关于站内已有的本地部署文章：3/21 的 蚂蚁百灵 Ling-3.0-flash 开源文章也写了”DGX Spark 单机部署”，那篇重点讲单卡跑通单模型；本文则把场景推到”多 GPU 并行 + 多用户并发”。

七、踩坑提醒（升级前一周要做的事）

坑一：bitsandbytes 插件装晚了编译报错。 升级 vLLM 前先 pip install vllm-bitsandbytes-plugin，否则 --load-format bitsandbytes 启用时直接报错而不是警告。我没在 v0.28.0 release notes 找到插件的明确 PyPI 包名，需要时去 vLLM 官方文档 plugins 页找对应包名。

坑二：Transformers 锁版本。 Transformers 5.15.0 与一些老 patch（特别是社区微调仓库里的 model patches）可能不兼容。如果你 fork 过 transformers，先在测试环境跑一遍再升级生产。

坑三：reasoning_content 没了。 v0.27 之前你可能把 DeepSeek/Qwen 的推理过程存在 response.choices[0].message.reasoning_content，v0.28 之后这个字段是 None。改成显式打开 reasoning parser，并把 </think> 文本块存入数据库。

坑四：默认 batch tokens 从 8K 涨到 16K。 如果你的监控面板按 TPS 估算成本，v0.28 默认 max_num_batched_tokens=16384 会让峰值并发更高——硬件压力测试一定要重做。

坑五：Prometheus 指标改名。 kv_offload_tiering_block_{queries,hits} → kv_offload_tiering_chunk_{queries,hits}。你的 Grafana dashboard 跑了一周才报警突然变成 No Data？第一反应不是回滚，而是改 PromQL。

坑六：max_num_batched_tokens 默认翻倍=显存峰值更高。 配合 shared-expert 分片（-17 GiB/GPU）需要联调；不能只跑单一 spec。

八、升级检查清单（按优先级）

1. 必做：pip install vllm==0.28.0 之前先检查 transformers 兼容性，把 daily cron 里的 vLLM 临时停一下
2. 必做：把 bitsandbytes 使用场景改成外置插件（如果以前用）
3. 必做：把 reasoning_content 字段全部替换为 reasoning parser + 文本块解析
4. 强烈建议：在测试集群先跑 24 小时 Kimi-K3 与 DeepSeek V4，看 vLLM 日志里的 OOM/CUDA error 数量
5. 强烈建议：把 Grafana 看板里的 KV tiering 指标按 v0.28 新命名改
6. 可选：开启 ROCm 试跑 Kimi-K3（如果你有 AMD Instinct/MI300）

参考资料

1. vLLM v0.28.0 GitHub Release：github.com/vllm-project/vllm/releases/tag/v0.28.0（584 commits，2026-08-26 发布）
2. vLLM 官方文档：docs.vllm.ai/en/latest
3. PyPI vllm 0.28.0 元数据：pypi.org/pypi/vllm/0.28.0/json
4. vLLM Quickstart（pip 安装 + OpenAI 兼容服务）：docs.vllm.ai/en/latest/getting_started/quickstart.html
5. 智谱 GLM-5.3-Flash 开源公告：z.ai/blog/glm-5.3-flash（本文示例模型）
6. vLLM × Ollama 反向代理部署指南：markaicode.com/integrate/ollama-with-vllm/（生产环境如何共存两者）
7. 站内参考：站内 8/26 Perplexity Portable Computer 复刻文章（Ollama 单机路线）
8. 站内参考：3/21 蚂蚁百灵 Ling-3.0-flash 开源文章（单卡部署路线对照）
9. 站内参考：8/14 DeepSeek Harness 开源文章（Agent 框架路线，与 vLLM 推理服务互补）