环境配置

本章将详细介绍如何配置 Hugging Face Transformers 的开发环境，包括 Python 环境、深度学习框架、CUDA 配置以及 Hugging Face Hub 的登录设置。

系统要求

硬件要求

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

软件要求

• 操作系统：Windows 10/11、macOS 10.15+、Linux (Ubuntu 18.04+)
• Python：3.8 或更高版本（推荐 3.10-3.11）
• 包管理器：pip 或 conda

Python 环境配置

使用 venv（推荐）

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

# 激活环境
# Windows:
transformers-env\Scripts\activate
# macOS/Linux:
source transformers-env/bin/activate

# 升级 pip
pip install --upgrade pip

使用 conda

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

# 激活环境
conda activate transformers

# 升级 conda
conda update conda

安装 Transformers

基础安装

最简单的安装方式，仅包含核心功能：

pip install transformers

完整安装（推荐）

包含所有常用依赖的完整安装：

# 1. 安装 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

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

# 2. 安装 Transformers 及生态工具
pip install transformers datasets evaluate accelerate

# 3. 安装其他可选依赖
# 图像处理
pip install pillow

# 音频处理
pip install librosa

# 模型序列化
pip install protobuf

# 推理优化
pip install optimum[onnxruntime]

使用 conda 安装

# 安装 PyTorch
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

# 安装 Transformers
conda install -c huggingface transformers
conda install -c huggingface datasets
conda install -c conda-forge accelerate

开发版本安装

如果需要使用最新功能或修复：

# 从 GitHub 安装最新开发版本
pip install git+https://github.com/huggingface/transformers.git

# 从 GitHub 安装特定分支
pip install git+https://github.com/huggingface/transformers.git@main

CUDA 和 GPU 配置

检查 CUDA 可用性

import torch

# 检查 CUDA 是否可用
print(f"CUDA 可用: {torch.cuda.is_available()}")

if torch.cuda.is_available():
    # CUDA 版本
    print(f"CUDA 版本: {torch.version.cuda}")
    
    # cuDNN 版本
    print(f"cuDNN 版本: {torch.backends.cudnn.version()}")
    
    # GPU 数量
    print(f"GPU 数量: {torch.cuda.device_count()}")
    
    # GPU 名称
    for i in range(torch.cuda.device_count()):
        print(f"GPU {i}: {torch.cuda.get_device_name(i)}")
        print(f"  显存: {torch.cuda.get_device_properties(i).total_memory / 1e9:.2f} GB")

安装 CUDA Toolkit

如果系统没有 CUDA，需要单独安装：

Windows：

1. 下载 CUDA Toolkit
2. 运行安装程序
3. 添加环境变量

Linux（Ubuntu）：

# 添加 NVIDIA 包仓库
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.0-1_all.deb
sudo dpkg -i cuda-keyring_1.0-1_all.deb
sudo apt-get update

# 安装 CUDA Toolkit
sudo apt-get install cuda-toolkit-12-1

# 添加环境变量到 ~/.bashrc
export PATH=/usr/local/cuda-12.1/bin${PATH:+:${PATH}}
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

显存优化配置

对于显存有限的 GPU，可以配置显存分配策略：

import torch

# 方法1：清空缓存
torch.cuda.empty_cache()

# 方法2：设置显存分配策略
# 按需分配，避免一次性占用所有显存
import os
os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'

# 方法3：使用混合精度训练（节省显存）
from torch.cuda.amp import autocast, GradScaler

# 方法4：启用梯度检查点（以时间换空间）
model.gradient_checkpointing_enable()

Hugging Face Hub 配置

创建账号和 Token

1. 访问 Hugging Face 注册账号
2. 进入 Settings > Access Tokens
3. 创建新的 Access Token（选择 write 权限）

登录方式

方式1：命令行登录（推荐）

# 安装 huggingface_hub
pip install huggingface_hub

# 登录
huggingface-cli login

# 按提示输入 Access Token

方式2：代码中登录

from huggingface_hub import login

# 交互式登录
login()

# 或直接使用 token 登录
login(token="your_access_token_here")

方式3：环境变量登录

# Linux/macOS
export HF_TOKEN="your_access_token_here"

# Windows
set HF_TOKEN=your_access_token_here

# 代码中读取环境变量
import os
from huggingface_hub import login

login(token=os.environ.get("HF_TOKEN"))

验证登录

from huggingface_hub import whoami

# 查看当前登录用户
user_info = whoami()
print(f"用户名: {user_info['name']}")
print(f"组织: {user_info.get('orgs', [])}")

验证安装

基础功能测试

import transformers
import torch

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

# 测试 Pipeline
from transformers import pipeline

# 情感分析
classifier = pipeline("sentiment-analysis")
result = classifier("I love Hugging Face Transformers!")
print(f"情感分析结果: {result}")

