vllm docker 部署 deepseek

本地服务器上想用 vLLM 跑 DeepSeek，多半会卡在这几步：镜像拉下来发现驱动版本对不上，权重目录挂进去容器里却读不到，命令跑起来端口通了但发请求报错。这篇按「先自检、再拉镜像、后调参」的顺序走一遍，每一步都给出该核对什么、出错先查哪里。适合手上已有卡和服务器、想把它变成一个能被其他程序调用的接口的人。

本地服务器上想用 vLLM 跑 DeepSeek，多半会卡在这几步：镜像拉下来发现驱动版本对不上，权重目录挂进去容器里却读不到，命令跑起来端口通了但发请求报错。这篇按「先自检、再拉镜像、后调参」的顺序走一遍，每一步都给出该核对什么、出错先查哪里。

适合手上已有卡和服务器、想把它变成一个能被其他程序调用的接口的人。整篇不聊模型效果好不好，只聊怎么让它稳定地跑起来、外部程序能连上。跑通之后你会得到一个 OpenAI 兼容风格的本地接口，剩下的交给你的应用层。

开跑之前先把三件事确认掉

很多人上来就 docker run，结果卡在第一个报错上耗掉半天。其实开跑前有三件事确认掉，能省掉后面一大半排查时间：卡能不能被容器认到、显存够不够、权重目录结构对不对。这三件都不依赖 Docker 本身，先在宿主机上做完。

1. 核对显卡驱动与容器运行时宿主机上跑一次显卡状态查询命令，确认驱动正常且能看到全部卡。然后确认容器运行时装好了，否则镜像起来了也认不到卡，容器里会直接报找不到设备。相关名词不熟的话，到 /ai-dict/category/hardware 先混个脸熟再动手。
2. 算一遍显存够不够按参数量、量化档位、上下文长度和并发预留估一遍。别按「能装下权重」当标准——权重装得下只是最低门槛，KV 缓存和并发请求才是真正吃显存的地方。用 /models/deploy 的测算页对一下自己的配置，看看余量还剩多少。
3. 确认权重来源与格式从官方或镜像站拿到的权重目录结构要能被 vLLM 直接识别。先 ls 看清楚目录里有哪些文件、有没有配置文件，再决定怎么挂载。格式不对的话，容器起来只会报「找不到模型」这种很笼统的错。

镜像怎么选、怎么拉

镜像选择的核心原则只有一条：可复现。优先用官方镜像并固定一个具体标签，不要用 latest。原因很直接——部署脚本要能被别人复现，浮动标签下次跑可能就换内核了，昨天能跑的今天报错，排查起来毫无头绪。

固定标签

写死一个具体版本号，团队里所有人拉到的都是同一个镜像

CUDA 匹配

镜像里的 CUDA 版本要和宿主机的驱动能力匹配，版本太高会报运行时找不到设备的错，到 /ai-dict/category/infra 对照容器与驱动的关系

本地缓存

拉镜像慢就先在本机或就近节点做一次缓存，团队多台机器共用一份，别每台都从零拉

实际选择时，如果只是自己试跑，社区镜像也不是不能碰，但要把镜像来源记下来。一旦要给别人用或者上生产，回到官方镜像加固定标签这条路。拉之前先在另一台机器上验证标签能不能拉到，别等到部署当天才发现标签不存在。

权重挂载：路径、权限与磁盘

权重挂载出问题，症状几乎都一样：容器里报文件不存在，但你明明看到文件在宿主机上。这种情况十有八九不是路径写错，而是权限或安全策略拦了。挂载点写成绝对路径，宿主机的权重目录映射到容器内一个固定位置，命令里只引用容器内路径，别在两种路径之间来回切。

• 检查宿主机目录的读权限：容器里跑的用户可能不是目录所有者，读不到就是读不到
• 检查安全策略：SELinux 或 AppArmor 这类机制会拦容器访问宿主机目录，容器里报「文件不存在」多半是它干的
• 确认磁盘剩余空间：权重体积大，先看清楚目标盘剩多少、文件系统支不支持大文件，别跑到一半写满
• 挂载后进容器 ls 一次目标目录，确认文件真的可见，这一步三十秒，能省掉后面半小时的困惑
• 多卡机器上确认每张卡都能访问同一份权重目录，别出现某张卡读不到的情况

起服务命令要调的几组参数

起服务的命令别一次写太复杂。模型路径、服务端口、监听地址这三项先写死正确，其他参数先留默认，能起来再谈优化。一上来就把并发、显存、并行全调一遍，出错时根本不知道是哪个参数的问题。

调参的节奏是「一次只动一个」。想同时压并发和拉上下文，就先分别单独测一轮，看哪个参数是瓶颈。混在一起改，效果变好了也不知道是谁的功劳，变差了更不知道回退哪个。

接口验证：从容器内到容器外

服务起来了不代表能访问。验证要分两步：先在容器内部用本地地址发一次请求，再做容器外访问。两个都不通，说明是服务没起好；只有容器外不通，说明是端口映射或防火墙的问题。这个二分法能立刻把问题范围缩小一半。

• 容器内请求：在容器里用本地回环地址调一次接口，确认服务本身在响应
• 容器外请求：从宿主机或局域网另一台机器调同一个接口，确认端口映射生效
• 基线测量：用 /tools/speed-test 先量出一个延迟基线，之后调参才知道是变好还是变差
• 鉴权检查：暴露到公网之前先想清楚访问控制，vLLM 本身不替你解决鉴权，放内网或前面加一层网关更稳
• 回归记录：把这次的请求方式和返回结果记下来，作为下次升级后的对比基准

起不来时的排查顺序

排查要有固定顺序，别看到什么报错就查什么。按「驱动可见 → 镜像能跑 → 权重读得到 → 端口通 → 请求返回」五步往下走，报错信息里的关键词直接对应其中一步。跳步的代价是，你在第三步折腾半天，结果问题出在第一步。

1. 第一步：驱动可见宿主机上确认卡能被识别，容器运行时正常。这一步不过，后面全是白费。
2. 第二步：镜像能跑用最简单的命令让容器起来，确认镜像本身没问题，再往里加参数。
3. 第三步：权重读得到进容器 ls 权重目录，确认文件可见、可读。这一步卡住多半是权限或挂载策略。
4. 第四步：端口通容器内本地请求先通，再测容器外。不通就查端口映射和防火墙。
5. 第五步：请求返回接口能返回内容，再考虑并发和性能。返回慢或报错，先看日志里的排队和超时。

显存类报错和版本不匹配类报错不要同时改。显存不够先降并发和上下文长度，再考虑换量化档位；版本不匹配则要确认镜像、vLLM 版本、模型权重三者之间的兼容关系，参考 /vllm-deepseek-weight-compat 的做法先确认兼容性。把这两件事混在一起改会失去可比性。

跑起来之后长期怎么维护

跑通只是开始。长期维护的关键是让这套部署能被别人接手、能被自己回退。把镜像标签、启动命令、挂载路径记成一份版本化的配置文件，别只留在某台机器的历史命令里。换个人来接手，照着配置文件就能重建，而不是靠翻聊天记录。

服务能起来，只说明它今天能跑；配置能复现，才说明它明天还能跑。

升级镜像或换模型前，先留一份能回退的旧配置。升级后按同一组测试请求对比前后表现——用同一批请求、同样的并发，看延迟和正确返回率有没有变化。没有对比基线，升级就是盲改。并发压力也要按真实调用量慢慢加，别拿测试峰值当日常负载。