你手里有一张或多张卡，想把本地权重变成一个能被现有代码直接调的 OpenAI 兼容接口，第一反应是用 Docker 跑 vLLM。真正卡人的通常不是命令本身，而是模型路径怎么挂、参数写哪个、起完到底通没通、报错该从哪一层看。这篇按「准备—启动—验证—排查」的顺序给一份可照做的清单，不替你做选型结论。
你手里有一张或多张卡，想把本地权重变成一个能被现有代码直接调的 OpenAI 兼容接口，第一反应通常是用 Docker 跑 vLLM。这条路本身不复杂，真正卡人的是模型路径怎么挂、参数写哪几个、起完到底通没通、报错该从哪一层看。多数人第一次起服务的失败都集中在挂载、端口、卡数这三处，跟模型本身关系不大。
这篇按「准备—启动—验证—排查」的顺序给一份能照做的清单，每一步都写清楚看什么、验什么。它不替你做硬件和模型选型，也不承诺某个组合一定快，只帮你把启动这一步走顺、把失败原因缩小到一层。做完之后你应该能自己判断服务是不是真的可用，而不是看到容器没退出就当成功。
起容器之前先把四件事对齐
很多翻车不是发生在命令里，而是发生在命令之前。动手敲命令前先在心里把四件事对齐：卡能不能被容器看到、权重从哪来、服务对外长什么样、版本口径怎么统一。任何一件没对齐，后面都会表现成一堆看着无关的报错。
- 卡与驱动
- 先在宿主机跑一次显卡状态检查，确认驱动正常，再决定用哪种 GPU 直通方式；容器里看不到卡，九成是这一步没做
- 权重形态
- 本地目录和可下载的仓库标识，挂载与缓存写法不同；离线机器要提前把权重放进挂载目录，别指望容器自己联网拉
- 对外形态
- 端口映射到宿主哪个端口、要不要鉴权、宿主上是否已有服务占着同一端口，这三件先定好再起
- 版本口径
- 镜像标签与权重格式会互相影响，支持范围去站内资料库对照，别凭印象挑标签
版本这块最容易偷懒，也最容易返工。术语层面先去 /ai-dict/category/infra 把概念对齐，再看 /models 里该模型的资料页，确认它的权重格式和加载要求，不要凭截图或别人的命令直接抄。
启动命令与关键参数怎么下笔
一条能跑起来的最小结构其实很短：镜像、挂载的权重目录、映射端口、要加载的模型标识，四样齐全就够了，其余都是调优。建议先按默认值起，确认接口能响应之后再逐个加参数，一次只改一个变量，方便回退对比。
docker run --gpus all -p 8000:8000 -v /本地/权重目录:/models --name vllm-openai vllm/vllm-openai:latest --model /models --served-model-name mymodel| 参数分组 | 包含什么 | 怎么定 |
|---|---|---|
| 加载类 | 模型路径、权重格式、张量并行度 | 并行度与卡数对齐，别凭感觉写 |
| 服务类 | 监听地址、端口、并发与显存占用上限 | 显存别一次占满，留余量再压并发 |
| 对外兼容类 | 接口前缀、鉴权开关、允许来源 | 先决定是否对外，再决定开不开鉴权 |
张量并行度和卡数对不上，是最常见的起不来原因之一。卡多并行度小会浪费，卡少并行度大会直接失败，而且报错未必直白。显存占用上限也一样，先留出余量，等服务稳了再往上压，别一上来就顶满。
怎么确认「真的起了」而不是只是没报错
容器没退出不等于服务可用。验证要分三层走：容器日志出现服务就绪提示，只是第一层；宿主机发一个健康检查类请求拿到正常响应，是第二层；再用一段最小的对话请求跑通一次完整推理，才算第三层。
- 看日志就绪提示在容器日志里找到监听与就绪相关的输出行，注意它绑定的地址和端口，别和你映射的端口对不上
- 打健康检查请求从宿主机访问映射出来的端口，确认能拿到正常响应而不是连不上或超时，这一步能筛掉端口映射问题
- 跑一次最小推理把本地接口当成普通 OpenAI 兼容端点，先列模型，再发一次最小对话请求，确认返回结构和字段齐全
- 量一次基线用 /tools/speed-test 量一遍延迟和吞吐基线，作为后续改参数的对照，别等到上线才第一次测
对外暴露前先把鉴权想清楚：没有鉴权就只绑内网或回环地址，别顺手映射到公网；要开鉴权就把密钥写进环境变量或密钥文件，别留在命令历史里。这一步看起来是运维细节，实际是唯一能挡住误用的门槛。
起不来时的排查顺序
排查顺序反了，就会在一堆参数里反复试。正确顺序是：先看容器有没有加载到卡，再看权重路径或格式对不对，最后才怀疑参数值不合理。按这个顺序走，通常两三步就能定位到具体一层。
| 现象 | 大概率层级 | 先从哪查 |
|---|---|---|
| 容器秒退 | 入口或运行时 | 看入口命令、镜像标签、GPU 运行时支持 |
| 日志停在加载权重 | 路径或显存 | 确认挂载目录、权重格式、显存上限 |
| 服务起来了但请求超时 | 端口映射或监听地址 | 核对映射端口与日志里的绑定地址 |
- 版本类问题单独放一层：镜像、驱动、权重三者对不上时报错往往含糊，别猜，用日志关键词去站内词条查概念
- 排查要留痕：每次改动的命令和结果抄一行进笔记，同类报错第二次出现直接对照
- 改一个变量测一次，避免一次改多处导致分不清是哪一处起了作用
- 拿不准的术语和参数含义，先查站内资料再动手，省下的时间比试错多
概念层面的含糊别硬扛，去 /ai-dict/category/tech 和 /ai-dict 把术语查清再动手。很多时候报错信息里的关键词本身就是答案，只是你还没对上对应的概念。
常见问题
容器里看不到显卡怎么办
先回到宿主机确认显卡状态正常，再检查容器运行时是否装了 GPU 支持、启动时有没有把卡直通进去。这两步都没问题，才去看镜像本身是否带对应运行时。顺序反了容易怀疑镜像，其实问题在宿主机这一层。
服务能起但客户端调不通怎么排
先确认宿主端口和容器监听端口是否一致，再确认客户端调的接口前缀和模型标识有没有对上。这两项都正常，再看鉴权和允许来源设置。把客户端请求原样换成宿主机上的最小请求对比，能快速区分是网络问题还是参数问题。
下一步把这份清单走完只是第一步，真正省时间的是持续追踪各家接口与中转站的口径变化。想知道当时的价格与可用性对比，去站内价格追踪页面核对当时的数字，比记在笔记里可靠。→常见问题
用 Docker 起 vLLM 一定要开鉴权吗？
不是必须，但要看你把它暴露给谁。同一台机器本地开发、只绑回环地址或内网地址，可以不开；只要映射到公网或者给多人共用，就一定要加鉴权并配合防火墙或反向代理。判断标准很简单：这个端口如果被陌生人扫到，他能不能直接白用你的卡。
容器里跑得好好的，外面却连不上，通常差在哪？
先分两步看：容器内部自己访问接口通不通，通说明服务没问题，问题在端口映射或监听地址。常见原因是服务只监听了容器内的回环地址，或者宿主端口被占用、映射写反了。按「容器内自测 → 宿主自测 → 外部自测」的顺序逐层缩小范围即可。
同一张卡上，参数应该从哪里开始调？
不要一上来就调并发和批处理。先把服务跑通、确认单请求能出结果，然后再动显存占用上限，最后才压并发。每改一个参数就记录一次结果和延迟，这样出问题能回退。具体该留多少余量，跟卡型、模型体和量化档位都有关，去 /models/deploy 按你的配置算一遍更靠谱。
