# HuggingFace实战案例集

**Repository Path**: agent-dev-team/huggingface-cases

## Basic Information

- **Project Name**: HuggingFace实战案例集
- **Description**: HuggingFace实战案例集：情感分析、文本生成、零样本分类、Tokenizer、Pipeline及BERT/Qwen垃圾邮件分类微调。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HuggingFace 生态实战：从模型应用到高效微调

本仓库是 HuggingFace 生态的学习案例集，覆盖从**直接使用预训练模型 / Pipeline**，到**Tokenizer、数据集、评估**，再到**基于 transformers 与 modelscope 微调落地**的完整链路。

## 项目结构

```text
CASE-huggingface_cases/
├── pyproject.toml          # 依赖源（uv 项目模式）
├── uv.lock                 # 锁定依赖树（禁止手改）
├── .gitignore
├── 1-情感分析.py            # 用 pipeline 做情感分类
├── 2-文本生成.py            # 用 pipeline 做文本生成
├── 3-零样本分类.py          # Zero-Shot Classification
├── 4-tokenizer使用.py       # Tokenizer 编解码与特殊标记
├── 5-model使用.py           # 直接加载模型与权重
├── 6-实现pipeline.py        # 手写简化版 pipeline
├── 7-垃圾邮件分类器.py       # 微调训练一个垃圾邮件分类器
└── 8-垃圾邮件分类器-Qwen.py  # 基于 Qwen 的垃圾邮件分类示例
```

依赖关系示意：

```mermaid
graph TD
    A[案例脚本 *.py] --> B[transformers / pipeline]
    A --> C[datasets 数据集]
    A --> D[evaluate 评估指标]
    A --> E[modelscope 模型托管]
    B --> F[torch 训练与推理后端]
    A --> F
    C --> G[numpy 数值计算]
```

## 环境准备（uv 项目模式）

本仓库使用 [uv](https://github.com/astral-sh/uv) 管理依赖：
`pyproject.toml` 为依赖源，`uv.lock` 为可复现的锁定树。

```bash
# 1. 安装 uv（如未安装）
pip install uv

# 2. 创建虚拟环境并安装锁定版本
uv sync

# 3. 运行任意案例（自动使用 .venv 解释器）
uv run python 1-情感分析.py
```

> `uv sync` 会自动创建 `.venv/` 并安装 `uv.lock` 中锁定的精确版本。
> 国内环境已默认配置 TUNA 镜像（`pyproject.toml` 的 `[tool.uv].index-url`），如需官方源：
> `uv sync --index-url https://pypi.org/simple`

## 仓库地址

> HuggingFace实战案例集：情感分析、文本生成、零样本分类、Tokenizer、Pipeline及BERT/Qwen垃圾邮件分类微调。

- Gitee：`https://gitee.com/ai-agentkai-fa/huggingface-cases`

## uv 工作流命令速查

```bash
uv add <包>               # 新增依赖并刷新 lock
uv remove <包>            # 移除依赖
uv lock --upgrade         # 按 pyproject 约束升级到最新可解析版本
uv sync --frozen          # 严格按 uv.lock 安装，不重新解析
uv run python <脚本>.py   # 在虚拟环境中运行脚本
```

> ⚠️ `uv.lock` 由 uv 自动生成，禁止手动编辑；改依赖请走 `uv add/remove/lock`。

## 依赖清单（顶层）

| 包           | 约束        | 用途                         |
| ------------ | ----------- | ---------------------------- |
| `transformers` | `>=4.30.0` | 模型 / Pipeline / Tokenizer  |
| `torch`       | `>=2.0.0`  | 训练与推理后端              |
| `datasets`    | `>=2.19.1` | 数据集加载与处理            |
| `evaluate`    | `>=0.4.6`  | 评估指标                    |
| `modelscope`  | `>=1.25.0` | 魔搭社区模型托管            |
| `numpy`       | `>=1.24.0` | 数值计算                    |

## 版本说明

`pyproject.toml` 中仅声明依赖下限以保留升级空间，精确版本由 `uv.lock` 锁定。
当前锁定结果（节选）：`torch 2.13.0`、`transformers 5.15.0`、`datasets 5.0.1`、
`modelscope 1.39.1`、`evaluate 0.4.6`、`numpy 2.5.2`。

如需锁定主版本（例如 transformers 4.x），在 `pyproject.toml` 追加上限后重新 `uv lock`：

```toml
"transformers>=4.30.0,<5.0",
```

## Windows 提示

部分 Windows 开启 **Smart App Control** 会拦截未签名的 `.venv\Scripts\python.exe`，
导致 `uv run` 报 `os error 4551`。解决方式：将项目目录加入 Smart App Control 白名单，
或用系统已签名 Python 指向 venv 的 `site-packages` 运行。