从零开始部署：DeepSeek-R1-Distill-Qwen-1.5B全流程实操手册

从零开始部署：DeepSeek-R1-Distill-Qwen-1.5B全流程实操手册

1. 引言

1.1 学习目标

本文旨在为开发者提供一份完整、可执行的DeepSeek-R1-Distill-Qwen-1.5B模型本地化部署指南。通过本教程，您将掌握：

• 如何配置支持 CUDA 的 Python 环境
• 模型下载与缓存管理
• 基于 Gradio 的 Web 服务搭建
• 后台运行与 Docker 容器化部署
• 常见问题排查方法

最终实现一个稳定运行在 GPU 上的推理服务，支持数学推理、代码生成和逻辑推导等高级任务。

1.2 前置知识

建议读者具备以下基础： - Linux 命令行操作能力 - Python 编程经验 - 对 Hugging Face 模型生态有一定了解 - 初步的 Docker 使用经验（非必须）

1.3 教程价值

不同于碎片化的部署笔记，本文提供的是端到端可复现的工程实践路径，涵盖从环境准备到生产级部署的全部关键环节，并附带优化建议与故障应对策略，适合用于科研测试或轻量级产品原型开发。

2. 环境准备

2.1 系统要求确认

确保您的设备满足以下最低配置：

提示：可通过nvidia-smi命令验证 GPU 驱动及 CUDA 版本是否正常加载。

2.2 Python 环境搭建

推荐使用虚拟环境隔离依赖：

# 创建虚拟环境 python3.11 -m venv deepseek-env # 激活环境 source deepseek-env/bin/activate # 升级 pip pip install --upgrade pip

2.3 核心依赖安装

根据项目说明，需安装如下包：

pip install torch==2.9.1+cu128 \ transformers==4.57.3 \ gradio==6.2.0 \ --extra-index-url https://download.pytorch.org/whl/cu128

注意：请确保 PyTorch 安装的是 CUDA 12.8 版本，否则无法启用 GPU 加速。

3. 模型获取与本地缓存

3.1 模型特性概述

DeepSeek-R1-Distill-Qwen-1.5B是基于 Qwen-1.5B 架构，通过 DeepSeek-R1 强化学习数据进行知识蒸馏训练得到的轻量级推理模型，具备以下优势：

• 高推理精度：在数学与代码任务上显著优于同规模基线模型
• 低延迟响应：适用于实时交互场景
• 小体积易部署：适合边缘设备或资源受限环境

3.2 下载模型文件

若尚未下载模型，执行以下命令：

# 安装 Hugging Face CLI 工具 pip install huggingface_hub # 登录账号（如需私有模型访问权限） huggingface-cli login # 下载模型 huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --local-dir /root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B

路径说明：Hugging Face 默认缓存路径为~/.cache/huggingface/，此处已指定固定路径以避免重复下载。

3.3 验证模型加载

创建测试脚本test_load.py：

from transformers import AutoTokenizer, AutoModelForCausalLM MODEL_PATH = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" try: tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH) model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, device_map="auto", torch_dtype="auto" ) print("✅ 模型加载成功！") print(f"模型架构: {model.config.architectures}") print(f"参数量: ~{model.num_parameters() / 1e9:.1f}B") except Exception as e: print(f"❌ 模型加载失败: {str(e)}")

运行后应输出类似信息：

✅ 模型加载成功！ 模型架构: ['QWenLMHeadModel'] 参数量: ~1.5B

4. Web 服务开发与启动

4.1 应用程序结构

假设app.py内容如下：

import gradio as gr from transformers import AutoTokenizer, AutoModelForCausalLM # 全局变量（首次加载较慢） MODEL_PATH = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH) model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, device_map="auto", torch_dtype="auto" ) def generate_text(prompt, max_tokens=2048, temperature=0.6, top_p=0.95): inputs = tokenizer(prompt, return_tensors="pt").to(model.device) outputs = model.generate( **inputs, max_new_tokens=max_tokens, temperature=temperature, top_p=top_p, do_sample=True, pad_token_id=tokenizer.eos_token_id ) response = tokenizer.decode(outputs[0], skip_special_tokens=True) return response[len(prompt):] # 去除输入部分 # 构建界面 with gr.Blocks(title="DeepSeek-R1-Distill-Qwen-1.5B") as demo: gr.Markdown("# 🧠 DeepSeek-R1-Distill-Qwen-1.5B 推理服务") gr.Markdown("支持数学、代码、逻辑推理任务") with gr.Row(): with gr.Column(): prompt = gr.Textbox(label="输入提示", lines=5, placeholder="请输入您的问题...") max_tokens = gr.Slider(minimum=256, maximum=2048, value=2048, step=128, label="最大生成长度") temperature = gr.Slider(minimum=0.1, maximum=1.0, value=0.6, step=0.05, label="温度 (Temperature)") top_p = gr.Slider(minimum=0.7, maximum=1.0, value=0.95, step=0.01, label="Top-P") submit_btn = gr.Button("生成", variant="primary") with gr.Column(): output = gr.Textbox(label="模型输出", lines=12) submit_btn.click( fn=generate_text, inputs=[prompt, max_tokens, temperature, top_p], outputs=output ) if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

