速查表
| 报错关键词 | 真实原因 | 解法 |
|---|---|---|
Repo id must be in the form 'repo_name' | 模型路径不存在/写错 | 用绝对路径，先 os.path.isdir() 检查 |
User-specified max_model_len (X) is greater than the derived max_model_len | 上下文超过模型上限 | 把 max_model_len 调到上限内 |
No available memory for the cache blocks | 显存不够给 KV cache | 提高 gpu_memory_utilization 或降上下文 |
| 同样报上一条，但你没有改配置 | 同进程开了两个引擎 | 一个配置一个进程 |
ValidationError ... dtype | dtype 写了不支持的值 | 只用 auto/half/float16/bfloat16/float32 |
Engine core initialization failed | 引擎子进程崩了 | 往上看第一条真实错误 |
| 推理结果异常/卡死 | flashinfer sampler 兼容问题 | VLLM_USE_FLASHINFER_SAMPLER=0 |
Address already in use | 端口被占 | 换端口或杀掉旧进程 |
| 图片数超过限制时报错 | limit_mm_per_prompt 设太小 | 调大或按需传图 |
| 启动卡在 CUDA graph capture | 编译优化耗时 | 调参阶段用 enforce_eager=True |
下面每条都附真实报错原文（vLLM 0.30.0 / torch 2.13.0+cu130 / RTX 5070 Ti / Qwen2.5-VL-7B-AWQ 实测）。
1. 模型路径不存在
OSError: Repo id must be in the form 'repo_name' or 'namespace/repo_name':
'/home/zhms/models/does-not-exist'. Use `repo_type` argument if needed.
看到 Repo id must be in the form，别去查网络配置——它其实是"找不到本地目录"。vLLM 发现路径不存在，就当成 HuggingFace repo id 去解析，于是报这个。
解法：
import os
MODEL = "/home/zhms/models/Qwen2.5-VL-7B-Instruct-AWQ"
assert os.path.isdir(MODEL), f"模型目录不存在: {MODEL}"
2. 上下文长度超过模型上限
pydantic_core._pydantic_core.ValidationError: 1 validation error for ModelConfig
Value error, User-specified max_model_len (200000) is greater than the derived
max_model_len (max_position_embeddings=128000.0 or model_max_length=None in model's config.json).
我随手写了 max_model_len=200000，但这个模型的 max_position_embeddings 是 128000，直接不让启动。
注意：这个报错来自 pydantic 校验，堆栈很长，真正有用的是最后那句 Value error, ...。
解法：把 max_model_len 调到模型上限内（通常是 32768 或 128000，看 config.json）：
LLM(model=MODEL, max_model_len=32768) # 先查 config.json 的 max_position_embeddings
3. 显存不够给 KV cache
ValueError: No available memory for the cache blocks. Try increasing
`gpu_memory_utilization` when initializing the engine (this flag also controls
CPU memory reservation on the CPU backend, despite its name).
我故意把 gpu_memory_utilization 设成 0.01，模型权重加载完就没剩多少给 KV cache 了。
解法组合拳（按性价比排序）：
- 提高
gpu_memory_utilization（0.85 → 0.9） - 降低
max_model_len（KV cache 大小和上下文长度成正比） - 换量化模型（7B bf16 → AWQ，显存 14GB → 6.5GB）
4. 同进程开第二个引擎——报错和上一条一模一样
a = LLM(model=MODEL, gpu_memory_utilization=0.35)
b = LLM(model=MODEL, gpu_memory_utilization=0.35) # 挂在这里
报的还是 No available memory for the cache blocks，但这次不是你配置错，是第一个引擎没释放显存。
这个坑我调参时踩了：想在一个脚本里跑多组配置，结果第二组就崩。
解法：一个配置一个进程。外层用 bash/python 循环，每次 python bench_one.py --config X。
5. dtype 写了不支持的值
pydantic_core._pydantic_core.ValidationError: 2 validation errors for ModelConfig
dtype.literal['auto','half','float16','bfloat16','float','float32']
Input should be 'auto', 'half', 'float16', 'bfloat16', 'float' or 'float32'
[type=literal_error, input_value='float64', input_type=str]
vLLM 只支持这几个 dtype，float64 不在里面。报错里直接把合法值列出来了，照着改就行。
解法：dtype="bfloat16"（或直接 "auto" 让 vLLM 自己判断）。
6. Engine core initialization failed
Engine core initialization failed. See root cause above. Failed core proc(s): {}
这句话本身没有信息量，它只是说"引擎子进程崩了"。真正的原因在日志更上面——我第一次遇到时，往上翻 40 行才发现是显存不足。
排查方法：
# 只留错误行，跳过 INFO
vllm serve ... 2>&1 | grep -B5 -A5 "ERROR\|Error\|error" | head -60
7. 推理异常或卡死：flashinfer sampler 兼容问题
症状比较隐蔽：模型能加载、能启动，但生成结果异常、偶尔卡死或崩溃。
这套组合（vLLM 0.30 + flashinfer 0.6.18 + CUDA 13）下，关掉 flashinfer 的采样 kernel 就好了：
import os
os.environ.setdefault("VLLM_USE_FLASHINFER_SAMPLER", "0")
排查顺序：遇到"能启动但结果不对"的怪问题，先关这个开关，再怀疑模型本身。
8. 端口被占用
ERROR: [Errno 98] error while attempting to bind on address ('0.0.0.0', 8000): address already in use
vllm serve 默认 8000 端口，上一个进程没退干净就起不来。
解法：
lsof -i:8000 -t | xargs -r kill -9 # 杀旧进程
vllm serve ... --port 8001 # 或者换个端口
9. 图片数量超过 limit_mm_per_prompt
多模态场景设了 limit_mm_per_prompt={"image": 1}，但请求里塞了 2 张图——会在请求处理阶段报错。
解法：要么把限制调大，要么按限制传图：
LLM(..., limit_mm_per_prompt={"image": 2})
对"一条请求一张图"的批量场景，保持 {"image": 1} 最省显存——它不只是限制，也是显存保护。
10. 启动卡在 CUDA graph capture
启动日志刷屏：
Capturing CUDA graphs (FULL): 20%|██ | 7/35 [00:00<00:00, 18.20it/s]
首启动要编译并捕获 CUDA graph，26-44 秒很正常（我实测一个 7B 模型 37.5 秒）。
但如果你在快速调参、反复重启，这个时间很烦。用 enforce_eager=True 跳过：
LLM(..., enforce_eager=True)
代价呢？我实测过：吞吐 4.52 vs 4.58 张/秒，只慢 1%。调参阶段完全值得开。
附：排查方法论（比记住报错更有用）
① 永远看第一条 traceback，不要看最后一行
vLLM 的报错会被包装好几层，最后一行往往是"引擎崩了""初始化失败"这种废话。真正的错误在中间。
② 先缩小到最小复现
from vllm import LLM
LLM(model=MODEL) # 什么都不配，能起来吗？
能起来 → 逐个加参数找罪魁；起不来 → 环境/模型问题。
③ 一配置一进程
同进程多次初始化 vLLM 必炸（本文第 4 条）。
④ 记住三个高频"元凶"
- 显存（
gpu_memory_utilization+max_model_len的组合） - 版本（vLLM/torch/CUDA 三者关系）
- 路径（模型目录、tokenizer 文件）
版本与时效性
| 项 | 值 |
|---|---|
| vLLM | 0.30.0 |
| torch | 2.13.0+cu130 |
| 模型 | Qwen2.5-VL-7B-Instruct-AWQ |
| GPU | RTX 5070 Ti 16GB |
| 实测日期 | 2026-11-09 |
vLLM 迭代很快，报错文案和默认行为可能变化；遇到对不上的情况，以你版本的实际日志为准，重点看报错类型 + 关键词，别死记全文。
