保姆级教程：从0开始用DeepSeek-R1-Qwen-1.5B做项目-平芜编程栈

保姆级教程：从0开始用DeepSeek-R1-Qwen-1.5B做项目

1. 学习目标与前置知识

本文是一篇从零开始的实战教程，旨在帮助开发者快速部署并基于DeepSeek-R1-Distill-Qwen-1.5B模型构建可交互的文本生成 Web 应用。通过本教程，你将掌握：

如何配置支持 CUDA 的 Python 环境
下载、加载和推理调用 DeepSeek 蒸馏模型
使用 Gradio 构建可视化 Web 接口
将服务打包为后台进程或 Docker 容器
常见问题排查与性能优化建议

前置知识要求

熟悉 Linux 命令行操作
具备基础 Python 编程能力
了解 Hugging Face Transformers 框架基本用法
拥有支持 CUDA 12.8 的 GPU 设备（推荐至少 8GB 显存）

2. 环境准备与依赖安装

2.1 系统环境检查

首先确认你的系统满足以下条件：

# 检查 CUDA 版本 nvidia-smi # 查看 Python 版本（需 3.11+） python3 --version # 检查 pip 是否可用 pip --version

注意：该模型对显存有一定要求，1.5B 参数量在 FP16 模式下约占用 4~6GB 显存。若显存不足，可考虑降低max_new_tokens或启用 CPU 推理模式。

2.2 安装核心依赖包

执行以下命令安装必要的 Python 库：

pip install torch==2.9.1 \ transformers==4.57.3 \ gradio==6.2.0 \ sentencepiece

说明： -torch: PyTorch 深度学习框架，支持 GPU 加速 -transformers: Hugging Face 提供的模型接口库 -gradio: 快速构建 Web UI 的工具 -sentencepiece: Qwen 模型所需的分词器后端

确保所有包版本符合镜像文档要求，避免因版本不兼容导致加载失败。

3. 模型获取与本地加载

3.1 模型来源说明

DeepSeek-R1-Distill-Qwen-1.5B是通过强化学习蒸馏技术从更大规模的 DeepSeek-R1 模型中提取知识而得到的小型化推理模型。其特点包括：

参数量：1.5B
架构基础：Qwen-2.5 架构
优势能力：数学推理、代码生成、逻辑链推导
适用场景：轻量化部署、边缘设备推理、多轮对话系统

该模型已缓存在/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B路径下（注意文件名中的___表示.）。

3.2 手动下载模型（可选）

如果你需要手动下载模型，请使用 Hugging Face CLI：

huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --local-dir ./model/deepseek-r1-1.5b

提示：首次下载可能较慢，建议使用代理加速或选择国内镜像源。

3.3 加载模型代码实现

创建load_model.py文件进行测试性加载：

from transformers import AutoTokenizer, AutoModelForCausalLM import torch # 模型路径（根据实际情况调整） model_path = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" # 加载分词器和模型 tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.float16, device_map="auto", trust_remote_code=True, local_files_only=True # 仅使用本地文件 ) print("✅ 模型加载成功！") print(f"设备: {next(model.parameters()).device}")

运行此脚本应输出类似信息，表示模型成功加载至 GPU。

4. 构建 Web 服务接口

4.1 创建主应用文件 app.py

我们使用 Gradio 构建一个简洁的 Web 界面，支持用户输入并返回模型生成结果。