4.2 启动服务

激活环境并运行：

python3 /root/DeepSeek-R1-Distill-Qwen-1.5B/app.py

成功启动后，终端会显示：

Running on local URL: http://0.0.0.0:7860

4.3 访问 Web 界面

打开浏览器访问：

http://<服务器IP>:7860

即可看到交互式界面，支持输入文本并生成结果。

5. 生产级部署方案

5.1 后台持久化运行

使用nohup实现后台常驻：

# 启动服务并记录日志 nohup python3 app.py > /tmp/deepseek_web.log 2>&1 & # 查看运行状态 tail -f /tmp/deepseek_web.log

停止服务脚本

# 自动查找并终止进程 ps aux | grep "python3 app.py" | grep -v grep | awk '{print $2}' | xargs kill

建议：可将其封装为stop.sh脚本以便管理。

5.2 Docker 容器化部署

构建镜像

创建Dockerfile：

FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 RUN apt-get update && apt-get install -y \ python3.11 \ python3-pip \ && rm -rf /var/lib/apt/lists/* WORKDIR /app COPY app.py . # 复制本地缓存模型（需提前挂载） ENV TRANSFORMERS_OFFLINE=1 ENV HF_HOME=/root/.cache/huggingface COPY --chown=root:root /root/.cache/huggingface /root/.cache/huggingface RUN pip3 install torch==2.9.1+cu128 \ transformers==4.57.3 \ gradio==6.2.0 \ --extra-index-url https://download.pytorch.org/whl/cu128 EXPOSE 7860 CMD ["python3", "app.py"]

构建与运行容器

# 构建镜像 docker build -t deepseek-r1-1.5b:latest . # 运行容器（自动挂载 GPU） docker run -d --gpus all \ -p 7860:7860 \ -v /root/.cache/huggingface:/root/.cache/huggingface \ --name deepseek-web \ deepseek-r1-1.5b:latest

优势：容器化部署便于版本控制、迁移和集群扩展。

6. 参数调优与性能建议

6.1 推荐推理参数

6.2 性能优化建议

• 减少上下文长度：长序列显著增加显存消耗
• 启用半精度：使用torch_dtype=torch.float16减少内存占用
• 批处理请求：若并发高，可考虑使用 vLLM 或 Text Generation Inference 优化吞吐

7. 故障排查指南

7.1 常见问题清单

7.2 端口检测命令

# 查看 7860 端口占用情况 lsof -i:7860 # 或 netstat -tuln | grep 7860

7.3 切换至 CPU 模式

修改app.py中模型加载方式：

model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, device_map="cpu", # 改为 CPU torch_dtype=torch.float32 )

适用场景：无 GPU 设备时临时调试使用，性能大幅下降。

8. 总结

本文系统地介绍了DeepSeek-R1-Distill-Qwen-1.5B模型的全链路部署流程，涵盖环境配置、模型加载、Web 服务构建、后台运行与 Docker 容器化等多个维度。核心要点包括：

1. 环境一致性：严格匹配 CUDA 12.8 与对应版本的 PyTorch 是成功启用 GPU 的前提。
2. 模型缓存管理：合理利用 Hugging Face 缓存机制避免重复下载。
3. Gradio 快速原型：适合快速验证功能与交互设计。
4. Docker 提升可移植性：实现“一次构建，处处运行”的工程目标。
5. 参数调优保障质量：合理的生成参数设置直接影响用户体验。

该模型凭借其在数学与代码任务上的优异表现，非常适合用于教育辅助、编程助手、自动化测试等场景。结合本文提供的部署方案，开发者可在短时间内完成本地化集成。

获取更多AI镜像

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