保姆级教程：从0开始用vLLM部署DeepSeek-R1-Distill-Qwen-1.5B

保姆级教程：从0开始用vLLM部署DeepSeek-R1-Distill-Qwen-1.5B

1. 引言

1.1 学习目标

本文旨在为开发者提供一份完整、可执行、零基础入门的实践指南，帮助你使用vLLM 框架成功部署轻量化大模型DeepSeek-R1-Distill-Qwen-1.5B。通过本教程，你将掌握：

• 如何下载并准备模型文件
• 使用 vLLM 启动 OpenAI 兼容 API 服务
• 配置参数优化显存占用
• 编写客户端代码进行推理测试（包括流式输出）
• 常见问题排查与性能调优建议

最终实现本地一键启动模型服务，并通过 Python 调用完成对话交互。

1.2 前置知识要求

• 熟悉 Linux 命令行操作
• 了解 Python 基础语法
• 具备基本的深度学习和大模型概念（如 token、KV Cache、推理延迟等）

2. 技术背景与核心组件介绍

2.1 vLLM：高效推理框架的核心优势

vLLM是由加州大学伯克利分校 LMSYS 组织开源的大语言模型推理和服务框架，其核心创新在于提出了一种名为PagedAttention的注意力机制管理技术。

核心特性：

• 高吞吐量：相比 Hugging Face Transformers，默认配置下提升 24 倍；相较于 TGI 提升 3.5 倍。
• 内存效率高：通过 PagedAttention 实现 KV Cache 的分页管理，显著降低显存浪费。
• OpenAI 接口兼容：支持openaiPython SDK 直接调用，便于集成到现有系统。
• 无缝集成 HuggingFace 模型：无需修改模型结构即可加载.safetensors或 PyTorch 权重。

提示：PagedAttention 类似于操作系统中的虚拟内存分页机制，允许非连续分配 KV 缓存，从而避免因预分配导致的显存碎片化问题。

2.2 DeepSeek-R1-Distill-Qwen-1.5B 模型解析

该模型是 DeepSeek 团队基于Qwen2.5-Math-1.5B进行知识蒸馏后得到的轻量级版本，专为边缘设备或资源受限场景设计。

关键设计亮点：

使用建议（官方推荐）：

• 温度设置：0.6（范围 0.5–0.7），防止重复或发散
• 不使用 system prompt，所有指令放入 user 消息
• 数学题提示词模板：请逐步推理，并将最终答案放在\boxed{}内
• 输出前强制添加\n，避免跳过思维链

3. 环境准备与依赖安装

3.1 硬件与软件环境要求

3.2 安装必要依赖包

# 创建虚拟环境（推荐） python -m venv vllm_env source vllm_env/bin/activate # 升级 pip pip install --upgrade pip # 安装核心依赖 pip install torch==2.5.1+cu124 torchvision==0.17.1+cu124 --extra-index-url https://download.pytorch.org/whl/cu124 pip install transformers==4.46.3 safetensors==0.4.5 triton==3.0.0 pip install vllm==0.6.6 pip install openai jupyterlab

注意：确保 CUDA 版本与 PyTorch 匹配。若使用其他版本，请参考 vLLM 官方文档 调整安装命令。

4. 模型下载与本地存储

4.1 下载地址

前往 Hugging Face 获取模型权重：

👉 https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B

4.2 下载方式（使用 git-lfs）

# 安装 git-lfs（如未安装） sudo apt-get install git-lfs # 克隆模型仓库 git lfs install git clone https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B # 移动至指定目录 mkdir -p /LLM mv DeepSeek-R1-Distill-Qwen-1.5B /LLM/

4.3 目录结构确认

/LLM/DeepSeek-R1-Distill-Qwen-1.5B/ ├── config.json ├── model.safetensors ├── tokenizer_config.json ├── special_tokens_map.json └── ...

确保关键文件存在，尤其是model.safetensors和config.json。

5. 启动 vLLM 服务

5.1 编写启动脚本api_server.sh

创建脚本文件：

nano api_server.sh

写入以下内容：

#!/bin/bash python -m vllm.entrypoints.openai.api_server \ --model /LLM/DeepSeek-R1-Distill-Qwen-1.5B \ --served-model-name deepseek-qwen-1.5b \ --dtype half \ --tensor-parallel-size 1 \ --max-model-len 1000 \ --gpu-memory-utilization 0.2 \ --port 8000

参数说明：

5.2 赋予执行权限并运行

chmod +x api_server.sh sh api_server.sh