# app.py import gradio as gr from transformers import AutoTokenizer, AutoModelForCausalLM import torch # --- 配置区 --- MODEL_PATH = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" DEVICE = "cuda" if torch.cuda.is_available() else "cpu" MAX_NEW_TOKENS = 2048 TEMPERATURE = 0.6 TOP_P = 0.95 # --- 模型加载 --- tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtype=torch.float16, device_map="auto", trust_remote_code=True, local_files_only=True ) # --- 推理函数 --- def generate_response(prompt): if not prompt.strip(): return "请输入有效内容。" inputs = tokenizer(prompt, return_tensors="pt").to(DEVICE) with torch.no_grad(): outputs = model.generate( **inputs, max_new_tokens=MAX_NEW_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) # 去除原始 prompt（保留生成部分） generated_text = response[len(prompt):].strip() return generated_text # --- Gradio 界面 --- with gr.Blocks(title="DeepSeek-R1-1.5B 文本生成") as demo: gr.Markdown("# 🧠 DeepSeek-R1-Distill-Qwen-1.5B 文本生成服务") gr.Markdown("支持数学推理、代码生成与复杂逻辑任务") with gr.Row(): with gr.Column(scale=2): input_text = gr.Textbox( label="输入提示 (Prompt)", placeholder="例如：请写一个快速排序的 Python 实现，并解释其时间复杂度。", lines=6 ) with gr.Row(): clear_btn = gr.Button("清空") submit_btn = gr.Button("生成", variant="primary") with gr.Column(scale=3): output_text = gr.Textbox(label="模型输出", lines=12, interactive=False) # 绑定事件 submit_btn.click(fn=generate_response, inputs=input_text, outputs=output_text) clear_btn.click(fn=lambda: ("", ""), inputs=None, outputs=[input_text, output_text]) gr.Examples( label="示例输入", examples=[ "求解方程 x^2 + 5x + 6 = 0", "用 Python 写一个斐波那契数列生成器", "解释什么是梯度下降算法？", "帮我设计一个 RESTful API 来管理用户订单" ], inputs=input_text ) # 启动服务 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

4.2 运行 Web 服务

启动服务：

python3 app.py

成功运行后，终端会显示：

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

此时可通过浏览器访问http://<服务器IP>:7860查看交互界面。

5. 后台运行与日志管理

为了长期运行服务，建议将其置于后台并记录日志。

5.1 启动后台服务

nohup python3 app.py > /tmp/deepseek_web.log 2>&1 &

5.2 查看运行日志

tail -f /tmp/deepseek_web.log

5.3 停止服务

查找并终止进程：

ps aux | grep "python3 app.py" | grep -v grep | awk '{print $2}' | xargs kill

6. Docker 化部署方案

6.1 编写 Dockerfile

FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 RUN apt-get update && apt-get install -y \ python3.11 \ python3-pip \ python3-distutils \ && rm -rf /var/lib/apt/lists/* WORKDIR /app COPY app.py . # 复制本地缓存的模型（需提前挂载） COPY --from=cache /root/.cache/huggingface /root/.cache/huggingface RUN pip3 install torch==2.9.1 \ transformers==4.57.3 \ gradio==6.2.0 \ sentencepiece EXPOSE 7860 CMD ["python3", "app.py"]

6.2 构建与运行容器

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

说明：确保宿主机已预下载模型并正确映射路径。

7. 故障排查与优化建议

7.1 常见问题及解决方案

问题现象	可能原因	解决方法
启动时报错`CUDA out of memory`	显存不足	降低`max_new_tokens`或改用 CPU 模式
模型无法加载	路径错误或缺失`trust_remote_code=True`	检查路径拼写，确认启用远程代码信任
端口被占用	7860 已被其他服务占用	使用`lsof -i:7860`查看并杀掉进程
分词器报错	缺少`sentencepiece`	安装`sentencepiece`包

7.2 性能优化建议

温度调节：对于确定性任务（如数学计算），建议设置temperature=0.5~0.6；创意类任务可提高至0.7
Top-P 采样：保持top_p=0.95可平衡多样性与稳定性
减少上下文长度：非必要情况下限制max_new_tokens以节省显存
启用半精度：始终使用torch.float16减少内存占用

8. 总结

本文详细介绍了如何从零开始部署并使用DeepSeek-R1-Distill-Qwen-1.5B模型构建一个功能完整的文本生成 Web 服务。主要内容包括：

环境搭建：配置 Python 与 CUDA 支持
模型加载：通过本地路径安全加载模型
Web 接口开发：使用 Gradio 快速构建交互界面
服务持久化：后台运行与日志监控
容器化部署：Docker 方案提升可移植性
问题排查：常见错误应对策略与性能调优

该模型凭借其在数学、代码和逻辑推理方面的出色表现，非常适合用于教育辅助、编程助手、智能客服等轻量级 AI 应用场景。

下一步你可以尝试： - 集成 LangChain 构建 Agent 系统 - 添加多轮对话记忆机制 - 对特定领域数据进行微调以增强专业能力

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

保姆级教程：从0开始用DeepSeek-R1-Qwen-1.5B做项目