围绕DeepSeek模型在vLLM上的部署，梳理环境配置、模型加载、接口联调与性能调优的关键步骤，为教学实验和生产落地提供可复用的实战路径。
DeepSeek系列模型在推理任务中的使用频率持续上升，vLLM凭借PagedAttention和连续批处理成为常见的推理服务框架。把模型从权重文件变成稳定可用的API服务，需要跨越依赖匹配、显存规划、接口联调和压测调优几个环节，任何一个环节处理不当都会让部署停在“能启动但不好用”的状态。下面按实际落地顺序展开，重点说明每个阶段的操作要点和教学场景中的常见问题。
1. 环境与依赖准备
部署DeepSeek模型前先确定硬件和软件基线。DeepSeek系列包含V3、R1以及蒸馏版本，参数量从7B到671B不等，显存需求差异很大。教学实验通常选择DeepSeek-R1-Distill-Qwen-7B或14B，单张24GB显卡即可完成推理验证；生产环境若使用DeepSeek-V3则需要多机多卡并启用张量并行或专家并行。需要核对GPU型号、驱动版本、CUDA版本与vLLM发行版的兼容关系，常见组合是CUDA 12.1以上、PyTorch 2.4以上、Python 3.10或3.11。不要直接安装最新版vLLM，应该根据CUDA版本选择对应wheel，必要时使用官方容器镜像固定环境。
在指导学生的过程中，环境核验要形成可复现的记录。用nvidia-smi确认驱动和显存，用nvcc –version确认CUDA编译工具链，用Python命令确认torch.cuda.is_available返回True，确保PyTorch能识别GPU。依赖安装完成后把vLLM、transformers、torch版本写入requirements.txt，避免不同机器上出现“我这里能跑”的问题。国内网络环境还要配置HF_ENDPOINT或MODEL_SCOPE镜像，减少模型下载失败。容器化是更稳妥的做法，vllm/vllm-openai镜像已经包含运行时依赖，挂载模型目录和缓存目录后可以直接启动，但要注意容器内CUDA版本与宿主机驱动匹配。
还需要提前规划磁盘和内存。DeepSeek-R1-Distill-Qwen-7B权重约15GB，14B约30GB，32B约65GB，下载和转换过程会额外占用空间。教学环境建议单独挂载数据盘，模型缓存目录设置到空间充足的位置。若使用量化版本，要确认vLLM支持的量化格式，例如AWQ、GPTQ或FP8，并在加载时传入对应参数。环境准备阶段做得扎实，后续启动服务时才能把问题定位在模型或参数上，而不是反复排查依赖冲突。
2. 模型获取与vLLM服务启动
模型获取有Hugging Face和ModelScope两条路径，选择取决于网络条件。以DeepSeek-R1-Distill-Qwen-7B为例，可以用huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-7B –local-dir ./models/deepseek-r1-7b下载权重和tokenizer。下载完成后检查目录中是否包含config.json、tokenizer.json、model.safetensors等文件，缺少文件会导致vLLM加载失败。启动命令通常使用OpenAI兼容服务入口：python -m vllm.entrypoints.openai.api_server –model ./models/deepseek-r1-7b –served-model-name deepseek-r1 –host 0.0.0.0 –port 8000 –gpu-memory-utilization 0.9 –max-model-len 8192。单卡7B模型一般不需要张量并行，14B以上或多卡环境要加–tensor-parallel-size，DeepSeek-V3这类MoE模型还需关注专家并行参数和–trust-remote-code选项。
参数设置直接决定服务能否稳定运行。–gpu-memory-utilization控制vLLM可占用的显存比例，设得过高容易在长请求时触发OOM，设得过低会浪费KV cache空间；–max-model-len要结合业务上下文长度设置，盲目开到模型上限会显著增加显存占用。启动后观察日志中的权重加载、KV cache分配和CUDA graph编译信息，出现CUDA out of memory时优先降低max-model-len或gpu-memory-utilization，而不是反复重启。服务就绪后访问:8000/health返回200，说明进程已经可以接收请求；访问/v1/models可以看到served-model-name对应的模型标识。
教学场景适合采用“先小后大”的路径。先让学生用7B蒸馏模型跑通完整启动流程，理解模型目录、服务端口、模型名称三者之间的关系，再迁移到14B或32B模型，观察张量并行参数变化对启动日志和显存占用的影响。常见错误包括模型路径写错、tokenizer与模型不匹配、端口被占用、容器内没有挂载模型目录。把这些错误现象和排查命令记录下来，比只背启动命令更有价值。
3. OpenAI兼容接口联调与业务接入
vLLM的OpenAI兼容接口降低了业务接入成本。服务启动后，/v1/chat/completions接收聊天请求，/v1/completions接收补全请求，/v1/models返回模型列表，鉴权字段可以传空字符串，因为本地服务默认不校验API key。用Python的openai SDK接入时，把base_url设置为:8000/v1，api_key设置为EMPTY，model填写启动命令中的served-model-name。请求体里可以设置messages、temperature、max_tokens、stream等参数，流式返回适合课堂演示，因为可以看到token逐步生成的过程，也便于业务端实现打字机效果。
联调阶段要验证请求结构、返回字段和异常处理。非流式返回的choices[0].message.content是主要文本，usage字段记录prompt_tokens、completion_tokens和total_tokens，这些数据是后续计费和容量规划的依据。DeepSeek-R1系列在推理任务中可能返回推理过程相关字段，业务端需要确认vLLM版本和模型模板是否支持，避免把推理内容直接混入最终答案。生产接入不能在业务代码里直连推理服务，应该在中间加一层网关，处理鉴权、限流、超时、重试和日志脱敏。教学时让学生分别用curl和Python SDK发起请求，对比请求头、请求体和响应JSON，理解OpenAI协议在本地服务中的映射关系。
业务接入还要考虑并发和会话管理。vLLM支持连续批处理，多个请求会动态合并，但客户端仍需设置合理的超时时间，避免长请求拖垮线程池。对于多轮对话，messages数组要按角色顺序维护，system提示词放在首位，历史轮次过多时要做截断或摘要，否则会快速消耗上下文窗口。把模型名称、接口地址、超时时间、最大token数做成配置项，方便在测试环境和生产环境之间切换。联调完成后保留一组固定测试用例，每次更换模型版本或调整启动参数后重新跑一遍，确保接口行为没有漂移。
4. 性能压测、显存调优与生产化运维
服务能跑通不等于能承载业务流量，压测是部署流程中必须补上的一环。vLLM自带benchmark_serving.py，可以指定数据集、请求速率和并发数，输出吞吐、首token延迟TTFT、每token延迟TPOT等指标。教学实验可以设计阶梯并发，从1、4、8、16逐步增加，观察吞吐上升和延迟拐点，找到当前显存配置下的合理并发区间。压测时同时用nvidia-smi或DCGM采集GPU利用率和显存占用，若GPU利用率长期偏低而请求排队明显，说明瓶颈可能在max-num-seqs或调度参数；若显存接近上限且延迟抖动大，则需要降低max-model-len或启用量化。
调优要围绕显存和批处理展开。–gpu-memory-utilization决定KV cache可用空间，–max-num-seqs控制并发序列数，–enable-prefix-caching对共享系统提示词的场景能减少重复计算，chunked prefill有助于长请求与短请求混合时的调度公平性。DeepSeek的MoE模型在专家并行下对通信和负载均衡更敏感，生产环境要结合张量并行度、专家并行度和节点间网络带宽做联合调整。量化方面，AWQ和GPTQ能降低显存占用，FP8在支持的新一代GPU上更有优势，但量化会带来精度损失，需要用业务评测集验证答案质量，不能只看吞吐数字。
生产化运维要把服务当成有状态组件管理。用Kubernetes部署时配置就绪探针和存活探针，就绪探针指向/health，存活探针结合进程状态和端口检测；模型权重放在共享存储或镜像层，启动时通过环境变量注入模型路径和并行参数。监控接入Prometheus，采集vLLM暴露的请求数、排队时间、KV cache使用率和token吞吐，配合Grafana做告警。模型版本升级采用滚动更新，先切小流量验证接口兼容性和输出质量，再逐步扩大。教学指导中可以把压测报告、调优记录和故障复盘作为课程交付物，让学生理解部署不是一次性的命令执行，而是持续观测和迭代的过程。
