DeepSeek-R1-Distill-Qwen-1.5B实战教程：Gradio界面集成详细步骤

DeepSeek-R1-Distill-Qwen-1.5B实战教程：Gradio界面集成详细步骤

你是否想快速搭建一个支持数学推理、代码生成和逻辑分析的轻量级AI对话系统？本文将带你从零开始，手把手部署DeepSeek-R1-Distill-Qwen-1.5B模型，并通过 Gradio 构建直观易用的 Web 交互界面。整个过程无需复杂配置，适合开发者、教育者或技术爱好者快速上手。

我们将覆盖环境准备、依赖安装、模型加载、Gradio 界面开发、服务启动与优化建议等关键环节，确保你能稳定运行并灵活调用该模型。无论你是想做本地实验、教学演示还是二次开发，这篇教程都能为你提供完整的技术路径。

1. 项目背景与核心能力

1.1 模型简介

DeepSeek-R1-Distill-Qwen-1.5B是基于 Qwen-1.5B 的蒸馏优化版本，利用 DeepSeek-R1 在强化学习中生成的高质量推理数据进行知识迁移训练而成。相比原始小模型，它在保持低资源消耗的同时显著提升了以下能力：

• 数学推理：能处理代数运算、方程求解、应用题解析等任务
• 代码生成：支持 Python、JavaScript 等主流语言的基础函数编写
• 逻辑推理：具备链式思考（Chain-of-Thought）能力，可完成多步推导

参数量仅为1.5B，可在消费级 GPU（如 RTX 3060/3090）上流畅运行，非常适合边缘部署和本地化服务。

1.2 技术优势

本项目目标是将其封装为可通过浏览器访问的 Web 服务，便于非技术人员使用其强大功能。

2. 环境准备与依赖安装

2.1 系统要求

为了保证模型顺利加载和推理，请确保你的设备满足以下最低配置：

• 操作系统：Linux（推荐 Ubuntu 20.04+）
• Python 版本：3.11 或以上
• CUDA 版本：12.8（支持 Tensor Core 加速）
• GPU 显存：至少 8GB（建议使用 NVIDIA A10/A100 或 RTX 30/40 系列）

注意：若无 GPU，也可降级至 CPU 模式运行，但推理速度会明显变慢。

2.2 安装必要依赖

打开终端，执行以下命令安装核心库：

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

这些库的作用如下：

• torch：PyTorch 深度学习框架，用于模型加载与推理
• transformers：Hugging Face 提供的模型接口库，简化调用流程
• gradio：快速构建 Web UI 的工具，无需前端知识即可实现交互界面

安装完成后，可通过以下代码验证环境是否正常：

import torch print(torch.__version__) print(torch.cuda.is_available()) # 应输出 True

如果返回True，说明 CUDA 环境已就绪。

3. 模型下载与本地缓存管理

3.1 下载模型文件

该模型托管于 Hugging Face Hub，你可以使用官方 CLI 工具下载：

huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --local-dir /root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B

注意路径中的1___5B是因文件系统限制对1.5B的转义写法，请勿手动修改目录名。

首次下载可能较慢（约 3~5 GB），建议使用国内镜像加速或挂载代理。

3.2 验证模型加载

创建测试脚本test_load.py，内容如下：

from transformers import AutoTokenizer, AutoModelForCausalLM model_path = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" tokenizer = AutoTokenizer.from_pretrained(model_path, local_files_only=True) model = AutoModelForCausalLM.from_pretrained( model_path, device_map="auto", torch_dtype=torch.float16 ) print(" 模型加载成功！")

运行后若无报错，则表示模型已正确部署到本地。

4. Gradio 界面开发与集成

4.1 创建主程序文件

新建app.py文件，作为 Web 服务入口。以下是完整实现代码：

