六盘水市网站建设_网站建设公司_字体设计_seo优化

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 核心技术栈

这些不是随便选的版本，而是经过测试能稳定运行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 pipreqs

4.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，开发依赖另建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 日志排查常见问题

记住：最好的 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 给开发者的实用建议

1. 每次更新代码后重新检查依赖，尤其是新增功能模块时
2. 不要盲目pip freeze，保持requirements.txt精简
3. 给团队成员提供标准环境说明文档，减少“在我电脑上能跑”的问题
4. 定期升级依赖并测试，避免长期停留在旧版本带来安全隐患

获取更多AI镜像

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