使用 PyTorch 和 Hugging Face 入门深度学习

此仓库包含使用 PyTorch 以及 Hugging Face 的 transformers、datasets 等库入门深度学习的说明、示例和教程。

训练示例

• 使用 DeepSpeed 和 Hugging Face Transformers 微调 FLAN-T5 XL/XXL
• 微调 FLAN-T5 用于聊天与对话摘要
• 使用 DeepSpeed ZeRO、LoRA 和 Flash Attention 微调 Falcon 180B
• 使用 PyTorch 和 TPU 入门 Transformers
• 扩展指南：指令微调 Llama 2
• 使用 optimum 和 GPTQ 对开源大模型进行量化
• 为 RAG 微调嵌入模型
• 2024 年使用 TRL 微调大模型
• 2025 年微调大模型
• 使用 TRL 微调多模态大模型
• 2024 年使用 DPO 和 Hugging Face 进行 RLHF
• 使用 ChatML 微调 Gemma
• 利用 FSDP 和 Q-LoRA 高效扩展分布式训练
• 2025 年微调 ModernBERT 分类器
• 如何在 2025 年使用 DPO 和 Hugging Face 对齐开源大模型

推理示例

• 文本生成推理示例
• FP8 推理基准测试
• Idefics 推理
• Llama 2 推理
• 推测解码
• StarCoder GPTQ 推理

deep-learning-pytorch-huggingface 快速上手指南

本仓库提供了基于 PyTorch 和 Hugging Face 生态系统（如 transformers、datasets）进行深度学习开发的指令、示例和教程。涵盖从模型微调（Fine-tuning）、量化到推理的全流程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 macOS。Windows 用户建议使用 WSL2。
• Python 版本: Python 3.9 或更高版本。
• 硬件加速:
  • GPU: 推荐使用 NVIDIA GPU (需安装对应的 CUDA 驱动)。部分示例支持 TPU。
  • 内存: 微调大模型（如 Llama 2, Falcon）建议至少 24GB VRAM，或使用 LoRA/QLoRA 技术在较低显存下运行。
• 前置依赖:
  • Git (用于克隆仓库)
  • pip 或 conda (包管理工具)

提示：国内开发者若遇到网络连接问题，建议在安装步骤中配置清华或阿里镜像源。

安装步骤

1. 克隆仓库

首先将项目代码克隆到本地：

git clone https://github.com/philschmid/deep-learning-pytorch-huggingface.git
cd deep-learning-pytorch-huggingface

2. 创建虚拟环境

推荐使用 conda 或 venv 隔离环境：

# 使用 conda
conda create -n dl-hf python=3.10
conda activate dl-hf

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

3. 安装核心依赖

根据您的需求安装基础库。为了加速下载，国内用户可使用 -i 指定镜像源。

基础安装 (PyTorch + Transformers + Datasets):

# 使用清华镜像源安装 PyTorch (CUDA 11.8 示例，请根据实际显卡调整)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 安装 Hugging Face 核心库及常用训练工具
pip install transformers datasets accelerate evaluate -i https://pypi.tuna.tsinghua.edu.cn/simple

进阶安装 (针对特定示例): 如果您需要运行 DeepSpeed、LoRA 或量化示例，需额外安装以下库：

# 安装 DeepSpeed, PEFT (LoRA), TRL (强化学习), Optimum (量化) 等
pip install deepspeed peft trl optimum auto-gptq bitsandbytes flash-attn -i https://pypi.tuna.tsinghua.edu.cn/simple

注意: flash-attn 可能需要特定的编译环境，若安装失败可暂时跳过，部分示例会自动降级处理。

基本使用

本仓库的核心内容是位于 training/ 和 inference/ 目录下的 Jupyter Notebook (.ipynb) 文件。以下是快速启动一个微调任务的标准流程。

1. 启动 Jupyter Lab

进入项目根目录并启动交互式开发环境：

jupyter lab

2. 选择并运行示例

在浏览器打开的界面中，导航至 training 文件夹，选择一个适合您需求的笔记本。

示例：微调 FLAN-T5 进行摘要生成

1. 打开 ./training/flan-t5-samsum-summarization.ipynb。
2. 按顺序执行单元格。代码逻辑通常如下：

from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
from datasets import load_dataset

# 1. 加载模型和分词器
model_name = "google/flan-t5-base"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSeq2SeqLM.from_pretrained(model_name)

# 2. 加载数据集 (例如 SAMSum 对话摘要数据集)
dataset = load_dataset("samsum")

# 3. 数据预处理函数
def preprocess_function(examples):
    inputs = [doc for doc in examples["dialogue"]]
    model_inputs = tokenizer(inputs, max_length=512, truncation=True)
    
    labels = [doc for doc in examples["summary"]]
    with tokenizer.as_target_tokenizer():
        labels = tokenizer(labels, max_length=128, truncation=True)
    
    model_inputs["labels"] = labels["input_ids"]
    return model_inputs

tokenized_datasets = dataset.map(preprocess_function, batched=True)

# 4. 后续步骤请参考 Notebook 中的 TrainingArguments 定义及 trainer.train()

3. 运行推理示例

对于推理任务，可查看 inference 目录下的 Markdown 文档或对应的脚本。例如运行 Llama 2 推理：

# 参考 ./inference/llama-7b.md 中的指引
python inference/run_llama_inference.py --model_id "meta-llama/Llama-2-7b-chat-hf" --prompt "你好，请介绍一下你自己。"

提示：首次运行会自动从 Hugging Face Hub 下载模型权重。国内网络若下载缓慢，可配置 HF_ENDPOINT 环境变量使用镜像站：

export HF_ENDPOINT=https://hf-mirror.com