企业官网建设流程全解析

如何上手 HuggingFace Transformers：153 个模型教程 Notebook 完整实操指南

【免费下载链接】Transformers-TutorialsThis repository contains demos I made with the Transformers library by HuggingFace.项目地址: https://gitcode.com/GitHub_Trending/tr/Transformers-Tutorials

手上有张 COCO 图片，想给沙发上两只猫画上检测框；又有一堆发票，想让模型自动抽取出金额。官方文档把 API 讲得很细，可示例都是碎片化代码块，拼不成能跑的流程。Transformers-Tutorials 解决的就是这个问题：HuggingFace 核心贡献者 Niels Rogge 按模型组织了 153 个 Jupyter Notebook，覆盖文本、视觉、文档 AI 三大类。从加载模型到跑通完整微调，复制即得结果。

它解决了什么问题

用这个项目之前，最常见的三个卡点：

1. 文档讲 API，示例要自己拼。官方文档每个类都讲得透，但数据怎么预处理、训练循环怎么搭、评估指标怎么算，得自己写。这个仓库里每个 Notebook 都是完整可运行的 demo：加载模型、准备数据、微调、评估，一条龙给出来。
2. 不知道该选哪个训练框架。原生 PyTorch、PyTorch Lightning 还是 🤗 Trainer？README 里专门有一节讲三者的取舍，同一任务还会给出不同实现——比如 TrOCR 微调就同时有 Seq2SeqTrainer 和原生 PyTorch 两个版本，可以对照着看。
3. 环境配起来费劲。本地跑一个教程要装 torch、transformers、datasets、accelerate 等一长串依赖，版本还容易打架。好在每个 Notebook 顶部都带 Colab 按钮，点一下就在 Google 免费 GPU 上直接运行，本地一个包都不用装。

功能全景

仓库按模型分目录组织，共 75 个模型目录。按能力域归类如下：

3 分钟跑通环境

仓库用 uv（一个快速的 Python 包管理器）管理依赖，要求 Python 3.12 以上。pyproject.toml 里锁定了 32 个依赖，包括 transformers 4.57.3 和 torch 2.9.1，装一次就能跑全部教程：

git clone https://gitcode.com/GitHub_Trending/tr/Transformers-Tutorials cd Transformers-Tutorials uv sync # 按 pyproject.toml 一键装齐依赖

然后启动 Jupyter，挑一个 Notebook 打开运行：

uv run jupyter notebook

第一个教程建议从 DETR/DETR_minimal_example.ipynb 开始，代码量最小，几行就能出检测框。

核心用法精讲

用 DETR 做零样本目标检测

场景：想给图片画框，但手里没有任何标注数据。DETR（DEtection TRansformer）是端到端检测模型，不用自己写区域建议和 NMS（非极大值抑制）。

实际跑一下会发现，流程短到只有几行：

from transformers import DetrImageProcessor, DetrForObjectDetection import torch processor = DetrImageProcessor.from_pretrained("facebook/detr-resnet-50") model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50") encoding = processor(image, return_tensors="pt") # 自动缩放并归一化 with torch.no_grad(): outputs = model(**encoding)

两个值得注意的细节：processor 会自动把图片缩放到合适尺寸（最小边 800、最大边 1333），并用 ImageNet 的均值和标准差做归一化，预处理完全不用自己写；这个 ResNet-50 版本在 COCO validation 2017 上的 box AP 是 42.0，Notebook 后半段会把 outputs 转成框、置信度和类别标签的完整步骤。DETR 目录里还有在自定义气球数据集上微调的教程，推理跑通后可以接着学。

微调 LayoutLMv3 做文档实体抽取

场景：发票、表单这类文档需要抽出金额、日期、账号等实体字段。LayoutLMv3 把图像、词列表、框坐标三者一起喂给模型，让它学会利用版面布局。

核心就这几行：

from transformers import AutoProcessor from datasets import load_dataset processor = AutoProcessor.from_pretrained("microsoft/layoutlmv3-base", apply_ocr=False) dataset = load_dataset("nielsr/funsd-layoutlmv3") # 图像、词、框坐标、实体标签同时输入 encoding = processor(images, words, boxes=boxes, word_labels=word_labels, truncation=True, padding="max_length")

Notebook 以 FUNSD（表单实体抽取数据集）为例微调 LayoutLMv3ForTokenClassification，用 seqeval 评估实体级 F1，训练全程走 🤗 Trainer，基本是几行配置的事。

其余能力各挑一个代表：BERT 做 NER 微调、TrOCR 识别手写文字、SAM（Segment Anything）在自定义数据集上微调分割、ViLT 做视觉问答、VideoMAE 做视频分类，都在对应模型目录里能直接打开跑。

进阶技巧与常见坑

几个值得直接搬走的参数和习惯：

• 微调学习率用 5e-5。README 里作者明确说这是他微调 Transformer 时"几乎总用"的起点值。
• 推理一律套torch.no_grad()。推理时不算梯度，省下一大截显存，DETR 的 Notebook 特意留下这行注释。
• 自己写训练循环时用 Accelerate 接管硬件。多 GPU、混合精度、设备放置都不用手动处理，代码不用改。

报错排查清单：

适用边界

适合谁：想从零快速看到效果的入门者；想学"微调到底怎么做"并对比不同训练框架实现的开发者；做文档 AI 想直接看完整范例的人。

不适合谁：找生产级服务的人——这些是教学代码，要上线得自己重写成工程化代码；需要 TensorFlow 或 JAX 版本的人也要留意，README 明确说目前所有 demo 都只实现了 PyTorch。

与同类方案的取舍：官方文档覆盖面最全，查参数细节还得回文档；官方 examples 脚本偏工程、解释少；这个仓库在中间，Notebook 兼顾讲解和可运行，两者配合用效率最高。

写在最后

如果你要开始用 HuggingFace Transformers 库，先克隆这个仓库，挑两三个感兴趣的 Notebook 完整跑一遍，整个流程就有底了。

资源链接（仓库内相对路径）：

• 项目总览与教程清单：README.md
• 目标检测教程：DETR/
• 文档理解教程：LayoutLMv3/
• 视觉生态总览 Notebook：HuggingFace_vision_ecosystem_overview_(June_2022).ipynb.ipynb)
• 完整依赖清单：pyproject.toml

【免费下载链接】Transformers-TutorialsThis repository contains demos I made with the Transformers library by HuggingFace.项目地址: https://gitcode.com/GitHub_Trending/tr/Transformers-Tutorials