# 文本生成
generator = pipeline("text-generation", model="gpt2")
result = generator("Hello, I'm a language model", max_length=30, num_return_sequences=1)
print(f"文本生成结果: {result}")

GPU 推理测试

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载模型到 GPU
model_name = "gpt2"
model = AutoModelForCausalLM.from_pretrained(model_name)
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 移动到 GPU
if torch.cuda.is_available():
    model = model.to("cuda")
    print(f"模型已加载到 GPU: {torch.cuda.get_device_name(0)}")
else:
    print("使用 CPU 推理")

# 测试推理
text = "The future of AI is"
inputs = tokenizer(text, return_tensors="pt")

if torch.cuda.is_available():
    inputs = {k: v.to("cuda") for k, v in inputs.items()}

with torch.no_grad():
    outputs = model.generate(**inputs, max_length=50)

result = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(f"生成结果: {result}")

完整环境检查脚本

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

def check_environment():
    print("=" * 60)
    print("Hugging Face Transformers 环境检查")
    print("=" * 60)
    
    # 检查 Python 版本
    import sys
    print(f"\nPython 版本: {sys.version}")
    
    # 检查 Transformers
    try:
        import transformers
        print(f"Transformers 版本: {transformers.__version__}")
    except ImportError:
        print("Transformers 未安装！")
        return False
    
    # 检查 PyTorch
    try:
        import torch
        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()}")
            for i in range(torch.cuda.device_count()):
                print(f"  GPU {i}: {torch.cuda.get_device_name(i)}")
    except ImportError:
        print("PyTorch 未安装！")
    
    # 检查 datasets
    try:
        import datasets
        print(f"Datasets 版本: {datasets.__version__}")
    except ImportError:
        print("Datasets 未安装")
    
    # 检查 accelerate
    try:
        import accelerate
        print(f"Accelerate 版本: {accelerate.__version__}")
    except ImportError:
        print("Accelerate 未安装")
    
    # 检查 Hugging Face Hub 登录状态
    try:
        from huggingface_hub import whoami
        user = whoami()
        print(f"Hugging Face 登录用户: {user['name']}")
    except Exception as e:
        print(f"Hugging Face 未登录: {e}")
    
    # 测试基础功能
    print("\n" + "=" * 60)
    print("功能测试")
    print("=" * 60)
    
    try:
        from transformers import pipeline
        classifier = pipeline("sentiment-analysis")
        result = classifier("Test")
        print(f"Pipeline 测试: 通过 ✓")
    except Exception as e:
        print(f"Pipeline 测试: 失败 ✗ - {e}")
    
    print("\n" + "=" * 60)
    print("环境检查完成")
    print("=" * 60)
    
    return True

if __name__ == "__main__":
    check_environment()

常见问题解决

1. CUDA 版本不匹配

问题：RuntimeError: CUDA error: no kernel image is available

解决：

# 检查 CUDA 版本
nvidia-smi

# 安装对应版本的 PyTorch
# 例如 CUDA 11.8
pip install torch --index-url https://download.pytorch.org/whl/cu118 --force-reinstall

2. 模型下载失败

问题：OSError: We couldn't connect to 'https://huggingface.co'

解决：

# 设置镜像（国内用户）
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

# 或使用本地缓存
from transformers import AutoModel
model = AutoModel.from_pretrained("bert-base-chinese", local_files_only=True)

3. 显存不足

问题：RuntimeError: CUDA out of memory

解决：

# 使用 CPU 加载
model = AutoModel.from_pretrained("model_name", device_map="cpu")

# 或使用 8bit 量化
model = AutoModel.from_pretrained("model_name", load_in_8bit=True)

# 或使用更小的模型
model = AutoModel.from_pretrained("distilbert-base-uncased")

4. Windows 安装问题

问题：安装速度慢或失败

解决：

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

# 或升级 pip 和 setuptools
python -m pip install --upgrade pip setuptools wheel

开发环境推荐

VS Code 配置

推荐安装的扩展：

• Python
• Jupyter
• Pylance
• autoDocstring

settings.json 配置：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/transformers-env/bin/python",
    "python.analysis.typeCheckingMode": "basic",
    "jupyter.askForKernelRestart": false,
    "editor.formatOnSave": true,
    "python.formatting.provider": "black"
}

Jupyter Notebook

# 安装 Jupyter
pip install jupyterlab ipywidgets

# 启动
jupyter lab

Google Colab

Colab 提供免费的 GPU 资源，适合学习和实验：

# 在 Colab 中安装
!pip install transformers datasets accelerate

# 检查 GPU
!nvidia-smi

# 登录 Hugging Face
from huggingface_hub import notebook_login
notebook_login()

下一步

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

• Pipeline 快速入门 - 使用高层 API 快速上手
• 模型加载与使用 - 深入理解模型架构

参考资源

• PyTorch 安装指南
• Transformers 安装文档
• Hugging Face Hub 文档
• CUDA 下载页面