企业官网建设流程全解析

最近在折腾大模型本地部署的朋友，肯定绕不开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 python=3.10 -y conda activate vllm

Python版本我建议用3.10，vLLM对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-toolkit=12.1

装完验证：

nvcc --version

看到release 12.1之类的输出即可。需要注意的是，vLLM会有自己依赖的CUDA版本范围，一般在安装vLLM时会自动匹配PyTorch对应的CUDA运行时。所以你不需要手动装很重的CUDA Toolkit，真正起作用的是PyTorch自带的CUDA runtime，nvcc主要用于开发编译场景。我们装它主要是为了防止后续编译flash-attention等扩展时需要用到。

2.3 WSL2网络与存储优化

WSL2默认的NAT网络模式在多数场景够用，但如果你要跑需要外部设备访问的服务（比如局域网里另一台机器来调用你的推理接口），建议用mirrored网络模式。在%UserProfile%\.wslconfig里加：

[wsl2] networkingMode=mirrored memory=16GB processors=8

networkingMode=mirrored是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对齐，我建议手动先装PyTorch：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

然后装vLLM：

pip 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_ENDPOINT=https://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-size：GPU并行度。单卡设1，多卡设实际卡数。
• --host和--port：服务监听地址和端口。局域网或Docker里用0.0.0.0，仅本机调试可以设127.0.0.1。
• --gpu-memory-utilization：vLLM会按显存可用比例自动分配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 2

vLLM会自动做张量并行，把模型切分到多张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-world

GPU支持需要额外插件，即nvidia-container-toolkit：

sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker 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_DEVICES=0 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_DEVICES=0 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. 常见问题与排查技巧

整个流程我走过的坑不少，下面这些是出现频率最高的，每个都给了排查建议。

和网络相关的排查方向，我再多说一句。如果你在下载模型时碰到各种奇怪的超时或校验错误，第一反应别去改代码，先确认环境变量是否正确。HuggingFace侧，HF_ENDPOINT和HF_HOME这两个变量最容易影响行为。HF_HOME指定缓存根目录，如果你希望模型下载后存放在一个可控的目录，而不是默认的~/.cache/huggingface，最好手动设置。

export HF_HOME=/data/huggingface export HF_ENDPOINT=https://hf-mirror.com

ModelScope侧，可通过设置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] autoMemoryReclaim=gradual这个配置项做了调整，可以避免内存吃紧时被强制重新回收。不同版本的Windows对这条配置支持不同，如果你的系统较新，可以试一下，确实能减少很多烦心事。

写在最后的实操心得

从零开始把vLLM在Windows WSL2上跑通，再走到Docker化分发，这条路我完整走下来，最大的感受是：环境坑比模型坑多。模型本身只要权重完整、路径正确，vLLM基本不会让你大动干戈。反倒是WSL2的虚拟化开关、NVIDIA驱动的透传、Docker的GPU插件，每一步都可能成为拦路虎。所以我的建议是，每一个阶段先做最小验证：WSL2装完先跑nvidia-smi，Docker装完先跑GPU容器，模型下完先看一眼目录结构，再启动vLLM。这样哪怕出了问题，排查范围也很小。

配置上我目前的主力环境是：Win11 + WSL2 Ubuntu 22.04 + RTX 4090 24GB + vLLM 0.6.x + Qwen2.5-7B-Instruct（AWQ量化）。日常开发调试用的是HuggingFace镜像站下载权重，跑生产环境服务时用Docker Compose编排，镜像只含运行环境，权重通过挂载卷共享。这套组合实操下来，稳定性和性能都让我满意。

后面你可以继续扩展的方向也不少，比如给vLLM服务加一个简单的鉴权层、对接一个Web UI（比如Chatbot UI）、或者把多模型和LoRA动态加载玩起来。技术上都是顺着这条路再往前走，环境基础打牢了，后面就都是锦上添花。