环境配置

本章将详细介绍如何配置 Hugging Face Transformers 的开发环境，包括 Python 环境、GPU 支持、以及相关依赖库的安装。

系统要求

硬件要求

配置级别	CPU	内存	存储	GPU
基础配置	4核+	8GB+	20GB+	可选
推荐配置	8核+	16GB+	50GB+	NVIDIA GPU 8GB+
高性能配置	16核+	32GB+	100GB+	NVIDIA GPU 24GB+

软件要求

Python: 3.8 或更高版本（推荐 3.10+）
操作系统: Linux (推荐)、macOS、Windows
CUDA: 11.8+（如需 GPU 支持）
cuDNN: 8.6+（配合 CUDA 使用）

Python 环境配置

使用 Conda 创建环境（推荐）

# 创建新环境
conda create -n transformers python=3.10

# 激活环境
conda activate transformers

# 验证 Python 版本
python --version

使用 venv 创建环境

# 创建虚拟环境
python -m venv transformers-env

# 激活环境（Linux/macOS）
source transformers-env/bin/activate

# 激活环境（Windows）
transformers-env\Scripts\activate

安装 Transformers

基础安装

# 仅安装 transformers
pip install transformers

完整安装（推荐）

# 安装 PyTorch（根据 CUDA 版本选择）
# CPU 版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# CUDA 11.8 版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1 版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装 Transformers 及核心依赖
pip install transformers datasets evaluate accelerate

# 安装分词器（可选，但推荐）
pip install tokenizers

# 安装模型序列化工具
pip install safetensors

功能扩展安装

# 图像处理支持
pip install pillow

# 音频处理支持
pip install librosa

# 语音处理支持
pip install soundfile

# 多模态支持
pip install transformers[vision]
pip install transformers[audio]

# 推理优化
pip install optimum[onnxruntime]

# 量化支持
pip install bitsandbytes

# 参数高效微调
pip install peft

# RLHF 训练
pip install trl

验证安装

基础验证

import transformers

print(f"Transformers 版本: {transformers.__version__}")

# 测试基本功能
from transformers import pipeline

classifier = pipeline("sentiment-analysis")
result = classifier("I love using Transformers!")
print(result)

GPU 验证

import torch

