hugging face 使用教程——

概述

本篇存在的意义是快速介绍hugging face使用，梳理主要部件，梳理易混淆概念。原因是：目前hugging face的使用，官方放在了3个地方（参考链接部分）：使用文档、NLP教程、Transformers git的readme 文件，很多重叠内容比较浪费时间，很容易看懵。等大家有了主要概念再去看需要具体看某个函数或功能。

本篇主要从以下维度来快速介绍hugging face使用：

1、是什么：我觉得这么讲更适合当前（20240603）初学者，hugging face本身集成了常用的三大功能：model hub、data hub、space，和一个著名源代码库Transformers。

2、怎么用：这里除了上面的几大部件，最需要知道的几个易混淆名词：pipeline、AutoTokenizer、AutoConfig、AutoModel、AutoModelForXXX、accelerate、Trainer、peft、Agents、optimum。

一、是什么

1、model hub

登录官方网站（https://huggingface.co/models）可以看到如下的页面（我们选择models 选项卡）。

其中蓝色和绿色，就是后面怎么用的时候代码里面对应的参数名，分别代表任务类型和模型名字，其中任务类型在代码中全部换为小写。

模型内部如下，这个是一个比较复杂的代码，并且当前没有被hugging face 的Transformers git代码集成，所以有自定义的一些源码，就需要也上传到对应的hub上，调用逻辑，主要是通过config json 里面的map 字段。

2、databub

整体和model hub类似, 登录官方网站（https://huggingface.co/datasets）

3、space

其实就是对应的服务的一个demo地址，可以先简单试一下模型效果。登录官方网站（https://huggingface.co/spaces)

4、docs

就是对应的一些文档，这部分和源码里面的readme 有重叠。官方网址（https://huggingface.co/docs）

5、Transformers

这是整个工程的开源代码库，这个要区别Transform（这是一个架构名称，区别与CNN），这个git里面集成了一些知名的结构的源代码，比如llama，并且没有做过多的抽象，可以方便快速查看源代码

比如：https://github.com/huggingface/transformers/tree/main/src/transformers/models

这里就要区别使用model bub，这是两种不同的使用方式，一般而言 model bub会更新和更全。官方也有文档写怎么提交这两种方式，参见这里https://github.com/huggingface/transformers/blob/main/docs/source/zh/custom_models.md

二、怎么用

这里以pytorch和LLM类为例，图像和声音的可以参考官方对应文档，整体流程差不多。涉及的python安装包（建议使用Python虚拟环境）：

pip install transformers datasets evaluate accelerate torch

1、AutoTokenizer、AutoModel、AutoModelForXXX、AutoConfig

首先这里还是建议使用Auto类别，AutoModel、AutoModelForXXX、特定类区别：

AutoModel：加载基础的预训练模型，不带特定任务头部。

AutoModelFor 系列：为特定任务（如分类、标注、问答等）加载预训练模型，并添加适当的任务头部。

直接使用特定模型类（如 BertModel.from_pretrained）：提供明确性和特定模型功能，适合需要特定模型特性的场景。

PS：

*这里AutoTokenizer需要和model绑定保持一致，因为不同的模型使用的Tokenizer可能不一样。需要基本了解BPE算法，还有就是hugging face tokenizer默认为快速版本使用rust编写，也可以选择满速版本使用Python原生实现，只需要在参数中将 use_fast=False 即可。

*这里AutoConfig需要和model等绑定保持一致，并且AutoConfig并不能加载权重。

使用范例：

from transformers import AutoModel, AutoModelForSequenceClassification, AutoTokenizer, AutoConfig, BertModel, BertTokenizer


model_name = "bert-base-uncased"

# 使用AutoModel加载基础模型
model = AutoModel.from_pretrained(model_name)
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 使用AutoModelFor加载适用于特定任务的模型
model_for_classification = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

# 直接使用BertModel加载模型,等价使用AutoModel加载基础模型
model = BertModel.from_pretrained(model_name)
tokenizer = BertTokenizer.from_pretrained(model_name)

# 从预训练模型名称加载配置
config = AutoConfig.from_pretrained(model_name)
model = AutoModel.from_config(config)  # 使用配置初始化模型（仅创建模型，不加载权重）
model = AutoModel.from_pretrained(model_name)  # 从预训练模型名称加载模型（包括配置和权重）
tokenizer = AutoTokenizer.from_pretrained(model_name)