5.3 查看启动日志

新开终端窗口查看日志：

cd /root/workspace cat deepseek_qwen.log

成功启动标志如下：

INFO: Started server process [PID] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

同时会显示显存占用信息：

model weights take 3.35GiB; non_torch_memory takes 0.23GiB; PyTorch activation peak memory takes 1.39GiB; the rest of the memory reserved for KV Cache is 1.38GiB.

此时总显存占用约6GB，远低于默认配置下的 28GB。

6. 客户端调用与功能验证

6.1 创建客户端类LLMClient

新建文件client_demo.py：

from openai import OpenAI import requests import json class LLMClient: def __init__(self, base_url="http://localhost:8000/v1"): self.client = OpenAI( base_url=base_url, api_key="none" # vLLM 不需要真实密钥 ) self.model = "deepseek-qwen-1.5b" # 必须与启动时 --served-model-name 一致 def chat_completion(self, messages, stream=False, temperature=0.6, max_tokens=2048): """基础聊天接口""" try: response = self.client.chat.completions.create( model=self.model, messages=messages, temperature=temperature, max_tokens=max_tokens, stream=stream ) return response except Exception as e: print(f"API调用错误: {e}") return None def stream_chat(self, messages): """流式输出对话""" print("AI: ", end="", flush=True) full_response = "" try: stream = self.chat_completion(messages, stream=True) if stream: for chunk in stream: if chunk.choices[0].delta.content is not None: content = chunk.choices[0].delta.content print(content, end="", flush=True) full_response += content print() # 换行 return full_response except Exception as e: print(f"流式对话错误: {e}") return "" def simple_chat(self, user_message, system_message=None): """简化对话接口""" messages = [] if system_message: messages.append({"role": "system", "content": system_message}) messages.append({"role": "user", "content": user_message}) response = self.chat_completion(messages) if response and response.choices: return response.choices[0].message.content return "请求失败"

6.2 测试用例执行

在if __name__ == "__main__":中添加测试逻辑：

if __name__ == "__main__": llm_client = LLMClient() # === 普通对话测试 === print("=== 普通对话测试 ===") response = llm_client.simple_chat( "请用中文介绍一下人工智能的发展历史", "你是一个有帮助的AI助手" ) print(f"回复: {response}") # === 流式输出测试 === print("\n=== 流式对话测试 ===") messages = [ {"role": "system", "content": "你是一个诗人"}, {"role": "user", "content": "写两首关于秋天的五言绝句"} ] llm_client.stream_chat(messages) # === 数学推理测试（按官方建议格式）=== print("\n=== 数学题推理测试 ===") math_prompt = ( "\n请逐步推理，并将最终答案放在\\boxed{}内。\n" "题目：一个矩形的长是宽的3倍，周长为32厘米，求它的面积。" ) result = llm_client.simple_chat(math_prompt) print(f"数学题回答:\n{result}")

6.3 运行测试脚本

python client_demo.py

预期输出包含正常文本生成结果，且流式输出逐字打印，无报错。

7. 常见问题与优化建议

7.1 显存不足（OOM）解决方案

7.2 API 调用失败排查

7.3 性能优化技巧

1. 开启前缀缓存（Prefix Caching）

bash --enable-prefix-caching

对相同前缀的请求复用 KV Cache，提升多轮对话效率。

1. 启用张量并行（多卡部署）

bash --tensor-parallel-size 2 # 双卡

1. 使用量化版本进一步压缩显存

若支持，可尝试 AWQ 或 GPTQ 量化模型：

bash --quantization awq

8. 总结

8.1 核心收获回顾

本文详细演示了如何从零开始使用vLLM成功部署DeepSeek-R1-Distill-Qwen-1.5B模型，涵盖以下关键步骤：

1. 环境搭建：安装 vLLM 及相关依赖
2. 模型获取：从 Hugging Face 下载并组织目录
3. 服务启动：编写脚本启动 OpenAI 兼容 API
4. 显存优化：通过--gpu-memory-utilization控制 KV Cache 占用
5. 客户端验证：实现普通与流式调用，完成多场景测试
6. 问题排查：常见错误处理与性能调优建议

8.2 最佳实践建议

• 生产环境务必设置合理的gpu-memory-utilization
• 数学类任务严格遵循官方提示词模板
• 优先使用流式输出提升用户体验
• 定期更新 vLLM 版本以获得性能改进

通过本教程，你已具备独立部署轻量级大模型的能力，可快速应用于智能客服、本地知识库问答、教育辅助等实际场景。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。