Fedora 39环境下HuggingFace的完整安装指南 (2025年05月版)

引言

HuggingFace是当前最流行的自然语言处理(NLP)库之一，提供了大量预训练模型和便捷的API。本指南将详细介绍在Fedora 39系统上完整安装HuggingFace生态系统的步骤，包括transformers库、datasets库以及相关依赖的配置。

准备工作

在开始之前，请确保：

已安装Fedora 39操作系统
拥有管理员权限(sudo)
网络连接正常(部分安装包需要从国外源下载)

步骤1：更新系统并安装基础依赖

首先更新系统并安装Python和必要的开发工具：

代码片段

# 更新系统软件包
sudo dnf update -y

# 安装Python和pip
sudo dnf install python3 python3-pip -y

# 安装开发工具链
sudo dnf groupinstall "Development Tools" -y

# 安装其他必要依赖
sudo dnf install python3-devel openssl-devel bzip2-devel libffi-devel -y

注意事项：
– Fedora默认使用Python3，无需额外配置Python2环境
– Development Tools组包含gcc等编译工具，是构建某些Python包所必需的

步骤2：创建Python虚拟环境(推荐)

为避免污染系统Python环境，建议创建虚拟环境：

代码片段

# 创建虚拟环境目录(可选位置)
mkdir ~/huggingface_env && cd ~/huggingface_env

# 创建虚拟环境
python3 -m venv huggingface

# 激活虚拟环境
source huggingface/bin/activate

激活后，命令行提示符前会显示(huggingface)标识。

步骤3：安装PyTorch或TensorFlow(二选一)

HuggingFace需要深度学习框架作为后端。PyTorch是官方推荐的选择：

PyTorch安装方案(推荐)：

代码片段

# 查看CUDA版本(如果有NVIDIA显卡)
nvidia-smi | grep "CUDA Version"

# 根据CUDA版本选择合适的PyTorch安装命令
# CUDA 12.x:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

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

# CPU版本:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

TensorFlow安装方案：

代码片段

# GPU版本(需要CUDA)
pip install tensorflow[and-cuda]

# CPU版本
pip install tensorflow

实践经验：
– PyTorch通常与HuggingFace生态集成更好，推荐优先选择
– 如果没有NVIDIA显卡或不想使用GPU，选择CPU版本即可

步骤4：安装HuggingFace核心库

现在可以安装HuggingFace的核心组件了：

代码片段

pip install transformers datasets evaluate accelerate sentencepiece protobuf scipy sklearn pandas tqdm

主要组件说明：
– transformers: HuggingFace的核心模型库
– datasets: 数据集加载和处理工具
– evaluate: 模型评估指标库
– accelerate: 分布式训练加速工具

注意事项：
– sentencepiece是处理某些tokenizer所需的依赖
– protobuf是模型序列化所需依赖

步骤5：验证安装

创建一个简单的Python脚本来验证所有组件是否正常工作：

代码片段

from transformers import pipeline, __version__ as tf_version
from datasets import __version__ as ds_version

print(f"HuggingFace Transformers版本: {tf_version}")
print(f"HuggingFace Datasets版本: {ds_version}")

# 测试一个简单的文本分类管道
classifier = pipeline("sentiment-analysis")
result = classifier("I love using HuggingFace libraries!")
print(result)

保存为test_hf.py并运行：

代码片段

python test_hf.py

预期输出类似：

代码片段

HuggingFace Transformers版本: x.x.x
HuggingFace Datasets版本: y.y.y 
[{'label': 'POSITIVE', 'score': 0.9998}]

(可选)步骤6：配置缓存目录和代理设置

为提升使用体验，可以配置以下环境变量：

代码片段

# HuggingFace模型缓存目录(避免默认存放到~/.cache)
echo 'export HF_HOME=~/hf_cache' >> ~/.bashrc

# (如有需要)设置代理解决下载问题(替换为你的代理地址)
echo 'export http_proxy=http://your.proxy.address:port' >> ~/.bashrc 
echo 'export https_proxy=http://your.proxy.address:port' >> ~/.bashrc 

source ~/.bashrc # 使配置生效

mkdir -p $HF_HOME # 创建缓存目录

实践经验：
– HF_HOME可以设置为大容量存储位置，因为模型文件通常很大(GB级别)
– China用户可能需要设置镜像源或代理来加速下载：