2、pipeline

上面代码其实已经很简洁，但使用pipeline后可以仅需要一行代码。

其中pipeline支持的任务：https://huggingface.co/docs/transformers/main/en/main_classes/pipelines#transformers.pipeline.task

from transformers import pipeline


# 加载文本分类pipeline
classifier = pipeline("sentiment-analysis", model="bert-base-uncased")

# 示例文本
text = "I love using transformers library!"

# 进行情感分析
result = classifier(text)
print(result)


#其中pipeline参数可以为多种

# 使用默认
classifier = pipeline("sentiment-analysis")

# 指定model
classifier = pipeline("sentiment-analysis", model="bert-base-uncased")
model_name = "bert-base-uncased"
model = AutoModelForSequenceClassification.from_pretrained(model_name)
tokenizer = AutoTokenizer.from_pretrained(model_name)
classifier = pipeline("sentiment-analysis", model=model, tokenizer=tokenizer)

自定义pipeline

官方：https://github.com/huggingface/transformers/blob/main/docs/source/zh/add_new_pipeline.md

简单的修改后处理的代码如下：

class MyPipeline(TextClassificationPipeline):
    def postprocess():
        # Your code goes here
        scores = scores * 100
        # And here

my_pipeline = MyPipeline(model=model, tokenizer=tokenizer, ...)
# or if you use *pipeline* function, then:
my_pipeline = pipeline(model="xxxx", pipeline_class=MyPipeline)

完整的一个示例如下：

from transformers import AutoTokenizer, AutoModelForSequenceClassification
from transformers import Pipeline
import torch


class CustomTextClassificationPipeline(Pipeline):
    def __init__(self, model, tokenizer, **kwargs):
        super().__init__(model=model, tokenizer=tokenizer, **kwargs)

    def _sanitize_parameters(self, **kwargs):
        preprocess_kwargs = {}
        forward_kwargs = {}
        postprocess_kwargs = {}
        return preprocess_kwargs, forward_kwargs, postprocess_kwargs

    def preprocess(self, inputs):
        # 自定义预处理步骤
        return self.tokenizer(inputs, padding=True, truncation=True, return_tensors="pt")

    def _forward(self, model_inputs):
        # 自定义前向传播步骤
        with torch.no_grad():
            outputs = self.model(**model_inputs)
        return outputs

    def postprocess(self, model_outputs):
        # 自定义后处理步骤
        logits = model_outputs.logits
        predictions = torch.nn.functional.softmax(logits, dim=-1)
        return predictions

# 加载模型和分词器
model_name_or_path = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name_or_path)
model = AutoModelForSequenceClassification.from_pretrained(model_name_or_path)

# 创建自定义 pipeline
custom_pipeline = CustomTextClassificationPipeline(model=model, tokenizer=tokenizer)

# 示例文本
texts = [
    "I love using the transformers library!",
    "I had a terrible experience with this product."
]

# 进行分类
results = custom_pipeline(texts)

# 输出结果
for text, result in zip(texts, results):
    print(f"Text: {text}\nClassification: {result}\n")

3、accelerate

这里对等的相关概念还有：megtron、PyTorch FSDP、deepspeed。这里就不对比详细区别，因为整体的技术都是zero系列的思路，只不过不同的时刻支持的方案有区别，当你用的时候可以查看所使用版本支持哪些并行方案。整体适合生态而言：

*Accelerate：适合希望快速实现分布式训练的用户，尤其是使用 Hugging Face 生态系统的用户。

*DeepSpeed：适合需要训练非常大规模模型的用户，对性能和资源利用率有高要求的场景。

*PyTorch FSDP：适合需要在多 GPU 上进行大规模模型训练的用户，尤其是已经在使用 PyTorch 的用户。

使用方式也相对简单，安装accelerate、简单设置、简单修改训练源码、启动训练，参照：https://github.com/huggingface/transformers/blob/main/docs/source/zh/accelerate.md

# 安装库

pip install accelerate

# 简单配置

accelerate config

修改训练源码（查看+、-部分）

 + from accelerate import Accelerator
  from transformers import AdamW, AutoModelForSequenceClassification, get_scheduler