# 检查 PyTorch 是否能检测到 GPU
print(f"PyTorch 版本: {torch.__version__}")
print(f"CUDA 可用: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    print(f"CUDA 版本: {torch.version.cuda}")
    print(f"GPU 数量: {torch.cuda.device_count()}")
    print(f"当前 GPU: {torch.cuda.get_device_name(0)}")
    
    # 测试 GPU 计算
    x = torch.rand(1000, 1000).cuda()
    y = torch.rand(1000, 1000).cuda()
    z = torch.matmul(x, y)
    print(f"GPU 计算测试成功！结果形状: {z.shape}")

完整环境检查脚本

#!/usr/bin/env python3
"""环境检查脚本"""

def check_environment():
    print("=" * 50)
    print("Hugging Face Transformers 环境检查")
    print("=" * 50)
    
    # 检查 Python 版本
    import sys
    print(f"\nPython 版本: {sys.version}")
    
    # 检查核心库
    libraries = [
        ("transformers", "Transformers"),
        ("torch", "PyTorch"),
        ("datasets", "Datasets"),
        ("accelerate", "Accelerate"),
        ("tokenizers", "Tokenizers"),
    ]
    
    print("\n核心库版本:")
    for module, name in libraries:
        try:
            mod = __import__(module)
            version = getattr(mod, "__version__", "unknown")
            print(f"  ✓ {name}: {version}")
        except ImportError:
            print(f"  ✗ {name}: 未安装")
    
    # 检查 GPU
    print("\nGPU 支持:")
    try:
        import torch
        if torch.cuda.is_available():
            print(f"  ✓ CUDA 可用")
            print(f"  ✓ CUDA 版本: {torch.version.cuda}")
            print(f"  ✓ GPU: {torch.cuda.get_device_name(0)}")
            print(f"  ✓ GPU 显存: {torch.cuda.get_device_properties(0).total_memory / 1e9:.2f} GB")
        else:
            print(f"  ✗ CUDA 不可用，将使用 CPU")
    except Exception as e:
        print(f"  ✗ GPU 检查失败: {e}")
    
    # 检查可选库
    print("\n可选库:")
    optional_libs = [
        ("PIL", "Pillow"),
        ("librosa", "Librosa"),
        ("soundfile", "SoundFile"),
        ("bitsandbytes", "BitsAndBytes"),
        ("peft", "PEFT"),
        ("trl", "TRL"),
    ]
    
    for module, name in optional_libs:
        try:
            __import__(module)
            print(f"  ✓ {name}: 已安装")
        except ImportError:
            print(f"  ✗ {name}: 未安装")
    
    print("\n" + "=" * 50)

if __name__ == "__main__":
    check_environment()

Hugging Face Hub 配置

注册账号

访问 Hugging Face 创建账号
在 Settings → Access Tokens 中创建 API Token

命令行登录

# 安装 Hugging Face CLI
pip install huggingface-hub

# 登录
huggingface-cli login

# 输入你的 access token
# Token 可以在这里获取: https://huggingface.co/settings/tokens

代码中登录

from huggingface_hub import login

# 交互式登录
login()

# 或使用 token 直接登录
login(token="your-access-token")

环境变量配置

# Linux/macOS
export HF_TOKEN="your-access-token"

# Windows PowerShell
$env:HF_TOKEN="your-access-token"

# Windows CMD
set HF_TOKEN=your-access-token

国内镜像配置

由于网络原因，国内用户可能需要配置镜像源：

Hugging Face 镜像

# 使用 HF-Mirror 镜像
export HF_ENDPOINT=https://hf-mirror.com

# Windows PowerShell
$env:HF_ENDPOINT="https://hf-mirror.com"

Python 包镜像

# 临时使用清华镜像
pip install transformers -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久配置
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

模型下载镜像

from transformers import AutoModel, AutoTokenizer
import os

# 设置镜像地址
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

# 下载模型
model = AutoModel.from_pretrained("bert-base-chinese")
tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")

Docker 部署

使用官方镜像

# 拉取镜像
docker pull huggingface/transformers-pytorch-gpu:latest

# 运行容器
docker run --gpus all -it \
  -v $(pwd):/workspace \
  huggingface/transformers-pytorch-gpu:latest \
  bash

Dockerfile 示例

FROM huggingface/transformers-pytorch-gpu:4.35.0

# 设置工作目录
WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 设置环境变量
ENV PYTHONUNBUFFERED=1
ENV HF_HOME=/app/.cache/huggingface

CMD ["python", "main.py"]

常见问题

1. CUDA 版本不匹配

# 错误信息: CUDA driver version is insufficient for CUDA runtime version

# 解决方案：安装与驱动匹配的 PyTorch 版本
# 查看 CUDA 驱动版本
nvidia-smi

# 根据驱动版本选择 PyTorch
# 驱动版本 >= 525.60.13: 使用 CUDA 12.1
# 驱动版本 >= 450.80.02: 使用 CUDA 11.8

2. 内存不足

# 使用更小的模型进行测试
from transformers import AutoModel

# 使用 DistilBERT 替代 BERT
model = AutoModel.from_pretrained("distilbert-base-uncased")

# 或使用量化版本
model = AutoModel.from_pretrained("bert-base-uncased", load_in_8bit=True)

3. 模型下载失败

# 设置超时和重试
from transformers import AutoModel
import os

os.environ['HF_HUB_DOWNLOAD_TIMEOUT'] = '300'
os.environ['HF_HUB_ETAG_TIMEOUT'] = '300'

# 使用本地缓存
model = AutoModel.from_pretrained(
    "bert-base-uncased",
    cache_dir="./model_cache",
    local_files_only=False
)

4. Windows 安装问题

# 安装 Visual C++ Build Tools
# 下载地址: https://visualstudio.microsoft.com/visual-cpp-build-tools/

# 使用 conda 安装（避免编译问题）
conda install -c huggingface transformers
conda install -c pytorch pytorch

下一步

环境配置完成后，你可以开始学习：

Pipeline 快速入门 - 最简单的模型使用方式
模型加载与使用 - 理解模型架构和加载机制

系统要求​

硬件要求​

软件要求​

Python 环境配置​

使用 Conda 创建环境（推荐）​

使用 venv 创建环境​

安装 Transformers​

基础安装​

完整安装（推荐）​

功能扩展安装​

验证安装​

基础验证​

GPU 验证​

完整环境检查脚本​

Hugging Face Hub 配置​

注册账号​

命令行登录​

代码中登录​

环境变量配置​

国内镜像配置​

Hugging Face 镜像​

Python 包镜像​

模型下载镜像​

Docker 部署​

使用官方镜像​

Dockerfile 示例​

常见问题​

1. CUDA 版本不匹配​

2. 内存不足​

3. 模型下载失败​

4. Windows 安装问题​

下一步​

系统要求

硬件要求

软件要求

Python 环境配置

使用 Conda 创建环境（推荐）

使用 venv 创建环境

安装 Transformers

基础安装

完整安装（推荐）

功能扩展安装

验证安装

基础验证

GPU 验证

完整环境检查脚本

Hugging Face Hub 配置

注册账号

命令行登录

代码中登录

环境变量配置

国内镜像配置

Hugging Face 镜像

Python 包镜像

模型下载镜像

Docker 部署

使用官方镜像

Dockerfile 示例

常见问题

1. CUDA 版本不匹配

2. 内存不足

3. 模型下载失败

4. Windows 安装问题

下一步