尧图网页设计 
最近在折腾大模型本地部署的朋友肯定绕不开vLLM这个名字。说实话我在Windows环境下第一次跑通vLLM的时候踩了不少坑从WSL2的环境初始化到模型权重下载再到最后用Docker把镜像打包分发出去每一步都有很多细节是官方文档不会直接告诉你的。这篇就是我完整梳理的一版本地部署全流程把WSL2环境安装、HuggingFace和ModelScope两种模型加载方式、vLLM启动推理以及Docker化部署与镜像分发全部串起来给你一条可以照着走的路。适合谁来参考主要是这三类人一是刚接触大模型推理、想在本地Windows机器上跑通vLLM的开发者二是需要在内网或离线环境部署推理服务又搞不清HuggingFace和ModelScope国内访问情况大家心里都有数该怎么切换的工程同学三是准备用Docker把模型推理服务打包成标准镜像、分发给团队或部署到服务器上的运维和算法工程师。如果你已经在用LM Studio或llama.cpp玩过本地推理再来看vLLM你会明显感觉到吞吐量和使用体验上的差异这篇文章能帮你把vLLM这条技术栈完整跑起来。1. 整体思路拆解为什么是vLLM为什么先落在WSL2先聊清楚一个基本问题vLLM到底解决了什么痛处。我们在本地跑大模型最常见的瓶颈是推理速度太慢、显存利用率太低。早期方案比如llama.cpp走的是CPU量化推理或者用HuggingFace Transformers直接加载PyTorch模型做生成显存一上来就很容易吃满而且并发一高请求排队时间会让人怀疑人生。vLLM的核心优势在于它实现了PagedAttention把KV Cache切分成物理块来管理有点像操作系统的虚拟内存分页机制。这个设计极大提升了显存利用率和吞吐支持Continuous Batching多个请求可以动态拼到一个batch里跑。你如果用过就会发现同样的显卡和模型用vLLM起服务和直接用Transformers起服务QPS差距可能是好几倍。所以我们要做的就是用vLLM把一个大模型加载起来暴露成一个兼容OpenAI协议的HTTP接口这样本地调试、上层应用对接都很方便。这个目标定了之后接下来要解决三个问题跑在什么系统环境里、模型权重从哪来、怎么把服务做成可以复用的部署单元。关于WSL2的选择这条我觉得有必要展开一下因为有不少人犹豫是直接用Windows原生跑还是装WSL2。我的建议很明确走WSL2。原因有三个。第一vLLM以及PyTorch生态里面的很多组件官方对Linux的支持永远是最优先的。你可以在Windows上用CUDA跑部分深度学习任务但一旦涉及像PagedAttention这种操作GPU内存的底层实现Linux下的兼容性和性能更稳定。第二Docker在Windows上跑有两种模式Windows容器和Linux容器。我们目标镜像基本是Linux的如果你用WSL2做后端Docker Desktop跑Linux容器就是原生级别的无缝体验文件挂载、端口映射都顺畅。第三WSL2本身是一个轻量级虚拟机但它和Windows共享网络和文件系统对日常开发来说几乎无感知最重要的是它允许NVIDIA Driver穿透到Linux里也就是说Windows里装好显卡驱动WSL2里就能直接用nvidia-smi看到GPU。这个特性直接决定了我们能在WSL2里做GPU推理。一句话总结思路Windows上装WSL2然后在WSL2里搭Python环境装vLLM从HuggingFace或ModelScope拉取模型权重启动vLLM作为OpenAI兼容服务最后用Docker把整个运行时打包成镜像分发。2. 环境准备WSL2安装与CUDA环境配置这块是整个流程的地基很多人在后面跑不起来回头排查全是环境问题。我按步骤讲每一步都标注为什么要这样做。2.1 启用Windows虚拟化功能与WSL2安装装WSL2之前先确认你的Windows版本。Win10 2004以上或Win11基本都支持。核心操作分三步。第一步以管理员身份打开PowerShell执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart这两条命令分别启用Windows Subsystem for Linux和虚拟机平台。第二条是WSL2的核心依赖因为WSL2本质上跑在一个轻量级虚拟化平台上如果你只开WSL1后面Docker和GPU透传都做不了。第二步重启电脑然后执行wsl --set-default-version 2把默认版本设为WSL2。如果你之前装过WSL1的发行版可以用wsl --set-version 发行版名 2单独转换。第三步安装Ubuntu发行版。你可以直接从Microsoft Store搜Ubuntu 22.04.3 LTS安装也可以用命令行wsl --install -d Ubuntu-22.04装完之后第一次启动会让你创建Linux用户名和密码。这里提个醒这个用户名和密码是Linux子系统内的和Windows账号没有关系别搞混。另外如果你遇到“WSL2无法启动因为此计算机上未启用虚拟化”这类报错直接进BIOS把Intel VT-x或AMD SVM打开。现在新机器一般默认开但有些品牌机出厂默认关着这一坑我见过太多次了。2.2 在WSL2里安装CUDA和NVIDIA驱动WSL2里装CUDA和你在裸机Linux上装不太一样关键点在于Windows侧的NVIDIA驱动同时服务于Windows和WSL2。所以第一步是去NVIDIA官网下载最新的Windows驱动装好之后WSL2里直接就能识别GPU。验证方法很简单进入WSL2终端执行nvidia-smi如果能看到类似下面的输出说明GPU透传已生效--------------------------------------------------------------------------------------- | NVIDIA-SMI 545.84 Driver Version: 545.84 CUDA Version: 12.3 | ---------------------------------------------------------------------------------------注意WSL2里不需要再单独安装NVIDIA驱动但CUDA Toolkit仍然要在Linux侧装。这个坑很多人踩过以为Windows装了驱动就万事大吉结果Python导入torch时报CUDA unavailable。正确的做法是装CUDA Toolkit我推荐用Miniconda来管理Python环境这样CUDA、PyTorch相关的依赖不会污染系统环境。在WSL2里依次执行wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装完Miniconda后新建一个vLLM专用环境conda create -n vllm python3.10 -y conda activate vllmPython版本我建议用3.10vLLM对3.10的支持最成熟3.11和3.12虽然也能跑但某些依赖比如旧版xformers、flash-attention可能会有编译兼容问题。然后是CUDA Toolkit直接走官方源麻烦建议用pip install nvidia-cuda-toolkit不对这个写法拿到的是PyPI上的CUDA二进制包不完整。标准做法是直接用英伟达的apt源或conda包conda install -c nvidia cuda-toolkit12.1装完验证nvcc --version看到release 12.1之类的输出即可。需要注意的是vLLM会有自己依赖的CUDA版本范围一般在安装vLLM时会自动匹配PyTorch对应的CUDA运行时。所以你不需要手动装很重的CUDA Toolkit真正起作用的是PyTorch自带的CUDA runtimenvcc主要用于开发编译场景。我们装它主要是为了防止后续编译flash-attention等扩展时需要用到。2.3 WSL2网络与存储优化WSL2默认的NAT网络模式在多数场景够用但如果你要跑需要外部设备访问的服务比如局域网里另一台机器来调用你的推理接口建议用mirrored网络模式。在%UserProfile%\.wslconfig里加[wsl2] networkingModemirrored memory16GB processors8networkingModemirrored是Win11 22H2以上才支持它让WSL2和Windows共享网络接口端口监听更自然外部设备直接访问Windows的IP加端口就能通到WSL2里的服务。内存和CPU限制按你的机器实际配置来。我这里设置了16GB内存和8核CPU因为我还要给Windows保留一部分资源。如果你只有16GB内存又跑7B模型建议把.wslconfig里的memory限制留2-4GB给Windows用不然Windows会卡成PPT。模型推理过程通常不需要调整这个文件但一旦跑起来发现WSL2里内存吃紧优先回来检查这个配置。存储方面默认VHDX虚拟磁盘文件放在C:\Users\用户名\AppData\Local\Packages\...很多人的C盘空间不够特别现在模型动辄十几个G。强烈建议把整个WSL发行版迁移到其他盘。先导出再导入wsl --export Ubuntu-22.04 D:\wsl\ubuntu.tar wsl --unregister Ubuntu-22.04 wsl --import Ubuntu-22.04 D:\wsl\ubuntu D:\wsl\ubuntu.tar注意--import之后默认用户会变成root需要手动设置默认用户比如ubuntu2204 config --default-user 你的用户名这种迁移方式比较粗暴但很实用我在自己机器上就是这么干的把整个WSL发行版放到了D盘省下了差不多30GB的C盘空间。3. vLLM安装与模型加载HuggingFace和ModelScope双轨方案环境准备好了下面进入重头戏安装vLLM并加载模型。3.1 pip安装vLLM及依赖选择在vllm环境里执行pip install vllm新版本vLLM的pip包已经捆绑了对应的PyTorch版本但为了确保CUDA对齐我建议手动先装PyTorchpip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121然后装vLLMpip install vllm装完后验证一下python -c import vllm; print(vllm.__version__)如果导入报错说找不到CUDA库多数是PyTorch的CUDA版本和系统驱动不匹配。这时候回到nvidia-smi看Driver Version和CUDA Version核对你PyTorch对应需要的CUDA版本。一般新版驱动530以上支持CUDA 12.x都没问题。顺带提一下很多人纠结SGLang和vLLM怎么选。SGLang在调度策略和结构化生成上有一些优势但论生态成熟度和社区支持vLLM目前还是更稳的选择。特别你如果只是想要一个稳定、高性能的OpenAI兼容推理服务vLLM可以少操很多心。3.2 从HuggingFace下载模型常规方法与国内镜像加速HuggingFace的模型库是全球最大的开源模型仓库但国内访问很不稳定这个大家都知道。如果你网络条件比较好直接用它自带的下载工具pip install -U huggingface_hub huggingface-cli download --resume-download meta-llama/Llama-2-7b-chat-hf --local-dir /data/models/llama-2-7b-chat--resume-download参数很重要下载中断后可以续传大模型文件动辄十几个G网络抖动断掉的情况太常见了。如果你发现HF官网根本连不上或者慢到无法忍受那就配置镜像。HuggingFace国内镜像站提供和官方一样的API和文件结构只需设置环境变量export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download --resume-download Qwen/Qwen2.5-7B-Instruct --local-dir /data/models/qwen2.5-7b-instruct注意设置HF_ENDPOINT之后huggingface_hub的所有请求都会走镜像站。不仅是下载连模型加载时如果本地找不到缓存也会回调这个地址。vLLM在加载模型时使用的是from_pretrained机制内部也会调用huggingface_hub所以这个环境变量对vLLM照样生效。另外还有一个国产方案是使用ModelScope我们下一节讲。3.3 从ModelScope下载模型国内真正省心的路径ModelScope是阿里开源模型社区国内下载速度非常理想而且和vLLM的兼容性也不错。很多热门模型包括Qwen系列、ChatGLM系列、DeepSeek系列在ModelScope上都有官方上传的权重。安装ModelScope的Python库pip install modelscope下载模型modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /data/models/qwen2.5-7b-instruct这里我推荐使用--local_dir而不是使用默认缓存目录。原因很简单vLLM加载时直接指向这个目录省去缓存查找的额外开销。而且你打包Docker镜像时把这个目录里的文件作为模型源也更直接。用ModelScope还有个好处国内很多模型作者会上传详细的中文说明和示例代码对英文不那么流畅的同学很友好。我在实际项目中如果目标模型在ModelScope有官方权重基本首选ModelScope省时省力。3.4 加载模型时vLLM对路径的处理逻辑vLLM启动时模型参数的--model参数既可以传HuggingFace模型名如meta-llama/Llama-2-7b-chat-hf也可以传本地目录如/data/models/qwen2.5-7b-instruct。当传模型名时vLLM会尝试从HuggingFace Hub拉取权重并缓存当传本地目录时它会直接读取目录下的config.json和权重文件。所以正确且可控的做法是先把权重完整下载到本地目录再把本地目录传给vLLM。这一点在生产环境尤为重要因为模型启动时会扫描权重文件、读取config、构建KV Cache尺寸如果权重不完整启动时会报错或行为异常。所以我强烈建议无论用HuggingFace还是ModelScope都先把权重下载到本地固定目录然后让vLLM读取本地路径不要让在线拉取发生在模型启动过程中。4. 本地运行与模型推理实践环境搭好权重也下好了终于到了启动vLLM服务的环节。4.1 单模型启动与OpenAI兼容接口验证最基础的一条启动命令python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct \ --served-model-name qwen2.5-7b \ --tensor-parallel-size 1 \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192参数解读--model模型路径或名称。--served-model-name对外暴露的模型名这个名称会出现在OpenAI兼容接口的/v1/models响应里客户端请求时model字段要传这个名字。--tensor-parallel-sizeGPU并行度。单卡设1多卡设实际卡数。--host和--port服务监听地址和端口。局域网或Docker里用0.0.0.0仅本机调试可以设127.0.0.1。--gpu-memory-utilizationvLLM会按显存可用比例自动分配KV Cache空间0.9表示最多用90%的显存。这个值不能设太高给CUDA context和其他开销留点余量不然启动时会报CUDA out of memory。--max-model-len模型最大上下文长度。这个值会直接影响KV Cache的预分配大小设太大可能OOM设太小长文本会截断。7B模型在消费级显卡上8K一般比较稳妥。启动日志里你会看到类似Starting vLLM server和Uvicorn running on http://0.0.0.0:8000的输出这说明服务已就绪。接下来用curl验证一下curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-7b, messages: [{role: user, content: 用一句话介绍你自己}], max_tokens: 128, temperature: 0.7 }看到返回的JSON里包含choices[0].message.content就说明推理已经跑通了。这个接口的请求格式和OpenAI官方接口保持一致所以你可以直接把OpenAI SDK的base_url改成http://localhost:8000/v1然后无缝切换到本地模型。我在实测Qwen2.5-7B-Instruct时单张RTX 4090上gpu-memory-utilization设0.9输入输出总长度约1500 tokens单个请求的首token时延大概在100ms左右稳定后吞吐能做到每秒2000-3000 tokens。这个速度已经足够支撑一些中小规模的交互场景。4.2 多模型管理vLLM的多模型部署方案很多场景下我们不只跑一个模型。比如业务早上用Qwen生成文本下午用Embedding模型做向量化。vLLM从某个版本开始支持一个服务实例同时加载多个模型。具体做法是使用--model参数时传入多个模型配置以JSON格式指定。但更简单的方式是写一个serve配置或者干脆起多个vLLM进程分别监听不同端口。如果你希望一个端口同时暴露多个模型可以这样启动python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct \ --model /data/models/bge-large-zh \ --served-model-name qwen2.5-7b,bge-large-zh \ --tensor-parallel-size 1 \ --host 0.0.0.0 \ --port 8000不过要注意多个模型会共享同一块显存KV Cache也会被分割。如果两个模型的总需求超过显存容量启动时就会直接报错。我的建议是单个服务实例最多放2-3个中小尺寸模型大模型还是单独起进程更清晰。另外vLLM还支持LoRA适配器的动态加载你可以用一个基础模型加上多个LoRA权重来低成本实现多风格多能力这个功能在不同版本上API稍不一样用之前务必看下你装的版本的--help。4.3 单机多卡与纯CPU模式的情况说明单机多卡部署是vLLM的强项你只需要把--tensor-parallel-size设为卡数。比如两张卡--tensor-parallel-size 2vLLM会自动做张量并行把模型切分到多张GPU上。需要注意几点一是多卡之间用NVLink或PCIe通信速度会影响性能NVLink最好二是8卡机器上tensor-parallel-size一般取2的幂2、4、8和模型头的维度划分有关三是启动时所有卡都可见但有其他进程占用了GPU显存也要在启动前处理好不然会报torch错误。纯CPU模式呢vLLM官方对CPU的支持不算太好它主要面向GPU推理。如果你确实没有NVIDIA GPU又想在本地跑vLLM社区有CPU版本的分支但性能和稳定性都远不如GPU版本。我只能说CPU推理老老实实用llama.cpp这类工具。vLLM的定位非常明确高性能GPU推理引擎别硬上。4.4 性能调优与参数选择心得跑通只是个开始跑得稳、跑得快才是目标。我分享几个实测下来帮助很大的调优参数。第一--max-num-seqs控制并发序列数。默认值是256但如果你的显存不大可以降到64或32减少burst时显存峰值避免OOM。第二--enable-prefix-caching开启前缀缓存。如果你的场景经常出现重复的前缀比如多轮对话里的system prompt、RAG里的固定指令这个开关能把相同前缀的KV Cache复用起来实际效果非常显著。多轮对话场景下我做过对比用了前缀缓存之后首token时延可以降低50%以上。第三--quantization参数。vLLM支持AWQ和GPTQ量化模型。如果你手头有量化好的权重比如Qwen2.5-7B-Instruct-AWQ加载时的命令python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct-awq \ --quantization awq \ --served-model-name qwen2.5-7b-awq量化模型的优点是显存占用大幅下降推理速度更快代价是模型精度稍有损失。对于7B模型AWQ量化后显存占用能从16GB降到10GB左右在低显存显卡上这是很值得考虑的选择。实测下来AWQ在生成质量和显存/速度之间的平衡做得不错是目前量化推理的首选方案之一。5. Docker化部署与镜像分发如果你只是在自己电脑上跑到第4步就够用了。但真正常见的场景是你在WSL2里调试好了环境后续要把这套推理服务部署到服务器上或者交给运维同事统一管理。这时候Docker化就是顺理成章的下一步。5.1 在WSL2中安装Docker与配置GPU支持我推荐直接在WSL2内部安装Docker Engine而不是用Docker Desktop。虽然Docker Desktop对初学者更友好界面化、一键启停但它会多一层封装对于需要精细控制的部署场景有时反而碍事。在WSL2里装Docker Engine本质上和在Linux服务器上安装没有任何区别好处是你的操作经验可以直接迁移到生产环境。安装方法curl -fsSL https://get.docker.com | sh或者手动加源安装用get.docker.com最省事。装完后启动服务并设为开机自启sudo systemctl enable docker --now验证Docker是否可用sudo docker run hello-worldGPU支持需要额外插件即nvidia-container-toolkitsudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker配置好之后用docker run时加上--gpus all就能在容器内访问GPU。注意WSL2内使用Docker跑GPU容器前提是宿主Windows已安装对应的NVIDIA驱动且WSL2里执行nvidia-smi能正常显示GPU信息。这个我们在前面已经验证过了。5.2 创建vLLM服务的Dockerfile一个标准的vLLM服务镜像可以基于官方提供的vllm镜像也可以自定义。我的推荐是基于官方镜像做二次封装这样能省去很多底层依赖编译的麻烦。官方镜像的地址是vllm/vllm-openai直接拉取docker pull vllm/vllm-openai:latest但如果你想要一个更可控的镜像可以自己写Dockerfile。下面这个是我在实际项目中用过的一份简洁且可复用FROM vllm/vllm-openai:latest # 设置工作目录 WORKDIR /app # 预先安装模型下载工具 RUN pip install modelscope huggingface_hub -U # 下载模型到镜像内也可以跳过这一步运行时通过挂载卷加载 RUN python -c from modelscope import snapshot_download; snapshot_download(Qwen/Qwen2.5-7B-Instruct, local_dir/models/qwen2.5-7b-instruct) # 暴露服务端口 EXPOSE 8000 # 默认启动命令 ENTRYPOINT [python, -m, vllm.entrypoints.openai.api_server] CMD [--model, /models/qwen2.5-7b-instruct, --served-model-name, qwen2.5-7b, --host, 0.0.0.0, --port, 8000, --gpu-memory-utilization, 0.9]有两个细节值得注意。一是把模型权重打进镜像好处是镜像启动即用分发时不用额外挂载数据卷坏处是镜像体积会非常大7B模型原始权重大概15GB加上运行环境整个镜像可能超过20GB。如果只是个人调试我建议别把权重打进镜像而是用挂载卷的方式把宿主机上的/data/models目录挂进容器。这样镜像只有几个GB分发起来轻松得多。二是如果你实在想把ModelScope下载步骤放在镜像构建里国内服务器构建时网络没问题但如果客户端机器拉镜像在网络受限环境镜像构建和拉取都可能出问题。所以更稳妥的做法是镜像只包含运行环境权重通过外部挂载或模型仓库下载。5.3 使用Docker Compose管理多服务当你的环境不只有一个模型服务还可能有向量数据库、前端应用等用Docker Compose来编排这些服务会更清晰。下面是一个简化的docker-compose.yml示例version: 3.8 services: vllm-qwen: image: myregistry.example.com/vllm-qwen:1.0 runtime: nvidia environment: - CUDA_VISIBLE_DEVICES0 volumes: - /data/models/qwen2.5-7b-instruct:/models/qwen2.5-7b-instruct ports: - 8000:8000 command: --model /models/qwen2.5-7b-instruct --served-model-name qwen2.5-7b --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.9 vllm-embedding: image: myregistry.example.com/vllm-embedding:1.0 runtime: nvidia environment: - CUDA_VISIBLE_DEVICES0 volumes: - /data/models/bge-large-zh:/models/bge-large-zh ports: - 8001:8000 command: --model /models/bge-large-zh --served-model-name bge-large-zh --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.4用docker compose up -d启动所有服务。两个模型分别监听8000和8001端口互不冲突。当你有多卡时可以分别指定CUDA_VISIBLE_DEVICES把模型分配到不同GPU上进一步隔离资源。5.4 镜像构建、打标签与分发构建镜像docker build -t vllm-qwen:1.0 .打标签并推送到私有仓库docker tag vllm-qwen:1.0 myregistry.example.com/vllm-qwen:1.0 docker push myregistry.example.com/vllm-qwen:1.0如果没有私有仓库也可以用docker save把镜像保存为tar包在目标机器上docker load导入docker save vllm-qwen:1.0 | gzip vllm-qwen-1.0.tar.gz把tar包拷贝到目标机器后gunzip -c vllm-qwen-1.0.tar.gz | docker load这种方式很适合内网离线环境。目标机器只要有Docker运行环境和NVIDIA驱动以及container toolkit就可以直接起服务。我自己的习惯是如果目标部署机器能直连模型仓库ModelScope/HuggingFace镜像中就不带权重用Compose挂载本地目录如果目标机器完全离线且没有预置权重那就只能做完整镜像分发。两种方式在Dockerfile和Compose里的配置略有差异建议两种方案都准备好按实际场景切换。6. 常见问题与排查技巧整个流程我走过的坑不少下面这些是出现频率最高的每个都给了排查建议。现象原因排查与解决WSL2启动报“未启用虚拟化”BIOS中虚拟化技术被关闭进BIOS开启Intel VT-x或AMD SVMWSL2里执行nvidia-smi报错Windows显卡驱动过旧或未正确安装更新到最新版驱动重启WSL2vLLM启动报CUDA out of memory模型权重KV Cache超过显存容量降低gpu-memory-utilization或max-model-len或改用量化模型HuggingFace下载超时/断流网络访问不稳定设置HF_ENDPOINT为国内镜像站或用ModelScope模型加载后中文乱码或输出异常模型tokenizer配置问题或模型路径不对确认权重目录里包含tokenizer.json、config.json等完整文件Docker Desktop启动失败提示虚拟化不支持Windows虚拟化功能或BIOS关闭检查VirtualMachinePlatform和BIOS虚拟化开关多卡部署时速度反而变慢卡间通信瓶颈模型太小不适合张量并行小模型用单卡足够大模型才用tensor-parallel-size容器里访问不到GPU未安装nvidia-container-toolkit安装插件并重启Docker守护进程和网络相关的排查方向我再多说一句。如果你在下载模型时碰到各种奇怪的超时或校验错误第一反应别去改代码先确认环境变量是否正确。HuggingFace侧HF_ENDPOINT和HF_HOME这两个变量最容易影响行为。HF_HOME指定缓存根目录如果你希望模型下载后存放在一个可控的目录而不是默认的~/.cache/huggingface最好手动设置。export HF_HOME/data/huggingface export HF_ENDPOINThttps://hf-mirror.comModelScope侧可通过设置MODELSCOPE_CACHE指定缓存目录。这样你在调试模型路径时永远不会出现“明明下载了但找不到文件”的情况。最后再讲一个关于--served-model-name不生效的坑。如果你直接修改了--model的传参但忘了同步--served-model-name调用接口时可能会报The model xxx does not exist。因为OpenAI兼容接口的/v1/models里暴露的是served-model-name不是模型的文件夹名字。这个命名在客户端对接时要保持一致省得来回排查半天。还有一点经验之谈WSL2里如果长时间跑大模型服务Windows会自动回收内存导致WSL2里的进程被kill尤其是开机后没有主动设置WSL2内存上限时更容易遇到。我在.wslconfig里用[experimental] autoMemoryReclaimgradual这个配置项做了调整可以避免内存吃紧时被强制重新回收。不同版本的Windows对这条配置支持不同如果你的系统较新可以试一下确实能减少很多烦心事。写在最后的实操心得从零开始把vLLM在Windows WSL2上跑通再走到Docker化分发这条路我完整走下来最大的感受是环境坑比模型坑多。模型本身只要权重完整、路径正确vLLM基本不会让你大动干戈。反倒是WSL2的虚拟化开关、NVIDIA驱动的透传、Docker的GPU插件每一步都可能成为拦路虎。所以我的建议是每一个阶段先做最小验证WSL2装完先跑nvidia-smiDocker装完先跑GPU容器模型下完先看一眼目录结构再启动vLLM。这样哪怕出了问题排查范围也很小。配置上我目前的主力环境是Win11 WSL2 Ubuntu 22.04 RTX 4090 24GB vLLM 0.6.x Qwen2.5-7B-InstructAWQ量化。日常开发调试用的是HuggingFace镜像站下载权重跑生产环境服务时用Docker Compose编排镜像只含运行环境权重通过挂载卷共享。这套组合实操下来稳定性和性能都让我满意。后面你可以继续扩展的方向也不少比如给vLLM服务加一个简单的鉴权层、对接一个Web UI比如Chatbot UI、或者把多模型和LoRA动态加载玩起来。技术上都是顺着这条路再往前走环境基础打牢了后面就都是锦上添花。 Windows WSL2 下 vLLM 部署与 Docker 分发实战指南
最近在折腾大模型本地部署的朋友肯定绕不开vLLM这个名字。说实话我在Windows环境下第一次跑通vLLM的时候踩了不少坑从WSL2的环境初始化到模型权重下载再到最后用Docker把镜像打包分发出去每一步都有很多细节是官方文档不会直接告诉你的。这篇就是我完整梳理的一版本地部署全流程把WSL2环境安装、HuggingFace和ModelScope两种模型加载方式、vLLM启动推理以及Docker化部署与镜像分发全部串起来给你一条可以照着走的路。适合谁来参考主要是这三类人一是刚接触大模型推理、想在本地Windows机器上跑通vLLM的开发者二是需要在内网或离线环境部署推理服务又搞不清HuggingFace和ModelScope国内访问情况大家心里都有数该怎么切换的工程同学三是准备用Docker把模型推理服务打包成标准镜像、分发给团队或部署到服务器上的运维和算法工程师。如果你已经在用LM Studio或llama.cpp玩过本地推理再来看vLLM你会明显感觉到吞吐量和使用体验上的差异这篇文章能帮你把vLLM这条技术栈完整跑起来。1. 整体思路拆解为什么是vLLM为什么先落在WSL2先聊清楚一个基本问题vLLM到底解决了什么痛处。我们在本地跑大模型最常见的瓶颈是推理速度太慢、显存利用率太低。早期方案比如llama.cpp走的是CPU量化推理或者用HuggingFace Transformers直接加载PyTorch模型做生成显存一上来就很容易吃满而且并发一高请求排队时间会让人怀疑人生。vLLM的核心优势在于它实现了PagedAttention把KV Cache切分成物理块来管理有点像操作系统的虚拟内存分页机制。这个设计极大提升了显存利用率和吞吐支持Continuous Batching多个请求可以动态拼到一个batch里跑。你如果用过就会发现同样的显卡和模型用vLLM起服务和直接用Transformers起服务QPS差距可能是好几倍。所以我们要做的就是用vLLM把一个大模型加载起来暴露成一个兼容OpenAI协议的HTTP接口这样本地调试、上层应用对接都很方便。这个目标定了之后接下来要解决三个问题跑在什么系统环境里、模型权重从哪来、怎么把服务做成可以复用的部署单元。关于WSL2的选择这条我觉得有必要展开一下因为有不少人犹豫是直接用Windows原生跑还是装WSL2。我的建议很明确走WSL2。原因有三个。第一vLLM以及PyTorch生态里面的很多组件官方对Linux的支持永远是最优先的。你可以在Windows上用CUDA跑部分深度学习任务但一旦涉及像PagedAttention这种操作GPU内存的底层实现Linux下的兼容性和性能更稳定。第二Docker在Windows上跑有两种模式Windows容器和Linux容器。我们目标镜像基本是Linux的如果你用WSL2做后端Docker Desktop跑Linux容器就是原生级别的无缝体验文件挂载、端口映射都顺畅。第三WSL2本身是一个轻量级虚拟机但它和Windows共享网络和文件系统对日常开发来说几乎无感知最重要的是它允许NVIDIA Driver穿透到Linux里也就是说Windows里装好显卡驱动WSL2里就能直接用nvidia-smi看到GPU。这个特性直接决定了我们能在WSL2里做GPU推理。一句话总结思路Windows上装WSL2然后在WSL2里搭Python环境装vLLM从HuggingFace或ModelScope拉取模型权重启动vLLM作为OpenAI兼容服务最后用Docker把整个运行时打包成镜像分发。2. 环境准备WSL2安装与CUDA环境配置这块是整个流程的地基很多人在后面跑不起来回头排查全是环境问题。我按步骤讲每一步都标注为什么要这样做。2.1 启用Windows虚拟化功能与WSL2安装装WSL2之前先确认你的Windows版本。Win10 2004以上或Win11基本都支持。核心操作分三步。第一步以管理员身份打开PowerShell执行dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart这两条命令分别启用Windows Subsystem for Linux和虚拟机平台。第二条是WSL2的核心依赖因为WSL2本质上跑在一个轻量级虚拟化平台上如果你只开WSL1后面Docker和GPU透传都做不了。第二步重启电脑然后执行wsl --set-default-version 2把默认版本设为WSL2。如果你之前装过WSL1的发行版可以用wsl --set-version 发行版名 2单独转换。第三步安装Ubuntu发行版。你可以直接从Microsoft Store搜Ubuntu 22.04.3 LTS安装也可以用命令行wsl --install -d Ubuntu-22.04装完之后第一次启动会让你创建Linux用户名和密码。这里提个醒这个用户名和密码是Linux子系统内的和Windows账号没有关系别搞混。另外如果你遇到“WSL2无法启动因为此计算机上未启用虚拟化”这类报错直接进BIOS把Intel VT-x或AMD SVM打开。现在新机器一般默认开但有些品牌机出厂默认关着这一坑我见过太多次了。2.2 在WSL2里安装CUDA和NVIDIA驱动WSL2里装CUDA和你在裸机Linux上装不太一样关键点在于Windows侧的NVIDIA驱动同时服务于Windows和WSL2。所以第一步是去NVIDIA官网下载最新的Windows驱动装好之后WSL2里直接就能识别GPU。验证方法很简单进入WSL2终端执行nvidia-smi如果能看到类似下面的输出说明GPU透传已生效--------------------------------------------------------------------------------------- | NVIDIA-SMI 545.84 Driver Version: 545.84 CUDA Version: 12.3 | ---------------------------------------------------------------------------------------注意WSL2里不需要再单独安装NVIDIA驱动但CUDA Toolkit仍然要在Linux侧装。这个坑很多人踩过以为Windows装了驱动就万事大吉结果Python导入torch时报CUDA unavailable。正确的做法是装CUDA Toolkit我推荐用Miniconda来管理Python环境这样CUDA、PyTorch相关的依赖不会污染系统环境。在WSL2里依次执行wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装完Miniconda后新建一个vLLM专用环境conda create -n vllm python3.10 -y conda activate vllmPython版本我建议用3.10vLLM对3.10的支持最成熟3.11和3.12虽然也能跑但某些依赖比如旧版xformers、flash-attention可能会有编译兼容问题。然后是CUDA Toolkit直接走官方源麻烦建议用pip install nvidia-cuda-toolkit不对这个写法拿到的是PyPI上的CUDA二进制包不完整。标准做法是直接用英伟达的apt源或conda包conda install -c nvidia cuda-toolkit12.1装完验证nvcc --version看到release 12.1之类的输出即可。需要注意的是vLLM会有自己依赖的CUDA版本范围一般在安装vLLM时会自动匹配PyTorch对应的CUDA运行时。所以你不需要手动装很重的CUDA Toolkit真正起作用的是PyTorch自带的CUDA runtimenvcc主要用于开发编译场景。我们装它主要是为了防止后续编译flash-attention等扩展时需要用到。2.3 WSL2网络与存储优化WSL2默认的NAT网络模式在多数场景够用但如果你要跑需要外部设备访问的服务比如局域网里另一台机器来调用你的推理接口建议用mirrored网络模式。在%UserProfile%\.wslconfig里加[wsl2] networkingModemirrored memory16GB processors8networkingModemirrored是Win11 22H2以上才支持它让WSL2和Windows共享网络接口端口监听更自然外部设备直接访问Windows的IP加端口就能通到WSL2里的服务。内存和CPU限制按你的机器实际配置来。我这里设置了16GB内存和8核CPU因为我还要给Windows保留一部分资源。如果你只有16GB内存又跑7B模型建议把.wslconfig里的memory限制留2-4GB给Windows用不然Windows会卡成PPT。模型推理过程通常不需要调整这个文件但一旦跑起来发现WSL2里内存吃紧优先回来检查这个配置。存储方面默认VHDX虚拟磁盘文件放在C:\Users\用户名\AppData\Local\Packages\...很多人的C盘空间不够特别现在模型动辄十几个G。强烈建议把整个WSL发行版迁移到其他盘。先导出再导入wsl --export Ubuntu-22.04 D:\wsl\ubuntu.tar wsl --unregister Ubuntu-22.04 wsl --import Ubuntu-22.04 D:\wsl\ubuntu D:\wsl\ubuntu.tar注意--import之后默认用户会变成root需要手动设置默认用户比如ubuntu2204 config --default-user 你的用户名这种迁移方式比较粗暴但很实用我在自己机器上就是这么干的把整个WSL发行版放到了D盘省下了差不多30GB的C盘空间。3. vLLM安装与模型加载HuggingFace和ModelScope双轨方案环境准备好了下面进入重头戏安装vLLM并加载模型。3.1 pip安装vLLM及依赖选择在vllm环境里执行pip install vllm新版本vLLM的pip包已经捆绑了对应的PyTorch版本但为了确保CUDA对齐我建议手动先装PyTorchpip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121然后装vLLMpip install vllm装完后验证一下python -c import vllm; print(vllm.__version__)如果导入报错说找不到CUDA库多数是PyTorch的CUDA版本和系统驱动不匹配。这时候回到nvidia-smi看Driver Version和CUDA Version核对你PyTorch对应需要的CUDA版本。一般新版驱动530以上支持CUDA 12.x都没问题。顺带提一下很多人纠结SGLang和vLLM怎么选。SGLang在调度策略和结构化生成上有一些优势但论生态成熟度和社区支持vLLM目前还是更稳的选择。特别你如果只是想要一个稳定、高性能的OpenAI兼容推理服务vLLM可以少操很多心。3.2 从HuggingFace下载模型常规方法与国内镜像加速HuggingFace的模型库是全球最大的开源模型仓库但国内访问很不稳定这个大家都知道。如果你网络条件比较好直接用它自带的下载工具pip install -U huggingface_hub huggingface-cli download --resume-download meta-llama/Llama-2-7b-chat-hf --local-dir /data/models/llama-2-7b-chat--resume-download参数很重要下载中断后可以续传大模型文件动辄十几个G网络抖动断掉的情况太常见了。如果你发现HF官网根本连不上或者慢到无法忍受那就配置镜像。HuggingFace国内镜像站提供和官方一样的API和文件结构只需设置环境变量export HF_ENDPOINThttps://hf-mirror.com huggingface-cli download --resume-download Qwen/Qwen2.5-7B-Instruct --local-dir /data/models/qwen2.5-7b-instruct注意设置HF_ENDPOINT之后huggingface_hub的所有请求都会走镜像站。不仅是下载连模型加载时如果本地找不到缓存也会回调这个地址。vLLM在加载模型时使用的是from_pretrained机制内部也会调用huggingface_hub所以这个环境变量对vLLM照样生效。另外还有一个国产方案是使用ModelScope我们下一节讲。3.3 从ModelScope下载模型国内真正省心的路径ModelScope是阿里开源模型社区国内下载速度非常理想而且和vLLM的兼容性也不错。很多热门模型包括Qwen系列、ChatGLM系列、DeepSeek系列在ModelScope上都有官方上传的权重。安装ModelScope的Python库pip install modelscope下载模型modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /data/models/qwen2.5-7b-instruct这里我推荐使用--local_dir而不是使用默认缓存目录。原因很简单vLLM加载时直接指向这个目录省去缓存查找的额外开销。而且你打包Docker镜像时把这个目录里的文件作为模型源也更直接。用ModelScope还有个好处国内很多模型作者会上传详细的中文说明和示例代码对英文不那么流畅的同学很友好。我在实际项目中如果目标模型在ModelScope有官方权重基本首选ModelScope省时省力。3.4 加载模型时vLLM对路径的处理逻辑vLLM启动时模型参数的--model参数既可以传HuggingFace模型名如meta-llama/Llama-2-7b-chat-hf也可以传本地目录如/data/models/qwen2.5-7b-instruct。当传模型名时vLLM会尝试从HuggingFace Hub拉取权重并缓存当传本地目录时它会直接读取目录下的config.json和权重文件。所以正确且可控的做法是先把权重完整下载到本地目录再把本地目录传给vLLM。这一点在生产环境尤为重要因为模型启动时会扫描权重文件、读取config、构建KV Cache尺寸如果权重不完整启动时会报错或行为异常。所以我强烈建议无论用HuggingFace还是ModelScope都先把权重下载到本地固定目录然后让vLLM读取本地路径不要让在线拉取发生在模型启动过程中。4. 本地运行与模型推理实践环境搭好权重也下好了终于到了启动vLLM服务的环节。4.1 单模型启动与OpenAI兼容接口验证最基础的一条启动命令python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct \ --served-model-name qwen2.5-7b \ --tensor-parallel-size 1 \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192参数解读--model模型路径或名称。--served-model-name对外暴露的模型名这个名称会出现在OpenAI兼容接口的/v1/models响应里客户端请求时model字段要传这个名字。--tensor-parallel-sizeGPU并行度。单卡设1多卡设实际卡数。--host和--port服务监听地址和端口。局域网或Docker里用0.0.0.0仅本机调试可以设127.0.0.1。--gpu-memory-utilizationvLLM会按显存可用比例自动分配KV Cache空间0.9表示最多用90%的显存。这个值不能设太高给CUDA context和其他开销留点余量不然启动时会报CUDA out of memory。--max-model-len模型最大上下文长度。这个值会直接影响KV Cache的预分配大小设太大可能OOM设太小长文本会截断。7B模型在消费级显卡上8K一般比较稳妥。启动日志里你会看到类似Starting vLLM server和Uvicorn running on http://0.0.0.0:8000的输出这说明服务已就绪。接下来用curl验证一下curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-7b, messages: [{role: user, content: 用一句话介绍你自己}], max_tokens: 128, temperature: 0.7 }看到返回的JSON里包含choices[0].message.content就说明推理已经跑通了。这个接口的请求格式和OpenAI官方接口保持一致所以你可以直接把OpenAI SDK的base_url改成http://localhost:8000/v1然后无缝切换到本地模型。我在实测Qwen2.5-7B-Instruct时单张RTX 4090上gpu-memory-utilization设0.9输入输出总长度约1500 tokens单个请求的首token时延大概在100ms左右稳定后吞吐能做到每秒2000-3000 tokens。这个速度已经足够支撑一些中小规模的交互场景。4.2 多模型管理vLLM的多模型部署方案很多场景下我们不只跑一个模型。比如业务早上用Qwen生成文本下午用Embedding模型做向量化。vLLM从某个版本开始支持一个服务实例同时加载多个模型。具体做法是使用--model参数时传入多个模型配置以JSON格式指定。但更简单的方式是写一个serve配置或者干脆起多个vLLM进程分别监听不同端口。如果你希望一个端口同时暴露多个模型可以这样启动python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct \ --model /data/models/bge-large-zh \ --served-model-name qwen2.5-7b,bge-large-zh \ --tensor-parallel-size 1 \ --host 0.0.0.0 \ --port 8000不过要注意多个模型会共享同一块显存KV Cache也会被分割。如果两个模型的总需求超过显存容量启动时就会直接报错。我的建议是单个服务实例最多放2-3个中小尺寸模型大模型还是单独起进程更清晰。另外vLLM还支持LoRA适配器的动态加载你可以用一个基础模型加上多个LoRA权重来低成本实现多风格多能力这个功能在不同版本上API稍不一样用之前务必看下你装的版本的--help。4.3 单机多卡与纯CPU模式的情况说明单机多卡部署是vLLM的强项你只需要把--tensor-parallel-size设为卡数。比如两张卡--tensor-parallel-size 2vLLM会自动做张量并行把模型切分到多张GPU上。需要注意几点一是多卡之间用NVLink或PCIe通信速度会影响性能NVLink最好二是8卡机器上tensor-parallel-size一般取2的幂2、4、8和模型头的维度划分有关三是启动时所有卡都可见但有其他进程占用了GPU显存也要在启动前处理好不然会报torch错误。纯CPU模式呢vLLM官方对CPU的支持不算太好它主要面向GPU推理。如果你确实没有NVIDIA GPU又想在本地跑vLLM社区有CPU版本的分支但性能和稳定性都远不如GPU版本。我只能说CPU推理老老实实用llama.cpp这类工具。vLLM的定位非常明确高性能GPU推理引擎别硬上。4.4 性能调优与参数选择心得跑通只是个开始跑得稳、跑得快才是目标。我分享几个实测下来帮助很大的调优参数。第一--max-num-seqs控制并发序列数。默认值是256但如果你的显存不大可以降到64或32减少burst时显存峰值避免OOM。第二--enable-prefix-caching开启前缀缓存。如果你的场景经常出现重复的前缀比如多轮对话里的system prompt、RAG里的固定指令这个开关能把相同前缀的KV Cache复用起来实际效果非常显著。多轮对话场景下我做过对比用了前缀缓存之后首token时延可以降低50%以上。第三--quantization参数。vLLM支持AWQ和GPTQ量化模型。如果你手头有量化好的权重比如Qwen2.5-7B-Instruct-AWQ加载时的命令python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct-awq \ --quantization awq \ --served-model-name qwen2.5-7b-awq量化模型的优点是显存占用大幅下降推理速度更快代价是模型精度稍有损失。对于7B模型AWQ量化后显存占用能从16GB降到10GB左右在低显存显卡上这是很值得考虑的选择。实测下来AWQ在生成质量和显存/速度之间的平衡做得不错是目前量化推理的首选方案之一。5. Docker化部署与镜像分发如果你只是在自己电脑上跑到第4步就够用了。但真正常见的场景是你在WSL2里调试好了环境后续要把这套推理服务部署到服务器上或者交给运维同事统一管理。这时候Docker化就是顺理成章的下一步。5.1 在WSL2中安装Docker与配置GPU支持我推荐直接在WSL2内部安装Docker Engine而不是用Docker Desktop。虽然Docker Desktop对初学者更友好界面化、一键启停但它会多一层封装对于需要精细控制的部署场景有时反而碍事。在WSL2里装Docker Engine本质上和在Linux服务器上安装没有任何区别好处是你的操作经验可以直接迁移到生产环境。安装方法curl -fsSL https://get.docker.com | sh或者手动加源安装用get.docker.com最省事。装完后启动服务并设为开机自启sudo systemctl enable docker --now验证Docker是否可用sudo docker run hello-worldGPU支持需要额外插件即nvidia-container-toolkitsudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker配置好之后用docker run时加上--gpus all就能在容器内访问GPU。注意WSL2内使用Docker跑GPU容器前提是宿主Windows已安装对应的NVIDIA驱动且WSL2里执行nvidia-smi能正常显示GPU信息。这个我们在前面已经验证过了。5.2 创建vLLM服务的Dockerfile一个标准的vLLM服务镜像可以基于官方提供的vllm镜像也可以自定义。我的推荐是基于官方镜像做二次封装这样能省去很多底层依赖编译的麻烦。官方镜像的地址是vllm/vllm-openai直接拉取docker pull vllm/vllm-openai:latest但如果你想要一个更可控的镜像可以自己写Dockerfile。下面这个是我在实际项目中用过的一份简洁且可复用FROM vllm/vllm-openai:latest # 设置工作目录 WORKDIR /app # 预先安装模型下载工具 RUN pip install modelscope huggingface_hub -U # 下载模型到镜像内也可以跳过这一步运行时通过挂载卷加载 RUN python -c from modelscope import snapshot_download; snapshot_download(Qwen/Qwen2.5-7B-Instruct, local_dir/models/qwen2.5-7b-instruct) # 暴露服务端口 EXPOSE 8000 # 默认启动命令 ENTRYPOINT [python, -m, vllm.entrypoints.openai.api_server] CMD [--model, /models/qwen2.5-7b-instruct, --served-model-name, qwen2.5-7b, --host, 0.0.0.0, --port, 8000, --gpu-memory-utilization, 0.9]有两个细节值得注意。一是把模型权重打进镜像好处是镜像启动即用分发时不用额外挂载数据卷坏处是镜像体积会非常大7B模型原始权重大概15GB加上运行环境整个镜像可能超过20GB。如果只是个人调试我建议别把权重打进镜像而是用挂载卷的方式把宿主机上的/data/models目录挂进容器。这样镜像只有几个GB分发起来轻松得多。二是如果你实在想把ModelScope下载步骤放在镜像构建里国内服务器构建时网络没问题但如果客户端机器拉镜像在网络受限环境镜像构建和拉取都可能出问题。所以更稳妥的做法是镜像只包含运行环境权重通过外部挂载或模型仓库下载。5.3 使用Docker Compose管理多服务当你的环境不只有一个模型服务还可能有向量数据库、前端应用等用Docker Compose来编排这些服务会更清晰。下面是一个简化的docker-compose.yml示例version: 3.8 services: vllm-qwen: image: myregistry.example.com/vllm-qwen:1.0 runtime: nvidia environment: - CUDA_VISIBLE_DEVICES0 volumes: - /data/models/qwen2.5-7b-instruct:/models/qwen2.5-7b-instruct ports: - 8000:8000 command: --model /models/qwen2.5-7b-instruct --served-model-name qwen2.5-7b --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.9 vllm-embedding: image: myregistry.example.com/vllm-embedding:1.0 runtime: nvidia environment: - CUDA_VISIBLE_DEVICES0 volumes: - /data/models/bge-large-zh:/models/bge-large-zh ports: - 8001:8000 command: --model /models/bge-large-zh --served-model-name bge-large-zh --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.4用docker compose up -d启动所有服务。两个模型分别监听8000和8001端口互不冲突。当你有多卡时可以分别指定CUDA_VISIBLE_DEVICES把模型分配到不同GPU上进一步隔离资源。5.4 镜像构建、打标签与分发构建镜像docker build -t vllm-qwen:1.0 .打标签并推送到私有仓库docker tag vllm-qwen:1.0 myregistry.example.com/vllm-qwen:1.0 docker push myregistry.example.com/vllm-qwen:1.0如果没有私有仓库也可以用docker save把镜像保存为tar包在目标机器上docker load导入docker save vllm-qwen:1.0 | gzip vllm-qwen-1.0.tar.gz把tar包拷贝到目标机器后gunzip -c vllm-qwen-1.0.tar.gz | docker load这种方式很适合内网离线环境。目标机器只要有Docker运行环境和NVIDIA驱动以及container toolkit就可以直接起服务。我自己的习惯是如果目标部署机器能直连模型仓库ModelScope/HuggingFace镜像中就不带权重用Compose挂载本地目录如果目标机器完全离线且没有预置权重那就只能做完整镜像分发。两种方式在Dockerfile和Compose里的配置略有差异建议两种方案都准备好按实际场景切换。6. 常见问题与排查技巧整个流程我走过的坑不少下面这些是出现频率最高的每个都给了排查建议。现象原因排查与解决WSL2启动报“未启用虚拟化”BIOS中虚拟化技术被关闭进BIOS开启Intel VT-x或AMD SVMWSL2里执行nvidia-smi报错Windows显卡驱动过旧或未正确安装更新到最新版驱动重启WSL2vLLM启动报CUDA out of memory模型权重KV Cache超过显存容量降低gpu-memory-utilization或max-model-len或改用量化模型HuggingFace下载超时/断流网络访问不稳定设置HF_ENDPOINT为国内镜像站或用ModelScope模型加载后中文乱码或输出异常模型tokenizer配置问题或模型路径不对确认权重目录里包含tokenizer.json、config.json等完整文件Docker Desktop启动失败提示虚拟化不支持Windows虚拟化功能或BIOS关闭检查VirtualMachinePlatform和BIOS虚拟化开关多卡部署时速度反而变慢卡间通信瓶颈模型太小不适合张量并行小模型用单卡足够大模型才用tensor-parallel-size容器里访问不到GPU未安装nvidia-container-toolkit安装插件并重启Docker守护进程和网络相关的排查方向我再多说一句。如果你在下载模型时碰到各种奇怪的超时或校验错误第一反应别去改代码先确认环境变量是否正确。HuggingFace侧HF_ENDPOINT和HF_HOME这两个变量最容易影响行为。HF_HOME指定缓存根目录如果你希望模型下载后存放在一个可控的目录而不是默认的~/.cache/huggingface最好手动设置。export HF_HOME/data/huggingface export HF_ENDPOINThttps://hf-mirror.comModelScope侧可通过设置MODELSCOPE_CACHE指定缓存目录。这样你在调试模型路径时永远不会出现“明明下载了但找不到文件”的情况。最后再讲一个关于--served-model-name不生效的坑。如果你直接修改了--model的传参但忘了同步--served-model-name调用接口时可能会报The model xxx does not exist。因为OpenAI兼容接口的/v1/models里暴露的是served-model-name不是模型的文件夹名字。这个命名在客户端对接时要保持一致省得来回排查半天。还有一点经验之谈WSL2里如果长时间跑大模型服务Windows会自动回收内存导致WSL2里的进程被kill尤其是开机后没有主动设置WSL2内存上限时更容易遇到。我在.wslconfig里用[experimental] autoMemoryReclaimgradual这个配置项做了调整可以避免内存吃紧时被强制重新回收。不同版本的Windows对这条配置支持不同如果你的系统较新可以试一下确实能减少很多烦心事。写在最后的实操心得从零开始把vLLM在Windows WSL2上跑通再走到Docker化分发这条路我完整走下来最大的感受是环境坑比模型坑多。模型本身只要权重完整、路径正确vLLM基本不会让你大动干戈。反倒是WSL2的虚拟化开关、NVIDIA驱动的透传、Docker的GPU插件每一步都可能成为拦路虎。所以我的建议是每一个阶段先做最小验证WSL2装完先跑nvidia-smiDocker装完先跑GPU容器模型下完先看一眼目录结构再启动vLLM。这样哪怕出了问题排查范围也很小。配置上我目前的主力环境是Win11 WSL2 Ubuntu 22.04 RTX 4090 24GB vLLM 0.6.x Qwen2.5-7B-InstructAWQ量化。日常开发调试用的是HuggingFace镜像站下载权重跑生产环境服务时用Docker Compose编排镜像只含运行环境权重通过挂载卷共享。这套组合实操下来稳定性和性能都让我满意。后面你可以继续扩展的方向也不少比如给vLLM服务加一个简单的鉴权层、对接一个Web UI比如Chatbot UI、或者把多模型和LoRA动态加载玩起来。技术上都是顺着这条路再往前走环境基础打牢了后面就都是锦上添花。