DeepSeek-R1-Distill-Qwen-1.5B依赖管理：requirements.txt生成教程
1. 教程目标与适用人群
你是不是也遇到过这种情况：项目跑得好好的，换台机器一部署，各种包版本冲突、依赖缺失，直接报错？尤其是像DeepSeek-R1-Distill-Qwen-1.5B这种对环境要求严格的AI模型服务，Python版本、CUDA驱动、PyTorch版本差一点都可能让你卡在启动前。
本教程专为正在做DeepSeek-R1-Distill-Qwen-1.5B 模型二次开发的开发者设计。我们将手把手教你如何从零开始，自动生成一个精准、可复用的requirements.txt文件，确保你的项目在任何支持GPU的环境中都能一键安装、顺利运行。
无论你是刚接手这个项目的新人，还是想把本地环境迁移到服务器或Docker容器的老手，这篇教程都能帮你搞定依赖管理这件“小事”。
2. 理解项目依赖结构
在生成requirements.txt之前，我们得先搞清楚这个项目到底用了哪些关键组件。根据部署说明文档，我们可以梳理出以下核心依赖关系：
2.1 核心技术栈
| 组件 | 版本要求 | 作用 |
|---|---|---|
| Python | 3.11+ | 基础运行环境 |
| CUDA | 12.8 | GPU加速支持 |
| PyTorch | >=2.9.1 | 深度学习框架，负责模型加载和推理 |
| Transformers | >=4.57.3 | Hugging Face模型接口，封装了Qwen模型的调用逻辑 |
| Gradio | >=6.2.0 | 快速构建Web交互界面 |
这些不是随便选的版本，而是经过测试能稳定运行1.5B参数量大模型的组合。特别是torch和transformers，它们之间有很强的兼容性要求——版本不匹配轻则警告，重则直接崩溃。
2.2 为什么不能直接 pip freeze？
你可能会问：“我直接pip freeze > requirements.txt不就行了吗？”
理论上可以，但实际问题很多：
- 会包含大量无关依赖（比如你装过的Jupyter、Flask等）
- 可能带入开发环境特有的包
- 版本过于具体（如带commit hash），不利于跨平台迁移
- 缺少对CUDA、Python版本的声明
所以我们需要的是一个精简、明确、可移植性强的依赖清单。
3. 手动创建 requirements.txt 的最佳实践
虽然有自动化工具，但在AI项目中，手动控制依赖列表更安全、更清晰。下面我们一步步来写一份高质量的requirements.txt。
3.1 创建基础文件
首先，在项目根目录下新建一个文件：
touch requirements.txt然后打开编辑器，开始填写内容。
3.2 添加核心依赖（推荐写法）
# DeepSeek-R1-Distill-Qwen-1.5B 推理服务依赖 # 支持数学推理、代码生成、逻辑推理任务 # 运行设备：NVIDIA GPU (CUDA 12.8) python>=3.11,<3.12 torch>=2.9.1 transformers>=4.57.3 gradio>=6.2.0注意几点：
- 我们没有写死具体小版本号（如
2.9.1），而是用>=允许合理升级 - 对Python做了范围限制（
<3.12）避免未来版本不兼容 - 注释说明用途和硬件要求，方便团队协作
3.3 如何处理隐式依赖？
有些包是间接引入的，比如tokenizers、accelerate，要不要加进去？
答案是：只加直接影响模型行为的核心包
如果你在代码里显式导入了某个模块（例如用了from accelerate import infer_auto_device_map），那就加上；否则让transformers自己管理它的依赖更稳妥。
4. 使用 pipreqs 自动生成精准依赖
如果你想省事，又怕漏掉包，推荐使用pipreqs工具——它能扫描你的代码文件，只提取实际 import 的库。
4.1 安装 pipreqs
pip install pipreqs4.2 扫描项目生成 requirements.txt
假设你的项目结构如下：
/root/DeepSeek-R1-Distill-Qwen-1.5B/ ├── app.py └── utils.py执行命令：
cd /root/DeepSeek-R1-Distill-Qwen-1.5B pipreqs . --force --ignore=tests,__pycache__参数说明：
.表示当前目录--force覆盖已存在的requirements.txt--ignore忽略不需要分析的目录
运行后你会看到类似输出：
Successfully saved requirements file in ./requirements.txt查看生成的内容：
torch==2.9.1 transformers==4.57.3 gradio==6.2.0非常干净！完全基于你在app.py中写的import torch等语句推断出来的。
5. 结合部署需求优化依赖文件
生成完之后，别急着提交。我们要根据实际部署场景进一步优化。
5.1 区分生产与开发依赖
AI项目通常分为两类依赖：
| 类型 | 示例 | 是否写入 requirements.txt |
|---|---|---|
| 生产依赖 | torch, transformers, gradio | 必须 |
| 开发依赖 | jupyter, pytest, flake8 | ❌ 单独管理 |
建议做法：只把生产依赖写进requirements.txt，开发依赖另建requirements-dev.txt。
5.2 添加平台约束（可选高级技巧）
为了防止有人在CPU环境强行运行导致OOM，可以在注释中加入提示：
# 注意：本模型需在 NVIDIA GPU + CUDA 12.8 环境下运行 # 若在CPU上运行，请将 DEVICE 设置为 "cpu" 并降低 max_tokens或者更进一步，使用environment.yml配合 Conda 做完整环境锁定（适合企业级部署）。
6. 验证 requirements.txt 的有效性
写好了不代表就完事了，必须验证它能不能真正还原环境。
6.1 新建虚拟环境测试
python -m venv test_env source test_env/bin/activate pip install -r requirements.txt如果安装成功，说明依赖定义没问题。
6.2 尝试启动服务
进入项目目录，运行：
python3 app.py观察是否能正常加载模型、启动Gradio服务。如果有报错，回到requirements.txt补全缺失的包。
6.3 日志排查常见问题
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| ModuleNotFoundError | 缺少依赖 | 用pipreqs重新扫描 |
| VersionConflict | 版本冲突 | 调整>=为具体版本 |
| CUDA not available | torch未带CUDA | 检查是否安装torch的GPU版 |
记住：最好的 requirements.txt 是能在三台不同机器上都跑通的那个版本。
7. Docker中的依赖管理策略
既然项目支持Docker部署，那我们就来看看怎么把requirements.txt用到Dockerfile中。
7.1 修改后的Dockerfile示例
FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04 # 安装Python RUN apt-get update && apt-get install -y \ python3.11 \ python3-pip \ && rm -rf /var/lib/apt/lists/* # 设置工作目录 WORKDIR /app # 先复制依赖文件（利用Docker缓存机制） COPY requirements.txt . RUN pip3 install --no-cache-dir -r requirements.txt # 再复制应用代码 COPY app.py . # 挂载模型缓存（外部传入） COPY -r /root/.cache/huggingface /root/.cache/huggingface EXPOSE 7860 CMD ["python3", "app.py"]关键点：
- 把
COPY requirements.txt放在前面，这样改代码不会触发重装依赖 - 使用
--no-cache-dir减小镜像体积 - 依赖分离，便于CI/CD流程管理
7.2 构建时传递CUDA版本（进阶）
你还可以通过构建参数动态指定CUDA版本：
ARG CUDA_VERSION=12.1.0 FROM nvidia/cuda:${CUDA_VERSION}-runtime-ubuntu22.04构建时：
docker build --build-arg CUDA_VERSION=12.8 -t deepseek-r1-1.5b .这样就能灵活适配不同GPU环境。
8. 总结：打造健壮的依赖管理体系
8.1 关键要点回顾
今天我们完成了从零构建requirements.txt的全过程，核心收获包括：
- 明确了DeepSeek-R1-Distill-Qwen-1.5B的核心技术栈：Python 3.11+、CUDA 12.8、torch>=2.9.1、transformers>=4.57.3、gradio>=6.2.0
- 学会了两种生成方式：手动编写（精确控制）和pipreqs自动扫描（高效无遗漏）
- 掌握了验证方法：在独立环境中测试安装与运行
- 了解了Docker中的最佳实践：分层复制、缓存优化、参数化构建
8.2 给开发者的实用建议
- 每次更新代码后重新检查依赖，尤其是新增功能模块时
- 不要盲目
pip freeze，保持requirements.txt精简 - 给团队成员提供标准环境说明文档，减少“在我电脑上能跑”的问题
- 定期升级依赖并测试，避免长期停留在旧版本带来安全隐患
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