import torch from transformers import AutoTokenizer, AutoModelForCausalLM import gradio as gr # 模型路径（请根据实际位置调整） MODEL_PATH = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" # 加载 tokenizer 和 model tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH, local_files_only=True) model = AutoModelForCausalLM.from_pretrained( MODEL_PATH, device_map="auto", torch_dtype=torch.float16 ) def generate_response(prompt, max_tokens=2048, temperature=0.6, top_p=0.95): """ 生成回复函数 :param prompt: 输入文本 :param max_tokens: 最大输出长度 :param temperature: 温度系数，控制随机性 :param top_p: 核采样阈值 :return: 模型输出文本 """ inputs = tokenizer(prompt, return_tensors="pt").to(model.device) with torch.no_grad(): 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):].strip() # 构建 Gradio 界面 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(scale=2): input_text = gr.Textbox(label="输入提示", placeholder="请输入你的问题...", lines=5) with gr.Row(): submit_btn = gr.Button("发送", variant="primary") clear_btn = gr.Button("清空") with gr.Column(scale=3): output_text = gr.Textbox(label="AI 回复", lines=5, interactive=False) # 参数调节区 with gr.Accordion("高级参数设置", open=False): max_tokens = gr.Slider(minimum=256, maximum=2048, value=2048, step=128, label="最大输出长度") temp = gr.Slider(minimum=0.1, maximum=1.2, value=0.6, step=0.1, label="温度 (Temperature)") top_p_val = gr.Slider(minimum=0.7, maximum=1.0, value=0.95, step=0.05, label="Top-P") # 绑定事件 submit_btn.click( fn=generate_response, inputs=[input_text, max_tokens, temp, top_p_val], outputs=output_text ) clear_btn.click(fn=lambda: ("", ""), inputs=None, outputs=[input_text, output_text]) # 启动服务 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)

4.2 关键代码解析

• device_map="auto"：自动分配模型层到可用设备（GPU/CPU）
• torch.float16：半精度加载，减少显存占用
• max_new_tokens：控制生成长度，避免过长阻塞
• do_sample=True：启用采样模式，提升输出多样性
• Gradio Blocks 布局：采用响应式列布局，适配不同屏幕尺寸

5. 服务启动与后台运行

5.1 直接启动服务

保存app.py后，在终端执行：

python3 app.py

启动成功后，终端会显示类似信息：

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

此时可在浏览器中访问http://<服务器IP>:7860查看界面。

5.2 后台常驻运行

为防止 SSH 断开导致服务中断，推荐使用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

6. Docker 化部署方案

6.1 编写 Dockerfile

创建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 . # 复制本地缓存模型（需提前挂载） COPY --from=cache /root/.cache/huggingface /root/.cache/huggingface RUN pip3 install torch==2.9.1 transformers==4.57.3 gradio==6.2.0 --extra-index-url https://download.pytorch.org/whl/cu128 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 故障排查清单

7.2 推荐参数设置

根据实测经验，以下参数组合在多数场景下表现最佳：

• 温度（Temperature）：0.6 —— 平衡创造性和稳定性
• 最大 Token 数：2048 —— 兼顾上下文长度与性能
• Top-P：0.95 —— 保留高质量候选词

对于需要严谨输出的任务（如数学证明），可将温度降至 0.3~0.5。

8. 总结

通过本文的详细指导，你应该已经成功部署了DeepSeek-R1-Distill-Qwen-1.5B模型，并构建了一个功能完整的 Gradio Web 交互界面。我们涵盖了从环境配置、模型加载、界面开发到 Docker 容器化的全流程，帮助你在本地或服务器上实现高效可用的 AI 服务。

这个轻量级模型特别适合以下应用场景：

• 教学辅助：自动解答学生提出的编程或数学问题
• 内部工具：为企业员工提供智能问答支持
• 创业原型：快速验证 AI 产品创意

下一步你可以尝试：

• 添加历史对话记忆功能
• 集成 RAG（检索增强生成）提升准确性
• 封装为 API 供其他系统调用

只要掌握了基础部署流程，后续扩展将变得非常简单。

获取更多AI镜像

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