Python开发者指南：调用DeepSeek-R1模型的三种方式代码实例
1. 引言
1.1 业务场景描述
随着大语言模型在数学推理、代码生成和逻辑推断等复杂任务中的表现日益突出，越来越多的开发者希望将高性能的小参数量模型集成到实际应用中。DeepSeek-R1-Distill-Qwen-1.5B 是基于 DeepSeek-R1 强化学习数据蒸馏技术优化后的 Qwen 1.5B 推理模型，具备出色的推理能力与较低的部署门槛，适合边缘服务、轻量级 Web 应用和本地开发测试。
该模型已在 Hugging Face 平台公开，并支持通过多种方式进行调用。本文面向 Python 开发者，详细介绍三种主流调用方式：本地直接加载、Gradio Web 接口调用、以及 RESTful API 封装调用，并提供完整可运行的代码示例。
1.2 痛点分析
在实际项目中，开发者常面临以下挑战：
- 模型加载耗时长，缺乏缓存管理
- 不同环境（GPU/CPU）切换困难
- 缺乏标准化接口供前端或其他服务调用
- 部署流程复杂，难以快速验证效果
本文提供的三种调用方式覆盖从“本地调试”到“服务化部署”的全链路需求，帮助开发者高效落地模型能力。
1.3 方案预告
本文将依次介绍：
- 使用
transformers库直接加载模型进行推理 - 基于 Gradio 快速构建交互式 Web 界面
- 使用 FastAPI 封装为 RESTful 接口供外部系统调用
每种方式均附带完整代码、参数说明及运行建议。
2. 方式一：本地直接调用（Transformers + Pipeline）
2.1 技术方案选型
使用 Hugging Face 的transformers库是最基础且灵活的模型调用方式。它允许开发者精确控制输入输出、解码策略和设备分配。
对比优势：
| 特性 | 说明 |
|---|---|
| 易用性 | 高，一行代码即可完成推理 |
| 灵活性 | 高，支持自定义 tokenizer 和 generation 参数 |
| 性能 | 优秀，支持 CUDA 加速 |
| 依赖 | torch, transformers |
2.2 实现步骤详解
步骤 1：安装依赖
pip install torch>=2.9.1 transformers>=4.57.3步骤 2：加载模型与分词器
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" print(f"Using device: {DEVICE}") tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32, device_map="auto" if DEVICE == "cuda" else None, trust_remote_code=True, local_files_only=True # 仅使用本地文件 ).to(DEVICE)注意：
trust_remote_code=True是必须的，因为该模型包含自定义实现的模块。
步骤 3：执行推理
def generate_response(prompt: str, max_tokens: int = 2048, temperature: float = 0.6, top_p: float = 0.95): inputs = tokenizer(prompt, return_tensors="pt").to(DEVICE) with torch.no_grad(): outputs = model.generate( inputs["input_ids"], 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):] # 去除输入部分 # 示例调用 prompt = "请解释牛顿第二定律，并写出其数学表达式。" response = generate_response(prompt) print("模型回复：", response)2.3 实践问题与优化
常见问题：
- 显存不足：可降低
max_new_tokens或改用 CPU 模式（设置DEVICE = "cpu"） - 加载失败：检查模型路径是否正确，确认
local_files_only=True - 响应重复：适当提高
temperature至 0.7，或启用repetition_penalty
性能优化建议：
- 使用
torch.compile(model)提升推理速度（PyTorch 2.0+） - 启用
device_map="auto"实现多 GPU 自动负载均衡 - 缓存 tokenizer 和 model 实例避免重复加载
3. 方式二：Gradio 交互式 Web 界面调用
3.1 技术方案选型
Gradio 是一个极简的 Python 库，用于快速构建机器学习模型的可视化界面。适用于演示、内部测试或原型开发。
优势对比：
| 维度 | 表现 |
|---|---|
| 开发效率 | 极高，10行代码即可上线 UI |
| 用户体验 | 支持富文本输入输出 |
| 部署便捷 | 内置服务器，支持公网穿透 |
| 扩展性 | 中等，适合单用户场景 |
3.2 完整代码实现
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" tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32, device_map="auto", trust_remote_code=True, local_files_only=True ).to(DEVICE) # ------------------ 推理函数 ------------------ def chat_interface(user_input, history, temperature=0.6, max_tokens=2048): full_prompt = user_input inputs = tokenizer(full_prompt, return_tensors="pt").to(DEVICE) with torch.no_grad(): outputs = model.generate( inputs["input_ids"], max_new_tokens=max_tokens, temperature=temperature, top_p=0.95, do_sample=True, pad_token_id=tokenizer.eos_token_id ) response = tokenizer.decode(outputs[0], skip_special_tokens=True) bot_response = response[len(full_prompt):].strip() # 更新对话历史 history.append((user_input, bot_response)) return "", history # ------------------ Gradio 界面 ------------------ with gr.Blocks(title="DeepSeek-R1 1.5B 交互界面") as demo: gr.Markdown("# 🤖 DeepSeek-R1-Distill-Qwen-1.5B 本地推理界面") gr.Markdown("支持数学推理、代码生成、逻辑问答等任务") chatbot = gr.Chatbot(height=500) with gr.Row(): msg = gr.Textbox(label="你的消息", placeholder="输入问题...", scale=8) submit = gr.Button("发送", scale=1) with gr.Accordion("生成参数", open=False): temp_slider = gr.Slider(minimum=0.1, maximum=1.0, value=0.6, step=0.05, label="Temperature") max_len = gr.Slider(minimum=256, maximum=4096, value=2048, step=128, label="Max New Tokens") history_state = gr.State([]) submit.click( fn=chat_interface, inputs=[msg, history_state, temp_slider, max_len], outputs=[msg, chatbot] ) msg.submit( fn=chat_interface, inputs=[msg, history_state, temp_slider, max_len], outputs=[msg, chatbot] ) # 启动服务 if __name__ == "__main__": demo.launch(server_name="0.0.0.0", server_port=7860, share=False)3.3 运行说明
保存为app.py后执行：
python app.py访问http://<IP>:7860即可使用图形化界面。
支持特性：
- 回车提交 + 按钮发送双触发
- 可调节温度与最大 token 数
- 自动维护对话历史
4. 方式三：FastAPI 封装为 RESTful 接口
4.1 技术方案选型
当模型需要被多个系统调用时，应封装为标准 HTTP 接口。FastAPI 具有自动文档生成、高性能异步支持等优点，是现代 API 服务的理想选择。
适用场景：
- 被前端页面调用
- 集成进后端微服务架构
- 提供给第三方系统访问
4.2 完整代码实现
from fastapi import FastAPI from pydantic import BaseModel import torch from transformers import AutoTokenizer, AutoModelForCausalLM import uvicorn from typing import Optional # ------------------ 模型初始化 ------------------ app = FastAPI(title="DeepSeek-R1 1.5B Inference API", version="1.0") model_path = "/root/.cache/huggingface/deepseek-ai/DeepSeek-R1-Distill-Qwen-1___5B" DEVICE = "cuda" if torch.cuda.is_available() else "cpu" tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32, device_map="auto", trust_remote_code=True, local_files_only=True ).to(DEVICE) # ------------------ 请求/响应模型 ------------------ class GenerateRequest(BaseModel): prompt: str max_tokens: int = 2048 temperature: float = 0.6 top_p: float = 0.95 class GenerateResponse(BaseModel): success: bool message: str generated_text: Optional[str] = None # ------------------ API 路由 ------------------ @app.post("/v1/generate", response_model=GenerateResponse) async def generate_text(request: GenerateRequest): try: inputs = tokenizer(request.prompt, return_tensors="pt").to(DEVICE) with torch.no_grad(): outputs = model.generate( inputs["input_ids"], max_new_tokens=request.max_tokens, temperature=request.temperature, top_p=request.top_p, do_sample=True, pad_token_id=tokenizer.eos_token_id ) text = tokenizer.decode(outputs[0], skip_special_tokens=True) generated = text[len(request.prompt):].strip() return GenerateResponse( success=True, message="生成成功", generated_text=generated ) except Exception as e: return GenerateResponse( success=False, message=f"生成失败: {str(e)}" ) @app.get("/") def root(): return {"message": "DeepSeek-R1 1.5B API is running", "model": "DeepSeek-R1-Distill-Qwen-1.5B"} # ------------------ 启动命令 ------------------ if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=8000)4.3 接口调用示例
启动服务后，可通过 curl 测试：
curl -X POST http://localhost:8000/v1/generate \ -H "Content-Type: application/json" \ -d '{ "prompt": "写一个Python函数计算斐波那契数列第n项。", "max_tokens": 1024, "temperature": 0.6 }'返回 JSON 结构如下：
{ "success": true, "message": "生成成功", "generated_text": "def fibonacci(n):\n if n <= 1:\n return n\n a, b = 0, 1\n for _ in range(2, n+1):\n a, b = b, a + b\n return b" }特性说明：
- 支持结构化请求体
- 自动生成 OpenAPI 文档（访问
/docs） - 错误统一处理，便于集成
5. 总结
5.1 实践经验总结
本文详细介绍了调用 DeepSeek-R1-Distill-Qwen-1.5B 模型的三种核心方式，各有侧重：
| 方式 | 适用阶段 | 优点 | 注意事项 |
|---|---|---|---|
| Transformers 直接调用 | 开发调试 | 控制精细、性能高 | 需手动管理资源 |
| Gradio Web 界面 | 演示/测试 | 快速上线、交互友好 | 不适合生产环境 |
| FastAPI REST 接口 | 生产集成 | 标准化、易扩展 | 需额外部署网关 |
5.2 最佳实践建议
- 开发初期：优先使用方式一（Transformers）验证模型能力；
- 团队协作评审：采用方式二（Gradio）快速共享成果；
- 上线部署：务必使用方式三（FastAPI）封装为服务，配合 Nginx/Gunicorn 提升稳定性；
- 资源受限环境：考虑量化版本（如 GPTQ 或 GGUF）进一步降低显存占用。
通过合理组合这三种方式，开发者可以高效完成从模型验证到服务上线的全流程工作。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
