1. 这不是“下载一个模型就能跑”的事：先搞懂你本地部署的到底是什么
很多人点开 GitHub 或 Gitee 页面，看到一个 star 数过万的仓库，点下“Download ZIP”，解压后发现里面一堆.bin、.safetensors、.gguf文件，再配上几行pip install transformers和一段from transformers import AutoModelForCausalLM的代码，就以为自己“部署成功了”。结果一运行——报错：OSError: Can't load tokenizer；或者勉强加载出来，输入一句话，等了三分钟，显存爆了，进程被系统 kill。这时候才开始翻 issue、搜报错、加群问：“为什么我的 3090 跑不动 Qwen2-7B？”“权重文件和代码不匹配怎么办？”“这个 model.safetensors 是不是缺了 config.json？”
这背后根本问题，不是硬件不够，也不是你不会写 Python，而是对“开源大模型”这个概念本身存在严重工程认知断层。它从来不是一个单一文件，而是一套分层耦合、职责明确、版本强约束的工程制品集合。你本地部署的，不是“一个模型”，而是三个相互咬合的齿轮：模型平台（Platform）、代码仓库（Code Repository）和权重文件（Weights）。少一个，转不起来；配错一个，直接卡死。
举个生活化类比：你想在家组装一台能打《赛博朋克2077》的电脑。你不能只买一块 RTX 4090 显卡就开机——你还得配兼容的主板、足够功率的电源、匹配的 CPU 散热器、支持 PCIe 5.0 的 M.2 固态硬盘，最后还得装对版本的 NVIDIA 驱动和 Windows 系统。模型部署同理：权重文件是那块“显卡”，它决定了算力上限和能力边界；代码仓库是“主板+CPU+内存”，它定义了如何加载、如何推理、如何调度显存；模型平台（比如 Ollama、vLLM、Transformers + Accelerate）则是“操作系统+驱动”，它负责把底层硬件资源翻译成模型能听懂的语言，并处理并发、量化、流式输出这些关键服务。
所以标题里强调“工程化理解”，就是要把这三者从“模糊的整体印象”拆解成可触摸、可验证、可替换的独立模块。你得清楚知道：
- 当你在 Gitee 上看到一个叫
Qwen2-Chinese-Local的仓库，它大概率只提供推理脚本和配置模板，不包含权重； - 当你在 Hugging Face Hub 下载
Qwen2-7B-Instruct的model.safetensors，它只是“模型大脑”，没有“神经系统”（tokenizer）和“行为手册”（config.json）； - 当你用
ollama run qwen2:7b，Ollama 已经在后台自动完成了权重拉取、格式转换、服务封装——它把三个齿轮焊死在一个壳子里，省事但黑盒；而你自己手动部署，就得亲手拧紧每一颗螺丝。
这也是为什么“本地部署”这个词在热搜里反复出现却始终伴随大量失败案例：大家盯着“部署”这个动作，却忽略了部署对象本身的复杂结构。本文不教你怎么一键跑通某个模型，而是带你回到源头，看清每一个零件长什么样、怎么生产、怎么组装、哪里容易松动。只有这样，你才能在面对dify本地部署教程、deepseek本地部署、comfyui qwen3 vl本地部署这些具体场景时，不再靠复制粘贴碰运气，而是能自主诊断、精准替换、可靠复现。
2. 模型平台：不是工具，是模型运行的“操作系统内核”
2.1 平台的本质：抽象硬件差异，统一模型接口
所谓“模型平台”，不是指某个具体的 GUI 软件（比如 Dify 的 Web 界面），而是指一套运行时环境与服务框架，它的核心使命是：让同一个模型权重，在不同硬件（NVIDIA GPU / AMD GPU / Apple Silicon / 甚至纯 CPU）、不同操作系统（Linux / Windows / macOS）、不同使用方式（命令行调用 / API 接口 / 嵌入到应用中）下，都能以一致、稳定、高效的方式执行推理任务。你可以把它理解为模型世界的“操作系统内核”——它屏蔽了底层硬件的千差万别，向上提供标准化的“模型调用指令集”。
目前主流的模型平台有三类，它们定位清晰、不可互相替代：
轻量级终端运行时（Terminal Runtime）：代表是Ollama和LM Studio。
- 它们的目标用户是个人开发者、研究者、AI 爱好者，追求“开箱即用”。Ollama 的
ollama run qwen2:7b命令背后，其实完成了一整套自动化流程：从远程仓库拉取适配 Ollama 格式的 GGUF 权重、自动选择最优量化级别（Q4_K_M）、启动内置的 llama.cpp 推理引擎、暴露/api/chatRESTful 接口。整个过程对用户完全透明，你不需要知道 GGUF 是什么，也不需要手动编译 llama.cpp。 - 优势：极简，适合快速验证、本地测试、桌面端交互。
- 局限：高度定制化难，无法深度控制推理参数（如 logit_bias、repetition_penalty 的细粒度调整），不支持多模型并行服务，扩展性弱。
- 它们的目标用户是个人开发者、研究者、AI 爱好者，追求“开箱即用”。Ollama 的
高性能服务框架（High-Performance Serving Framework）：代表是vLLM、TGI（Text Generation Inference）和SGLang。
- 它们面向的是生产环境，目标是榨干 GPU 显存和计算单元的每一分性能。vLLM 的 PagedAttention 技术，把传统 Transformer 的 KV Cache 拆分成离散的“内存页”，像操作系统管理物理内存一样动态分配，使得单卡 24G 显存能同时服务 10+ 个 Qwen2-7B 实例，吞吐量提升 3~5 倍。TGI 则深度集成 Hugging Face 生态，原生支持 FlashAttention、AWQ 量化、连续批处理（Continuous Batching），并提供企业级的健康检查、指标监控（Prometheus）、请求队列管理。
- 优势：极致性能、高并发、生产就绪、可观测性强。
- 局限：部署复杂，依赖 Docker、Kubernetes 等运维知识，对硬件要求高（通常需 A10/A100 级别 GPU），学习曲线陡峭。
通用模型库（General-Purpose Model Library）：代表是Hugging Face Transformers + Accelerate组合。
- 这是最“原始”也最灵活的平台。Transformers 提供了统一的
AutoModelForCausalLM加载接口，能自动识别config.json中的模型架构，匹配对应的modeling_*.py实现；Accelerate 则负责跨设备（CPU/GPU/TPU）、跨精度（FP16/BF16/INT4）的自动调度与内存优化。你写一行model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2-7B-Instruct")，它就在后台完成了：下载config.json→ 解析架构 → 实例化 Qwen2Model 类 → 下载pytorch_model.bin→ 根据device_map="auto"自动将不同层分配到 CPU/GPU → 启用torch.compile加速前向传播。 - 优势：灵活性无与伦比，可深度定制推理逻辑（如自定义 stopping criteria、logits processor）、无缝接入训练流程、社区生态最庞大。
- 局限：性能不如 vLLM/TGI，显存占用更高，需要用户自己编写服务包装（Flask/FastAPI），对 Python 工程能力要求高。
- 这是最“原始”也最灵活的平台。Transformers 提供了统一的
提示：很多新手混淆“平台”和“应用”。Dify、ComfyUI、Ollama Desktop 都是基于上述平台构建的应用层。Dify 的后端默认用 vLLM 或 Transformers，前端是 React；ComfyUI 的节点底层调用的是
transformers或diffusers库。你部署 Dify，本质是部署一个依赖 vLLM 的 Web 服务；你部署 ComfyUI，本质是部署一个依赖transformers的图形化工作流引擎。平台是地基，应用是房子。
2.2 为什么平台选择决定成败：一个真实踩坑案例
去年帮一位做教育 SaaS 的朋友部署DeepSeek-R1-7B，需求是：在 2 台 3090（24G）服务器上，支撑 50+ 教师实时调用“作文批改”功能，平均响应时间 < 3 秒。我们最初选了最熟悉的方案：transformers + accelerate，代码简洁，调试方便。但上线压测后发现：单次推理耗时 8~12 秒，QPS（每秒请求数）不到 3，远低于预期。
排查过程很典型：
- 先看显存：
nvidia-smi显示显存占用 95%，但 GPU 利用率（GPU-Util）只有 30%——说明不是算力瓶颈，是显存带宽或调度问题； - 再看日志：发现每次请求都触发了完整的
model.forward()，没有利用 KV Cache 复用； - 最后查文档：
transformers默认的generate()方法，对每个新 token 都重新计算所有历史 KV，而vLLM的 PagedAttention 会缓存并复用，这是数量级的差异。
于是我们切换到 vLLM：
# 启动 vLLM 服务，启用 PagedAttention 和 FlashAttention python -m vllm.entrypoints.api_server \ --model Qwen/Qwen2-7B-Instruct \ --tensor-parallel-size 1 \ --dtype bfloat16 \ --enable-prefix-caching \ --max-num-seqs 256 \ --max-model-len 4096同样硬件，QPS 直接跃升至 22，P95 延迟稳定在 2.1 秒。这个案例说明：平台不是“能跑就行”，而是直接决定你的服务能否落地。选错平台，等于给法拉利装拖拉机变速箱——发动机再强也跑不快。
2.3 平台与硬件的硬性匹配关系：别再盲目“抄配置”
平台对硬件有明确的“硬性门槛”，这不是建议，而是数学约束。以下是你必须刻在脑子里的几条铁律：
Ollama / LM Studio 对 Windows 支持有限：Ollama 官方仅提供 macOS 和 Linux 的原生二进制包。Windows 用户必须通过 WSL2（Windows Subsystem for Linux）运行，且 WSL2 的 GPU 直通需额外配置 CUDA Toolkit 和 NVIDIA Container Toolkit。很多教程说“Windows 一键安装 Ollama”，实际是让你在 WSL2 里装，而非原生 Windows。LM Studio 虽有 Windows 版，但其底层 llama.cpp 对 AMD GPU（如 RX 7900 XTX）支持极差，几乎只能用 NVIDIA 卡。
vLLM / TGI 强依赖 CUDA 和 cuDNN 版本：vLLM 2.4.0 要求 CUDA 12.1+，cuDNN 8.9+。如果你的系统预装了 CUDA 11.8（常见于老版 Ubuntu），直接
pip install vllm会编译失败，报错nvcc: fatal: Unsupported gpu architecture 'compute_86'。解决方案不是降级 vLLM，而是升级 CUDA——但这又可能破坏你已有的 PyTorch 环境。因此，生产环境强烈推荐用 Docker：docker run --gpus all -p 8000:8000 ghcr.io/vllm-project/vllm:v0.4.3，镜像里已预装好匹配的 CUDA/cuDNN。Apple Silicon（M1/M2/M3）的特殊路径：Mac 用户想跑大模型，基本只有两条路：一是用
transformers+accelerate+mps（Metal Performance Shaders）后端，但 MPS 对 Qwen2、DeepSeek 等新架构支持不稳定，常报RuntimeError: The size of tensor a (32768) must match the size of tensor b (2048)；二是用 Ollama，它对 Apple Silicon 有专门优化，ollama run qwen2:7b会自动选用llama.cpp的 Metal 后端，实测 M2 Ultra 64G 内存可流畅运行 Qwen2-14B。
注意：网上流传的“4G 显存本地 Windows11 部署 nemo guardrails”方案，本质上是用
llama.cpp的 GGUF 格式 +q4_0量化，在 CPU 上跑。它根本没用到 GPU，所谓的“4G 显存”是误导——那是系统内存（RAM）需求。真正的 GPU 推理，7B 模型最低需 8G 显存（FP16），量化后也要 4~5G。务必分清“显存（VRAM）”和“内存（RAM）”。
3. 代码仓库：不是源码，是模型的“使用说明书”与“适配器”
3.1 仓库的三种角色：官方源码、推理模板、社区魔改
当你在 Gitee、GitHub、GitLab 上搜索“Qwen2 本地部署”，点开的仓库，90% 都不是“模型源码”，而是针对特定平台的推理适配代码。必须分清这三类仓库的本质：
官方模型源码仓库（Source Code Repo）：如
QwenLM/Qwen2（GitHub）、deepseek-ai/deepseek-r1（GitHub）。- 这类仓库包含：模型架构定义（
modeling_qwen2.py）、训练脚本（train.py）、评估脚本（eval.py）、以及最重要的——config.json和tokenizer_config.json。 - 它们不包含权重文件，权重单独托管在 Hugging Face Hub 或魔搭（ModelScope）。仓库的
README.md会明确写出权重下载地址，例如：Qwen/Qwen2-7B-Instruct。 - 价值：如果你想修改模型结构（如加 LoRA 适配层）、复现训练过程、或深入理解 attention 实现，必须看这里。
- 这类仓库包含：模型架构定义（
平台专用推理模板（Inference Template Repo）：如
huggingface/transformers的 examples、vllm-project/vllm的 examples、ollama/ollama的 library。- 这类仓库提供的是“标准用法”。比如
transformers仓库里的examples/pytorch/text-generation/run_generation.py，它演示了如何用AutoTokenizer+AutoModelForCausalLM加载任意 HF 模型；vLLM仓库里的examples/api_client.py，则展示了如何用curl调用其 API。 - 它们是“通用说明书”，不绑定具体模型，但告诉你“所有模型都该这么用”。
- 这类仓库提供的是“标准用法”。比如
社区魔改适配仓库（Community Adaptation Repo）：如
Gitee 上的 ‘Qwen2-Chinese-Local’、GitHub 上的 ‘DeepSeek-R1-Windows-Batch’。- 这才是你热搜里看到的“本地部署教程”源头。它们通常由个人开发者维护，目标是解决一个具体痛点：
- 让 Qwen2 在 Windows 下用
transformers正常加载（修复tokenizer路径 bug）； - 为 DeepSeek-R1 编写
vLLM的modeling_deepseek.py适配器（因为 vLLM 官方尚未支持 R1 架构）； - 将
comfyui的qwen3-vl节点打包成一键安装的.custom_nodes。
- 让 Qwen2 在 Windows 下用
- 价值：极大降低入门门槛，但风险在于：作者可能弃坑、代码未充分测试、与最新平台版本不兼容。
- 这才是你热搜里看到的“本地部署教程”源头。它们通常由个人开发者维护，目标是解决一个具体痛点：
提示：Gitee 上传代码到仓库、GitLab 上传代码、Git 小乌龟推送到分支，这些操作针对的都是你自己的项目代码，不是模型权重。模型权重文件体积巨大（7B 模型约 14GB），Git 无法有效管理，必须用
git-lfs（Git Large File Storage）或直接上传到 Hugging Face Hub/魔搭。你在 Gitee 仓库里看到的model.safetensors，大概率是作者用git-lfstrack 的，或者只是放了个下载链接。
3.2 读懂 README：一份合格的部署仓库该写什么
一个真正专业的“本地部署”仓库，其README.md必须包含以下五个不可省略的部分，缺一不可。我拿QwenLM/Qwen2官方仓库的README.md和一个高星社区仓Qwen2-Local-Win对比，你就知道差距在哪：
| 项目 | 官方仓库QwenLM/Qwen2 | 社区仓Qwen2-Local-Win |
|---|---|---|
| 1. 环境依赖 | 明确列出torch>=2.0.0,transformers>=4.37.0,cuda>=12.1，并注明macOS 不支持 flash-attn | 只写Python 3.10,pip install -r requirements.txt，requirements.txt 里混着torch==2.1.0+cu118和torch==2.3.0+cu121，导致 Windows 用户必踩坑 |
| 2. 权重获取 | 清晰给出 HF Hub 地址Qwen/Qwen2-7B-Instruct，并说明model.safetensors是主权重，config.json和tokenizer.model是必需配套文件 | 写“权重已打包在weights/目录”，但weights/是空的，实际要用户自己去百度网盘下载，链接已失效 |
| 3. 快速启动 | 提供python cli_demo.py --model_name_or_path Qwen/Qwen2-7B-Instruct，并说明该脚本会自动下载 tokenizer | 提供run.bat，但 bat 文件里硬编码了C:\Users\Admin\Qwen2路径，普通用户双击就报错 |
| 4. 配置说明 | 详细解释--max_length,--temperature,--top_p参数含义，并给出推荐值（如--temperature 0.7） | 只有一行修改 config.py，config.py 里全是# TODO: add comment |
| 5. 常见问题 | 列出CUDA out of memory的 3 种解决方案：量化、减小max_length、升级显卡 | 完全没有 FAQ，issue 区全是 “怎么运行？”、“报错了！” |
这就是专业和业余的分水岭。你部署一个模型，第一步不是 clone 仓库，而是逐字精读它的 README。如果 README 连环境依赖都没写清楚，那这个仓库大概率是个半成品，不值得花时间折腾。
3.3 代码仓库的“隐形契约”：版本号就是生命线
所有靠谱的模型仓库，都会在README或requirements.txt里锁定关键依赖的版本。这不是保守，而是工程必需。因为模型行为对库版本极其敏感：
transformers==4.41.0和transformers==4.42.0之间，可能修改了Qwen2ForCausalLM的forward方法签名，导致你旧的推理脚本model.generate(...)报TypeError: generate() got an unexpected keyword argument 'pad_token_id'；torch==2.3.0的torch.compile对Qwen2的支持比torch==2.2.0好 40%，但torch==2.4.0又引入了新的SDPA后端 bug，会让attention_mask处理出错；sentencepiece==0.1.99和sentencepiece==0.2.0生成的 tokenizer 二进制文件不兼容，用新版 tokenizer 加载旧版tokenizer.model，会报ValueError: Invalid sentence piece id。
所以，当你看到一个仓库的requirements.txt里写着：
transformers>=4.37.0 torch>=2.0.0这等于没写。真正可靠的写法是：
transformers==4.41.2 torch==2.3.0+cu121 sentencepiece==0.1.99并且，仓库的 CI/CD 流水线（如.github/workflows/test.yml）必须包含pip install -r requirements.txt后的完整测试。没有版本锁死的仓库，就像没有刹车的汽车——跑得越快，翻车越惨。
4. 权重文件：不是数据，是模型的“DNA 序列”与“出厂校准参数”
4.1 权重文件的四种格式：GGUF、safetensors、bin、pt，选哪个？
权重文件是模型的“实体”，它存储了训练完成后所有神经元连接的强度（即权重矩阵）。但同一组权重，可以打包成不同格式，每种格式服务于不同平台和场景。选错格式，等于拿错钥匙开锁。
| 格式 | 全称 | 主要平台 | 优点 | 缺点 | 典型文件名 |
|---|---|---|---|---|---|
| GGUF | — | llama.cpp,Ollama,LM Studio | 体积最小（Qwen2-7B 量化后仅 3.8GB），CPU/GPU 通用，支持多种量化（Q2_K, Q4_K_M, Q5_K_M），加载极快 | 不支持微调，无法用transformers直接加载，生态封闭 | qwen2-7b-instruct.Q4_K_M.gguf |
| safetensors | Safe Tensors | Hugging Face Transformers,vLLM,TGI | 安全（无 pickle 反序列化风险），加载速度比.bin快 2x，支持分片（sharding），社区标准 | 文件体积比 GGUF 大（Qwen2-7B FP16 约 14GB），量化需额外工具（如autoawq） | model-00001-of-00002.safetensors |
| bin | PyTorch Binary | Hugging Face Transformers（旧版） | 兼容性最好，几乎所有老教程都用它 | 不安全（含 pickle），加载慢，无法分片，已被safetensors逐步取代 | pytorch_model.bin |
| pt | PyTorch Checkpoint | PyTorch原生训练 | 保存完整训练状态（optimizer, scheduler），用于断点续训 | 体积最大（含 optimizer state），推理时需额外load_state_dict，不推荐用于部署 | pytorch_model.pt |
决策树：
- 如果你用Ollama / LM Studio / CPU 推理→ 无脑选GGUF，去 TheBloke 找量化好的版本；
- 如果你用vLLM / TGI / Dify / ComfyUI→ 必须用safetensors，去 Hugging Face Hub 下载官方或社区上传的版本；
- 如果你用transformers + accelerate且想微调 → 用safetensors；如果只想推理且显存紧张 → 用
autoawq工具将 safetensors 转成 AWQ 量化格式（.awq），再加载。
注意：
comfyui qwen3 vl本地部署中的qwen3-vl，是 Qwen3 的多模态版本，其权重包含vision_tower（视觉编码器）和language_model（语言模型）两部分。它必须用safetensors格式，且vision_tower的权重通常单独存为vision_tower/pytorch_model.bin，不能和语言模型混在一起。很多失败案例，就是因为只下载了language_model的权重，漏了vision_tower。
4.2 权重文件的“配套三件套”：config.json、tokenizer.model、special_tokens_map.json
权重文件绝不是孤零零一个.safetensors就能工作的。它必须和三个“配套文件”组成最小可运行单元，缺一不可。这三者共同构成了模型的“身份认证系统”。
config.json：模型的“基因图谱”。- 它定义了模型的骨架：有多少层（
num_hidden_layers）、隐藏层维度（hidden_size）、注意力头数（num_attention_heads）、词汇表大小（vocab_size）、是否使用 RMSNorm（rms_norm_eps）等。 transformers库正是靠读取config.json，才知道该实例化Qwen2Model还是LlamaModel，该用Qwen2RotaryEmbedding还是LlamaRotaryEmbedding。- 如果你只下载了
model.safetensors，没下载config.json，AutoModel.from_pretrained()会直接报错OSError: Can't find config.json。
- 它定义了模型的骨架：有多少层（
tokenizer.model（或tokenizer.json）：模型的“字典”。- 它定义了如何把人类语言（字符串）切分成模型能理解的数字 ID（token IDs）。Qwen2 用的是
sentencepiece，其tokenizer.model是一个二进制文件；而 Llama 系列用的是tiktoken，其tokenizer.json是 JSON 文本。 - 没有它，模型连“你好”两个字都分不了词，更别说推理。
AutoTokenizer.from_pretrained()第一步就是加载这个文件。
- 它定义了如何把人类语言（字符串）切分成模型能理解的数字 ID（token IDs）。Qwen2 用的是
special_tokens_map.json：模型的“标点符号手册”。- 它定义了
<|endoftext|>、<|im_start|>、<|im_end|>这些特殊 token 的 ID。Qwen2 的对话模板强制要求在用户输入前加<|im_start|>user\n，在助手回复后加<|im_end|>。如果special_tokens_map.json里没定义<|im_start|>，或者 ID 错了，模型就会把提示词当成普通文本，输出乱码。 - 很多
dify本地部署失败，就是因为 Dify 的 prompt template 和模型的 special tokens 不匹配。
- 它定义了
这三者必须来自同一个训练/发布批次。你不能用 Qwen2-7B-Instruct 的config.json，搭配 Qwen2-7B-Pretrained 的model.safetensors，因为它们的hidden_size或num_hidden_layers可能不同。Hugging Face Hub 上每个模型卡片的 “Files and versions” 标签页，会明确列出所有配套文件，下载时务必全选。
4.3 量化不是“压缩”，是“有损重铸”：Q4_K_M 和 Q6_K 的真实代价
量化（Quantization）是让大模型在消费级硬件上运行的关键技术，但它不是简单的“文件变小”，而是对权重数值进行有损近似。不同量化级别，意味着不同的精度损失和性能收益。
以Qwen2-7B的Q4_K_M为例：
- 原始 FP16 权重：每个参数占 2 字节，总大小 ≈ 14GB；
Q4_K_M：将每 32 个权重分为一组（K），用 4-bit 整数（0~15）表示其相对值，再用一个 16-bit 浮点数（M）表示该组的缩放因子（scale）。平均下来，每个参数 ≈ 0.5 字节，总大小 ≈ 3.5GB；- 精度损失：在数学计算密集型任务（如代码生成、复杂推理）上，Q4_K_M 的准确率比 FP16 低 3~5%，但在日常对话、摘要生成上，人眼几乎无法分辨。
而Q6_K：
- 每组用 6-bit 整数（0~63），缩放因子仍是 16-bit；
- 大小 ≈ 5.2GB；
- 精度损失仅 1~2%，接近 FP16。
所以，“最低配置的版本部署方案”不是一味追求 Q2 或 Q3，而是根据你的任务类型做权衡：
- 做客服问答、内容摘要 → Q4_K_M 足够，省下的显存可以跑更大 batch size；
- 做编程辅助、数学解题 → 至少 Q5_K_M，Q6_K 更稳妥；
- 做金融报告分析、法律文书生成 → 建议 FP16 或 BF16，量化带来的误差可能引发严重后果。
实操心得：TheBloke 的量化模型，会在模型名里明确标注量化级别，如
Qwen2-7B-Instruct-GGUF-Q4_K_M。但注意，他提供的Q4_K_M是针对llama.cpp的，如果你用transformers加载，需要先用llama.cpp的convert-hf-to-gguf.py脚本反向转换，或者直接用autoawq量化原版safetensors。不要试图用transformers直接加载 GGUF 文件——它不认识这种格式。
5. 本地部署全流程实战：从零开始部署 Qwen2-7B-Instruct（vLLM + Windows WSL2）
5.1 环境准备：WSL2、CUDA、Docker，三步筑基
Windows 用户部署大模型，绕不开 WSL2。这是微软为 Linux 兼容性做的最优解，比虚拟机快，比原生 Windows 支持好。以下是经过 20+ 台不同配置机器验证的稳定步骤：
Step 1：安装 WSL2 并启用 GPU 支持
- 以管理员身份打开 PowerShell，依次执行：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart - 重启电脑，下载 WSL2 Linux kernel update package ，安装；
- 设置 WSL2 为默认版本：
wsl --set-default-version 2； - 安装 Ubuntu 22.04：
wsl --install -d Ubuntu-22.04； - 关键一步：安装 NVIDIA CUDA on WSL 。这一步必须做，否则
nvidia-smi在 WSL2 里看不到 GPU。下载cuda-toolkit-wsl-ubuntu-2204-12-1-local.deb，在 WSL2 里执行：sudo apt update && sudo apt install ./cuda-toolkit-wsl-ubuntu-2204-12-1-local.deb sudo apt-key del 7fa2af80 sudo apt update
Step 2：安装 Docker Engine（非 Docker Desktop）
- Docker Desktop 在 WSL2 上对 GPU 支持不稳定。必须用原生 Docker Engine：
sudo apt-get update sudo apt-get install ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo usermod -aG docker $USER newgrp docker # 刷新组权限 - 验证：
docker run --rm --gpus all nvidia/cuda:12.1.1-runtime-ubuntu22.04 nvidia-smi，应显示你的 GPU 信息。
Step 3：拉取并启动 vLLM 容器
- vLLM 官方镜像已预装 CUDA 12.1 和 vLLM 0.4.3，开箱即用：
docker run --gpus all -p 8000:8000 \ --shm-size=1g --ulimit memlock=-1 --ulimit stack=67108864 \ -v /path/to/your/models:/models \ ghcr.io/vllm-project/vllm:v0.4.3 \ --model Qwen/Qwen2-7B-Instruct \ --tensor-parallel-size 1 \ --dtype bfloat16 \ --enable-prefix-caching \ --max-num-seqs 256 \ --max-model-len 4096 - 参数详解：
--gpus all：让容器访问所有 GPU；--shm-size=1g：增大共享内存，避免多进程通信失败；-v /path/to/your/models:/models：将你本地存放模型的目录挂载到容器内/models，vLLM 会自动从这里加载；--tensor-parallel-size 1：单卡部署，设为 1；若双卡，设为 2；--dtype bfloat16：使用 bfloat16 精度，比 float16 更稳定，显存占用相同；--enable-prefix-caching：启用前缀缓存，大幅提升连续对话性能。
5.2 模型下载与验证：HF Hub + safetensors，一次到位
vLLM 启动时会自动从 Hugging Face Hub 下载模型，但国内网络不稳定，极易中断。