+ accelerator = Accelerator()
  model = AutoModelForSequenceClassification.from_pretrained(checkpoint, num_labels=2)
  optimizer = AdamW(model.parameters(), lr=3e-5)
- device = torch.device("cuda") if torch.cuda.is_available() else torch.device("cpu")
- model.to(device)
+ train_dataloader, eval_dataloader, model, optimizer = accelerator.prepare(
+     train_dataloader, eval_dataloader, model, optimizer

+ )
  num_epochs = 3
  num_training_steps = num_epochs * len(train_dataloader)
  lr_scheduler = get_scheduler(
      "linear",
      optimizer=optimizer,
      num_warmup_steps=0,
      num_training_steps=num_training_steps
  )
  progress_bar = tqdm(range(num_training_steps))
  model.train()
  for epoch in range(num_epochs):
      for batch in train_dataloader:
-         batch = {k: v.to(device) for k, v in batch.items()}
          outputs = model(**batch)
          loss = outputs.loss
-         loss.backward()
+         accelerator.backward(loss)
          optimizer.step()
          lr_scheduler.step()
          optimizer.zero_grad()
          progress_bar.update(1)

启动训练

accelerate launch train.py

4、peft

Transformers原生支持一些PEFT方法，这意味着你可以加载本地存储或在Hub上的adapter权重，并使用几行代码轻松运行或训练它们。以下是受支持的方法：Low Rank Adapters、IA3、AdaLoRA。参考：https://github.com/huggingface/transformers/blob/main/docs/source/zh/peft.md

要从huggingface的Transformers库中加载并使用PEFTadapter模型，请确保Hub仓库或本地目录包含一个adapter_config.json文件和adapter权重，如上例所示。然后，您可以使用AutoModelFor类加载PEFT adapter模型。

1）要为因果语言建模加载一个PEFT adapter模型：可以使用AutoModelFor类或基础模型类（如OPTForCausalLM或LlamaForCausalLM）来加载一个PEFT adapter；也可以通过load_adapter方法来加载 PEFT adapter。

2）添加新的adapter，切换adapter，启用禁用adapter。这里需要区别：

*enable_adapters 影响的是整个模型的适配器功能开关。

*set_active_adapters 影响的是具体的适配器激活状态。默认使用最后一次调用该函数的适配器，所以，当需要同时使用多个适配器的时候，同时传给该函数，切不要分次传入（只有最后一个生效）。

*load_adapter：从外部资源加载预训练的适配器，适用于已经有预训练适配器的情况。

*add_adapter：在模型中添加一个新的适配器，适用于需要在新任务上训练适配器的情况。

* 调用关系链：enable_adapters：如果你希望在推理或训练过程中使用适配器，那么你需要调用 enable_adapters 方法。如果你不调用这个方法，模型将不使用适配器。set_active_adapters：如果你只有一个适配器，并且不需要切换适配器，那么你不需要调用 set_active_adapters 方法。如果你有多个适配器并需要在它们之间切换，那么你需要调用这个方法。

*get_peft_model & add_adapter： get_peft_model是 PEFT 库的一部分，专注于参数高效微调技术。add_adapter 是 AdapterHub 或 Transformers 库的一部分。

from transformers import AutoModelForCausalLM, AutoTokenizer


# 定义模型和适配器的ID
model_id = "facebook/opt-350m"
peft_model_id = "ybelkada/opt-350m-lora"

# 加载基础模型
model = AutoModelForCausalLM.from_pretrained(model_id)

# 加载PEFT适配器
model.load_adapter(peft_model_id, adapter_name="adapter_1")

# 再次加载相同的PEFT适配器，作为不同的适配器名称
model.load_adapter(peft_model_id, adapter_name="adapter_2")

# 启用适配器
model.enable_adapters()  # 禁用： model.disable_adapters()

# 设置使用的适配器，展示切换
model.set_active_adapters("adapter_1")  # 使用 adapter_1
print("Using adapter_1:")
inputs = tokenizer("Hello, how are you?", return_tensors="pt")
outputs = model.generate(**inputs)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

model.set_active_adapters("adapter_2")  # 使用 adapter_2
print("Using adapter_2:")
outputs = model.generate(**inputs)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

# 同时使用多个适配器（如果支持）
model.set_active_adapters(["adapter_1", "adapter_2"])  # 同时使用 adapter_1 和 adapter_2
print("Using adapter_1 and adapter_2:")
outputs = model.generate(**inputs)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

