HuggingFace生态工具使用指南

HuggingFace生态

模型层
├── 🤗 Hub          —— 模型/数据集托管平台
├── transformers    —— 模型加载与推理（通用框架）
├── diffusers      —— 扩散模型（文生图/图生图）
└── peft          —— 参数高效微调（LoRA/QLoRA）

数据处理层
├── datasets      —— 数据集加载与处理
├── tokenizers    —— 高性能分词器
└── evaluate     —— 模型评估标准

部署层
├── TGI (Text Generation Inference) —— 高性能推理服务器
├── optimum       —— 硬件加速和量化
├── gradio        —— 快速搭建Demo界面
└── spaces        —— Demo托管平台

from huggingface_hub import snapshot_download

# 下载完整模型
snapshot_download(repo_id="Qwen/Qwen2.5-7B-Instruct", 
                  local_dir="./models/qwen2.5-7b")

# 只下载指定文件
snapshot_download(repo_id="Qwen/Qwen2.5-7B-Instruct",
                  allow_patterns=["*.json", "*.safetensors"],
                  local_dir="./models/qwen2.5-7b")

from huggingface_hub import HfApi

api = HfApi()

# 列出模型文件
files = api.list_repo_files("Qwen/Qwen2.5-7B-Instruct")
print(files)
# 输出：['config.json', 'model-00001-of-00004.safetensors', ...]

# 获取文件大小
model_info = api.model_info("Qwen/Qwen2.5-7B-Instruct")

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

# 或者直接设置镜像环境变量
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_name = "Qwen/Qwen2.5-7B-Instruct"

# 加载tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)

# 加载模型（半精度，节省显存）
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,        # 半精度
    device_map="auto",                # 自动分配设备
    trust_remote_code=True,
    attn_implementation="flash_attention_2",  # 使用Flash Attention加速
)

# 推理
inputs = tokenizer("你好，请问什么是Transformer？", return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=512)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)

from transformers import pipeline

# 一行代码搭建推理pipeline
generator = pipeline(
    "text-generation",
    model="Qwen/Qwen2.5-7B-Instruct",
    device_map="auto",
    torch_dtype=torch.float16,
)

result = generator("你好，请问什么是机器学习？", max_new_tokens=512)
print(result[0]['generated_text'])

# 使用bitsandbytes做4bit量化
from transformers import BitsAndBytesConfig

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
)

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=quantization_config,
    device_map="auto",
)

from peft import get_peft_model, LoraConfig, TaskType

# 配置LoRA
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=8,                    # 秩
    lora_alpha=16,          # 缩放参数
    lora_dropout=0.05,      # Dropout率
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],  # 目标模块
)

# 在基础模型上应用LoRA
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.float16)
peft_model = get_peft_model(model, lora_config)
peft_model.print_trainable_parameters()
# 输出：trainable params: 4,194,304 || all params: 7,000,000,000 || trainable%: 0.06

# 将LoRA权重合并到基础模型
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained(model_name)
merged_model = PeftModel.from_pretrained(base_model, "./lora-checkpoint")
merged_model = merged_model.merge_and_unload()

# 上传到HuggingFace Hub
merged_model.push_to_hub("your-username/your-model-name")
tokenizer.push_to_hub("your-username/your-model-name")

from datasets import load_dataset

# 加载数据集
dataset = load_dataset("json", data_files="my_data.jsonl")

# 数据处理
def preprocess_function(examples):
    # 格式化对话数据
    texts = []
    for instruction, output in zip(examples["instruction"], examples["output"]):
        text = f"指令：{instruction}\n回答：{output}"
        texts.append(text)
    return {"text": texts}

processed_dataset = dataset.map(preprocess_function, batched=True)
print(processed_dataset)

# 过滤短数据
dataset = dataset.filter(lambda x: len(x["text"]) > 50)

# 随机采样
sampled = dataset["train"].shuffle(seed=42).select(range(1000))

# 切分训练集/验证集
split_dataset = dataset["train"].train_test_split(test_size=0.1, seed=42)

import gradio as gr
from transformers import pipeline

# 加载模型
generator = pipeline("text-generation", model="Qwen/Qwen2.5-7B-Instruct")

# 创建聊天界面
def chat(message, history):
    response = generator(message, max_new_tokens=512)
    return response[0]['generated_text']

gr.ChatInterface(
    fn=chat,
    title="我的AI助手",
    description="基于Qwen2.5-7B的聊天机器人"
).launch(share=True)  # share=True生成公网链接

with gr.Blocks() as demo:
    gr.Markdown("# AI文本分析工具")
    
    with gr.Tab("文本生成"):
        input_text = gr.Textbox(label="输入", lines=5)
        output_text = gr.Textbox(label="输出", lines=5)
        generate_btn = gr.Button("生成")
        generate_btn.click(fn=generate, inputs=input_text, outputs=output_text)
    
    with gr.Tab("文本分类"):
        input_text = gr.Textbox(label="输入")
        output_label = gr.Label(label="分类结果")
        classify_btn = gr.Button("分类")
        classify_btn.click(fn=classify, inputs=input_text, outputs=output_label)

demo.launch()

1. 创建Space（选择Gradio/Streamlit）
2. 上传app.py和requirements.txt
3. 配置硬件（CPU免费/GPU需要订阅）
4. 自动构建和部署

# Docker方式部署
docker run --gpus all -p 8080:80 \
    -v $PWD/data:/data \
    ghcr.io/huggingface/text-generation-inference:latest \
    --model-id Qwen/Qwen2.5-7B-Instruct \
    --num-shard 2  # 多GPU并行

# 查看本地缓存的模型
huggingface-cli scan-cache

# 删除不需要的模型
huggingface-cli delete-cache

# 登录（上传模型需要）
huggingface-cli login

# 转换为ONNX格式
from optimum.onnxruntime import ORTModelForCausalLM

model = ORTModelForCausalLM.from_pretrained(model_name, export=True)
model.save_pretrained("./onnx-model")

from evaluate import load

# 加载评估指标
accuracy = load("accuracy")
rouge = load("rouge")
perplexity = load("perplexity")

# 计算指标
results = accuracy.compute(predictions=preds, references=refs)