很多人上 vLLM 是自己拼命令，跑通了也不知道对不对；等要上并发、换硬件、多机多卡时才发现示例里早就给了更省事的写法。这篇按「先跑什么、再看什么、最后改什么」整理仓库示例的阅读路径，并说明哪些示例只适合单机试水、哪些前提不满足时不该硬套。
很多人上 vLLM 是自己拼命令，跑通了也不知道对不对；等要上并发、换硬件、多机多卡时才发现示例里早就给了更省事的写法。这篇按「先跑什么、再看什么、最后改什么」整理官方仓库示例的阅读路径。
同时说清哪些示例只适合单机试水、哪些前提不满足时不该硬套。示例的价值不在照抄，而在于帮你快速建立一个可验证的起点。
进仓库先看哪几块：把示例分成四类
把仓库里的东西分成四类看：单机起服务的入口脚本、离线批量推理的调用示例、OpenAI 兼容接口的客户端示例、部署与分布式相关的配置示例。分类清楚之后，找东西的速度会明显提升。
- 入口脚本
- 单机把服务拉起来的启动命令，验证环境是否可用
- 离线调用示例
- 不依赖端口的批量推理脚本，用来确认权重与显存没问题
- 客户端示例
- 按兼容接口写的请求代码，决定业务侧怎么接
- 分布式配置示例
- 多卡多机的参数组合，只有真上规模才需要展开
- 先确定自己属于哪一类：只想本地验证模型能不能跑，就只看前两类。
- 要对外提供接口，第三类是必须抄的。
- 要上多卡多机，第四类才需要展开，否则容易越看越乱。
- 别一上来就翻目录深处的实验性脚本，那部分命名和参数变化快，跟不上你的版本。
- 仓库 README 里的 quickstart 和 examples 目录不是一回事：前者是最小可跑路径，后者是能力清单。
第一遍跑示例的正确姿势：先离线、后服务
先用离线批量推理的示例验证模型能加载，原因是它不依赖端口、并发和网关，出问题只可能是权重或显存。这一步跑通，后面排查范围会小很多。
- 跑离线示例用仓库里给出的批量推理脚本，只替换模型标识，其余保持默认；观察输出是否完整。
- 起服务确认离线跑通后再起服务，把示例里的模型标识替换成你实际要部署的那个。
- 换模型验证同一个示例换模型不改参数就跑，是最常见的翻车点；换完先小批量试。
- 算显存显存不够时不要急着改量化，先按示例的默认档位算一遍自己的卡能不能装下，具体算账路径到 /models/deploy 过一遍。
跑通的判断标准是输出内容和并发行为符合预期，不是「进程没报错」。这两者的区别，在压测阶段会非常明显。
服务与接口示例：客户端怎么写才和线上一致
服务示例重点看三处：启动参数、健康检查路径、以及接口的兼容程度；客户端示例重点看请求体字段和流式处理方式。这三处决定你接进业务后能不能稳定跑。
| 关注点 | 看什么 | 不达标会怎样 |
|---|---|---|
| 启动参数 | 默认值与你机器的匹配度 | 参数失真，压测数字参考价值低 |
| 健康检查 | 示例给的检查路径与返回 | 探活误判，实例被误杀 |
| 接口兼容 | 支持的请求字段与返回结构 | 业务侧按另一套习惯调用，接不上 |
| 流式处理 | 增量返回的拼接方式 | 长输出场景下客户端卡住或丢内容 |
把示例客户端直接搬进业务前，先量一遍你这条链路的延迟基线，用 /tools/speed-test 拉一个自己的参考值，否则后面调优没有对比物。示例里给的是最简请求，实际业务要补超时、重试和并发上限；这三项不补，压测数字好看上线就崩。
- 接口兼容范围要写清，避免对方按另一套调用习惯来接。
- 超时值按你最长的那种请求来定，不要按平均值定。
- 重试要有上限，否则故障时会放大流量。
- 并发上限先拦在网关层，别指望客户端自觉。
这些示例别照抄：不适用的几种情况
示例多为单机单实例的演示，没有覆盖生产的多实例、限流、灰度与回滚，别把演示配置当上线配置。这一点在你要接真实流量时必须提前想清楚。
- 示例默认的并行和显存参数是针对特定卡型的经验值，换成别的卡或别的量化档位后必须重新调，不能沿用。
- 示例里带实验性质或标记为预览的功能，接口可能在你下次升级时变；用在长期项目上要留替换方案。
- 要判断不同推理框架的分工差异，参考 vllm-ollama-llamacpp-pick 和 vllm-vs-ollama-inference-pick 的结论，别在这篇里找选型答案。
- 上线前的问题排查顺序可以对照 vllm-deploy-error-troubleshoot 走一遍，能省掉大量猜测。
- 示例不负责告诉你成本能不能接受，这部分要单独看。
把示例变成自己的调试节奏
建立三个固定动作：改一个参数、记一次结果、留一份可回退的配置；示例本身不负责帮你做这件事。有了节奏，示例才真正变成你自己的工具。
- 改一个参数一次只动一个，避免多个变量同时变化导致结果无法归因。
- 记一次结果把当时的配置和输出摘要写进同一条记录，别只记结论。
- 留可回退配置每次改动前保留一份可用配置，出问题能快速回到上一个状态。
- 升级后重跑每次升级版本后重新跑一遍最小示例，确认旧参数没被废弃。
把示例里可复用的部分抽成自己的启动脚本和配置模板，而不是每次从仓库复制粘贴。具体模型、量化档位与硬件的适配情况，别凭印象定，去 /models 和 /compute/gpus 核对当时的清单。
下一步把你手头要部署的模型和卡型带到站内清单里核一遍，再决定从哪个示例开始跑。→常见问题
仓库示例那么多，第一次上手只看哪几个就够了？
够用的一条线是：先看离线批量推理的示例确认模型能加载，再看起服务的示例把接口跑起来，最后扫一眼客户端示例确认调用格式。其余的分布式、多机、实验性示例，等你确实遇到并发或扩卡需求再回头看，前期看只会增加干扰。
示例能跑通，是不是就说明我的部署没问题？
不能。示例验证的是「能跑」，不是「能扛」。并发上限、长请求超时、显存碎片、多实例负载这些示例通常不覆盖。跑通之后至少要自己压一轮，量出延迟和吞吐基线，再决定要不要调参数。
为什么同样的示例换了个模型就报错？
最常见的原因是模型权重格式、量化档位和上下文长度这三项和示例默认值不一样，其次是显存装不下导致加载阶段就失败。排查顺序是先确认权重能被识别，再确认显存够用，最后再看参数是否需要跟着模型调整。
