DeepSeek-R1-Distill-Qwen-1.5B 部署指南：vLLM 与 Open-WebUI 集成

1. 为何选择 DeepSeek-R1-Distill-Qwen-1.5B

DeepSeek-R1-Distill-Qwen-1.5B 是一款轻量级大模型，基于通义千问 Qwen-1.5B 进行深度蒸馏，包含 80 万条高质量 R1 推理链。该模型参数为 15 亿，fp16 整模约 3.0 GB，量化至 GGUF-Q4 后压缩至 0.8 GB，适合在低显存设备（如 4GB 显存）上运行。

模型支持 Apache 2.0 协议，商用免费。在 MATH 数据集表现优异，支持 Python 函数生成、JSON 输出及快速响应（超过 200 tokens/s），适用于日常脚本编写、方程求解及 API 调试。

2. 环境准备

2.1 硬件要求

最低配置：4 GB 显存（RTX 3050 / A10G / RTX 4060）
推荐配置：6 GB 显存（RTX 3060 / A10 / L4），可满速运行 fp16
边缘设备实测：RK3588（8GB 内存+GPU）16 秒完成 1k token 推理
手机端：苹果 A17 芯片（iPhone 15 Pro）量化版达 120 tokens/s

提示：若无 NVIDIA 显卡，支持 Ollama 和 CPU GGUF 推理（速度约 5–10 tokens/s）。

2.2 软件环境

以 Ubuntu 22.04 LTS 为例（Windows 用户建议 WSL2）：

# 更新系统并安装基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3-pip python3-venv git curl wget build-essential

# 安装 NVIDIA 驱动（如未安装）
sudo apt install -y nvidia-driver-535
sudo reboot

确认 CUDA 可用：

nvidia-smi
nvcc --version

2.3 Python 环境

创建独立虚拟环境以避免依赖冲突：

python3 -m venv ~/deepseek-env
source ~/deepseek-env/bin/activate
pip install --upgrade pip wheel setuptools

注意：vLLM 对 CUDA 版本和 PyTorch ABI 敏感，隔离环境是避免 ImportError 的关键。

3. 模型获取与格式选择

3.1 模型来源

模型托管于 Hugging Face：

模型主页：https://huggingface.co/DeepSeek-AI/DeepSeek-R1-Distill-Qwen-1.5B
GGUF 量化版（推荐新手）：https://huggingface.co/DeepSeek-AI/DeepSeek-R1-Distill-Qwen-1.5B-GGUF
FP16 完整版：https://huggingface.co/DeepSeek-AI/DeepSeek-R1-Distill-Qwen-1.5B/tree/main

推荐首次部署选 Q4_K_M 量化档（约 0.8 GB），平衡精度与速度。

3.2 下载方式

mkdir -p ~/models/deepseek-r1
cd ~/models/deepseek-r1
pip install hf-transfer
export HF_TRANSFER=1

huggingface-cli download \
--resume-download \
--local-dir . \
DeepSeek-AI/DeepSeek-R1-Distill-Qwen-1.5B-GGUF \
--include "q4_k_m/*.gguf" \
--include "tokenizer.json" \
--include "config.json"

文件结构示例：

~/models/deepseek-r1/
├── tokenizer.json
├── config.json
└── q4_k_m/
    └── deepseek-r1-distill-qwen-1.5b.Q4_K_M.gguf

4. vLLM 服务部署

4.1 安装 vLLM

vLLM 采用 PagedAttention 技术提升显存利用率。

pip install vllm==0.6.3.post1
python -c "from vllm import LLM; print('vLLM ready')"

提示：vLLM ≥0.6.2 才原生支持 Qwen 系模型的 RoPE 位置编码。

4.2 启动 vLLM API 服务

vllm serve \
--model ~/models/deepseek-r1/q4_k_m/deepseek-r1-distill-qwen-1.5b.Q4_K_M.gguf \
--tokenizer ~/models/deepseek-r1/tokenizer.json \
--dtype auto \
--gpu-memory-utilization 0.9 \
--max-model-len 4096 \
--port 8000 \
--host 0.0.0.0 \
--served-model-name deepseek-r1-qwen-1.5b

验证服务：

curl http://localhost:8000/v1/models

5. Open-WebUI 部署

5.1 安装 Open-WebUI

使用 Docker 一键部署：

docker pull ghcr.io/open-webui/open-webui:main
mkdir -p ~/open-webui/data

docker run -d \
--network=host \
--name open-webui \
-v ~/open-webui/data:/app/backend/data \
-e OLLAMA_BASE_URL=http://host.docker.internal:8000 \
-p 3000:8080 \
ghcr.io/open-webui/open-webui:main

核心技巧：--network=host + http://host.docker.internal:8000 确保容器内访问宿主机 vLLM 服务。

5.2 首次访问与模型绑定

访问 http://localhost:3000，注册账号后点击右上角「+ Add Model」→ 选择「Custom OpenAI Endpoint」。

Model Name：deepseek-r1-qwen-1.5b
API Base URL：http://localhost:8000/v1
API Key：留空

6. 进阶配置

6.1 启用 JSON 模式

在 Open-WebUI 设置中开启「JSON Mode」，提示词末尾指定 JSON Schema 格式，模型将直接返回合法 JSON。

6.2 函数调用实战

Open-WebUI 支持插件机制。创建本地计算器函数（保存为 ~/open-webui/data/functions/calculator.py）：

def calculate(expression: str) -> str:
    try:
        return str(eval(expression))
    except:
        return "计算错误"

聊天中输入'帮我算一下 123 * 456 + 789'，模型将自动调用函数。

6.3 长文本摘要

模型上下文为 4k token。处理长文档时建议分段处理，每段单独提问总结后再整合。

6.4 速度再提速

若 GPU 支持 Ampere 架构，可编译 FlashAttention-2：

pip uninstall flash-attn -y
pip install flash-attn --no-build-isolation

重启 vLLM 时添加参数：--enable-flash-attn

6.5 日志与监控

调试时建议开启详细日志：

vllm serve ... --log-level DEBUG > vllm-debug.log 2>&1 &
watch -n 1 'nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader,nounits'

7. 总结

本文介绍了从环境初始化、模型下载、vLLM 服务启动到 Open-WebUI 接入的全流程。最终交付的本地智能体可在 4GB 显存设备上稳定运行，具备数学推理、函数调用及结构化输出能力，无需联网即可体验大模型功能。