# 只使用 adapter_1
model.set_active_adapters("adapter_1")
print("Using adapter_1 again:")
outputs = model.generate(**inputs)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

# 只使用 adapter_2
model.set_active_adapters("adapter_2")
print("Using adapter_2 again:")
outputs = model.generate(**inputs)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

5、Trainer

对于pytorch，当你的模型是模型都是标准的 torch.nn.Module，然后可以使用trainer来替代自己手写训练循环，初次之外trainer:包含了基础的训练循环并且为诸如分布式训练（也就是可以理解默认使用了acclerate），混合精度等特性增加了额外的功能。需要注意你可以使用回调来将trainer与其他库集成，查看训练循环来报告进度或提前结束训练。回调不会修改训练循环。如果想自定义损失函数等，就需要子类化 Trainer。这里补充一点：Trainer 类支持的损失函数主要取决于所使用的模型。大多数预训练模型在其 forward 方法中已经定义了适合其任务的损失函数。如果需要自定义损失函数，可以通过继承 Trainer 类并重写 compute_loss 方法来实现。

from transformers import Trainer, TrainingArguments, AutoModelForSequenceClassification, AutoTokenizer,  PreTrainedModel, PretrainedConfig
from datasets import load_dataset
import numpy as np
from sklearn.metrics import accuracy_score, precision_recall_fscore_support
from peft import LoraConfig


# 加载数据集
dataset = load_dataset("glue", "mrpc")

# 加载预训练模型和分词器
model_name = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

#  ———————————————————————————————————— 如下是自定义模型——————————————————————————————————————————————————  #

"""
class CustomBertModel(PreTrainedModel):
    def __init__(self, config):
        super().__init__(config)
        self.bert = AutoModelForSequenceClassification.from_pretrained("bert-base-uncased", config=config)
        self.custom_layer = nn.Linear(config.hidden_size, config.num_labels)

    def forward(self, input_ids=None, attention_mask=None, token_type_ids=None, labels=None):
        outputs = self.bert(input_ids, attention_mask=attention_mask, token_type_ids=token_type_ids)
        logits = self.custom_layer(outputs[1])  # 使用 BERT 的池化输出
        loss = None
        if labels is not None:
            loss_fct = nn.CrossEntropyLoss()
            loss = loss_fct(logits.view(-1, self.config.num_labels), labels.view(-1))
        return (loss, logits) if loss is not None else logits

# 加载配置和模型
config = PretrainedConfig.from_pretrained("bert-base-uncased", num_labels=2)
model = CustomBertModel(config)
"""

# ———————————————————————————————————— 如下是使用LoRa —————————————————————————————————————————————————— #
"""
peft_config = LoraConfig(
    lora_alpha=16,
    lora_dropout=0.1,
    r=64,
    bias="none",
    task_type="SEQ_CLS",
)
model.add_adapter(peft_config)
model.enable_adapters()  # 启用适配器，禁用： model.disable_adapters()

# peft_model = get_peft_model(model, peft_config) # 上面两行代码也可以使用这行代码替换
"""

# 预处理数据
def preprocess_function(examples):
    return tokenizer(examples['sentence1'], examples['sentence2'], truncation=True)
encoded_dataset = dataset.map(preprocess_function, batched=True)

# 定义计算指标
def compute_metrics(pred):
    labels = pred.label_ids
    preds = np.argmax(pred.predictions, axis=1)
    precision, recall, f1, _ = precision_recall_fscore_support(labels, preds, average='binary')
    acc = accuracy_score(labels, preds)
    return {
        'accuracy': acc,
        'f1': f1,
        'precision': precision,
        'recall': recall
    }

# 设置训练参数
training_args = TrainingArguments(
    output_dir='./results',
    evaluation_strategy="epoch",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    num_train_epochs=3,
    weight_decay=0.01,
)

# 初始化 Trainer
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=encoded_dataset['train'],
    eval_dataset=encoded_dataset['validation'],
    compute_metrics=compute_metrics
)

# 开始训练
trainer.train()

# 评估模型
trainer.evaluate()

# 保存模型
save_dir = ''
model.save_pretrained(save_dir)
model = AutoModelForSequenceClassification.from_pretrained(save_dir)