vllm docker部署使用本地模型

模型权重已经躺在本地硬盘上了，想用 vLLM 起个推理服务，结果一上来就卡在「容器里根本找不到我的模型目录」。这篇不聊该不该自建，只解决从宿主机权重到容器内可加载这条路：目录怎么挂、路径怎么写、权限和显存怎么对，以及起不来时按什么顺序排查。

模型权重已经躺在本地硬盘上了，想用 vLLM 起一个推理服务，结果第一步就卡住：容器里根本找不到你那个模型目录。这不是 vLLM 的问题，是挂载和路径没对齐。这篇只解决从宿主机权重到容器内可加载这一段路。

下面按「开工前定什么、命令怎么写、报错怎么查、跑通之后管什么」四段讲。每一步都带验证动作，照着做基本能少绕几圈。

动手前先把三件事定下来

很多人是权重还没整理好就直接敲命令，结果报错信息五花八门，浪费时间。先把下面三件事在纸上写清楚，再开容器。

权重目录

必须是完整的 Hugging Face 格式目录，里面有 config、tokenizer 这些文件；单个权重文件、没解压的压缩包都不算

模型标识

容器里加载模型用的是「容器内的那个路径」，不是宿主机的绝对路径，两套路径别混着写

运行环境

先确认显卡驱动和容器运行时能拿到 GPU，再确认镜像版本跟你要跑的模型架构对得上，支持范围到 /models/deploy 和 /models 核对当时的说明

挂载目录、写启动命令的正确姿势

挂载本身不难，容易错的是两件事：宿主机路径里有空格或中文，以及启动参数写成了宿主机路径。前者转义容易踩坑，后者基本必报「找不到模型」。

1. 挂载只读目录用只读方式把宿主机权重目录挂到容器内一个固定位置，比如 /models/your-model。挂完进容器 ls 一下，能看到 config 之类的文件才算对。
2. 写容器内路径启动命令里模型参数写容器内的挂载点，不是宿主机路径。这条是最高频的报错来源，写完自己回读一遍。
3. 调显存相关参数显存吃紧就先把单卡占用比例调低、上下文长度限制住，别一上来拉满。端口映射记得留出宿主机端口给后面调用。
4. 用最小请求验证服务起来后先发一次最小的对话请求，通了再考虑接业务。延迟基线可以到 /tools/speed-test 量一遍存下来做对比。

起不来时按这个顺序排查，别乱改参数

报错的时候最忌讳东改一下西改一下，改到最后自己都不知道哪步生效了。给一个固定顺序，一步一步来。

• 第一步看挂载：进容器确认那个目录里到底有没有文件，多数「找不到模型」其实是挂载点写错或目录是空的
• 第二步看权限：容器内进程读不到权重文件时，先查属主和读权限，别急着怀疑模型本身
• 第三步看显存：显存不足通常表现为启动中途退出或加载到一半失败，这时候该动的是量化档位和上下文长度，具体档位取舍到 /models/deploy 按当时的显存口径算
• 第四步才是版本：模型架构和框架版本不匹配，报错信息通常很直白，把前三步排掉再怀疑它

这四步的顺序不是随便排的：前三步都是环境问题，改起来代价小；版本涉及换镜像，动静最大，放最后。如果前两步都没问题但就是起不来，再带着完整报错去 /models/deploy 对照说明。

跑通之后，这几件事要一起定下来

服务能跑不等于能上线，下面三件事建议在跑通当天就定下来，省得后面返工。

• 暴露方式别默认全网开放，先从本机绑起，确认只有该访问的机器能连上再放开
• 许可证和「能不能跑起来」是两件事，跑得动不代表能商用，上线前先看清条件
• 把挂载路径、启动参数、镜像版本记在一个文档里，换机器或升级时不用重新试
• 如果你后面要接中转站或换服务商，先在 /sites 看清对接方式再动手

还有一种情况这套流程不适用：如果你的权重是分片存储或者放在网络文件系统上，挂载和读取速度的问题会不一样，得单独处理，别硬套本地目录的做法。