代码片段

from huggingface_hub import configure_http_backend  
configure_http_backend(backend="aiohttp")

(可选)步骤7：Jupyter Notebook支持

如果需要在Jupyter中使用HuggingFace:

代码片段

pip install notebook ipywidgets jupyterlab 

# Jupyter widgets支持 
jupyter nbextension enable --py widgetsnbextension 

# Jupyter Lab支持 
jupyter labextension install @jupyter-widgets/jupyterlab-manager

FAQ常见问题解决

SSL证书错误：

代码片段

sudo dnf install ca-certificates -y 
sudo update-ca-trust force-enable

CUDA相关错误：
- 确认NVIDIA驱动已正确安装：nvidia-smi
- PyTorch CUDA版本应与系统CUDA版本匹配

内存不足错误：
尝试使用较小的模型或在代码中添加：

代码片段

from transformers import AutoModelForSequenceClassification 
model = AutoModelForSequenceClassification.from_pretrained("model_name", device_map="auto")

下载速度慢：
使用镜像源或huggingface-cli登录：
代码片段
```
pip install huggingface-hub 
huggingface-cli login 
```

GPU加速优化建议（如有NVIDIA显卡）

确认CUDA可用性：
在Python中运行：

代码片段

import torch 
print(torch.cuda.is_available()) # True表示可用 
print(torch.cuda.get_device_name(0)) # GPU型号信息

混合精度训练（减少显存占用）：
在训练脚本中添加：

代码片段

from accelerate import Accelerator 

accelerator = Accelerator(mixed_precision="fp16") # or "bf16" for newer GPUs

使用更好的优化器：
推荐使用AdamW或Lion优化器:

代码片段

from transformers import AdamW, get_scheduler 

optimizer = AdamW(model.parameters(), lr=5e-5)

HuggingFace生态扩展组件（按需选择）

gradio: Web界面快速演示模型效果
peft: LoRA等参数高效微调方法
trl: Transformer强化学习支持

示例gradio应用代码（保存为app.py）:

代码片段

from transformers import pipeline  
import gradio as gr  

pipe = pipeline("text-generation", model="gpt2")  

def generate(text):  
    return pipe(text, max_length=50)[0]["generated_text"]  

demo = gr.Interface(fn=generate, inputs="text", outputs="text")  
demo.launch()

运行后访问本地URL即可测试GPT-2文本生成效果。

Python包管理最佳实践建议

冻结当前环境配置（便于复现）：

代码片段

pip freeze > requirements.txt

重建相同环境：

代码片段

pip install -r requirements.txt

定期更新依赖（保持兼容性）：

代码片段

pip list --outdated #查看过期包   
pip install -U package_name #更新指定包

清理缓存空间（特别是频繁更换模型时）：

代码片段

huggingface-cli delete-cache #清理下载缓存   
df -h $HF_HOME #查看缓存占用空间

Hugging Face Hub使用技巧

搜索适合任务的模型:
访问https://huggingface.co/models按任务筛选
CLI常用命令:

代码片段

huggingface-cli login #登录账号（上传模型需要）   
huggingface-cli download model_name #直接下载模型到缓存   
huggingface-cli repo create my-model --organization my-team #创建新仓库

直接从Hub加载模型的Python代码示例:

代码片段

from transformers import AutoModel, AutoTokenizer    

model_name = "bert-base-uncased"    
tokenizer = AutoTokenizer.from_pretrained(model_name)    
model = AutoModel.from_pretrained(model_name)    

inputs = tokenizer("Hello world!", return_tensors="pt")    
outputs = model(**inputs)    
print(outputs.last_hidden_state.shape)

4.分享自定义微调后的模型:
上传到Hub只需几行代码:

代码片段

from huggingface_hub import notebook_login    

notebook_login() #认证     
model.push_to_hub("my-finetuned-model")     
tokenizer.push_to_hub("my-finetuned-model")

5.高级用法——自定义推理API:
参考官方文档部署自己的推理端点服务。

通过以上完整指南，您应该已经在Fedora39系统上成功搭建了功能完善的Hugging Face开发环境。建议从官方示例教程开始实践：https://huggingface.co/docs/transformers/quicktour，逐步探索各种预训练模型的强大能力。