Hugging Face 课程

此仓库包含用于创建 Hugging Face 课程 的内容。该课程教你如何将 Transformer 模型应用于自然语言处理及其他领域的各种任务。在学习过程中，你将掌握如何使用 Hugging Face 生态系统——🤗 Transformers、🤗 Datasets、🤗 Tokenizers 和 🤗 Accelerate——以及 Hugging Face Hub。本课程完全免费且开源！

🌎 语言与翻译

语言	来源	作者
英语	chapters/en	@sgugger, @lewtun, @LysandreJik, @Rocketknight1, @sashavor, @osanseviero, @SaulLu, @lvwerra
孟加拉语 (进行中)	chapters/bn	@avishek-018, @eNipu
德语 (进行中)	chapters/de	@JesperDramsch, @MarcusFra, @fabridamicelli
西班牙语 (进行中)	chapters/es	@camartinezbu, @munozariasjm, @fordaz
波斯语 (进行中)	chapters/fa	@jowharshamshiri, @schoobani
法语	chapters/fr	@lbourdois, @ChainYo, @melaniedrevet, @abdouaziz
古吉拉特语 (进行中)	chapters/gu	@pandyaved98
希伯来语 (进行中)	chapters/he	@omer-dor
印地语 (进行中)	chapters/hi	@pandyaved98
印尼语 (进行中)	chapters/id	@gstdl
意大利语 (进行中)	chapters/it	@CaterinaBi, @ClonedOne, @Nolanogenn, @EdAbati, @gdacciaro
日语 (进行中)	chapters/ja	@hiromu166, @younesbelkada, @HiromuHota
韩语 (进行中)	chapters/ko	@Doohae, @wonhyeongseo, @dlfrnaos19, @nsbg
葡萄牙语 (进行中)	chapters/pt	@johnnv1, @victorescosta, @LincolnVS
俄语 (进行中)	chapters/ru	@pdumin, @svv73, @blademoon
泰卢固语 (进行中)	chapters/te	@Ajey95, @RahulKonda18
泰语 (进行中)	chapters/th	@peeraponw, @a-krirk, @jomariya23156, @ckingkan
土耳其语 (进行中)	chapters/tr	@tanersekmen, @mertbozkir, @ftarlaci, @akkasayaz
越南语	chapters/vi	@honghanhh
简体中文	chapters/zh-CN	@zhlhyx, petrichor1122, @1375626371
繁体中文 (进行中)	chapters/zh-TW	@davidpeng86, @thliang01
罗马尼亚语 (进行中)	chapters/ro	@Sigmoid, @eduard-balamatiuc, @FriptuLudmila, @tokyo-s, @hbkdesign, @grumpycatyo-collab, @Angroys

将课程翻译成您的语言

作为我们推动机器学习普及化使命的一部分，我们非常希望课程能够提供更多的语言版本！如果您愿意帮助将课程翻译成您的语言，请按照以下步骤操作 🙏。

🗞️ 打开一个议题

首先，前往本仓库的Issues页面，查看是否已有人为您的语言提交了议题。如果没有，请点击“New issue”按钮，选择“Translation template”来创建一个新的议题。

议题创建完成后，请在评论区说明您希望参与翻译的章节，我们会将您的名字添加到列表中。

🗣 加入我们的 Discord 服务器

由于通过 GitHub 议题快速讨论翻译细节可能不太方便，我们在 Discord 服务器上为每种语言都设立了专门的频道。如果您想加入，请按照该频道中的说明操作 👉：https://discord.gg/JfAtkvEtRb

🍴 分支仓库

接下来，您需要分叉这个仓库。只需点击本仓库页面右上角的“Fork”按钮即可。

分叉完成后，您需要将文件克隆到本地以便编辑。可以使用 Git 克隆分叉后的仓库，命令如下：

git clone https://github.com/YOUR-USERNAME/course

📋 复制英文文件并使用新的语言代码重命名

课程文件组织在一个主目录下：

• chapters：包含课程的所有文本和代码片段。

您只需要复制 chapters/en 目录下的文件。首先导航到您的分叉仓库，然后运行以下命令：

cd ~/path/to/course
cp -r chapters/en/CHAPTER-NUMBER chapters/LANG-ID/CHAPTER-NUMBER

其中，“CHAPTER-NUMBER”是指您想要翻译的章节编号，“LANG-ID”应为 ISO 639-1 或 ISO 639-2 的语言代码——您可以参考这里的便捷表格。

✍️ 开始翻译

现在到了最有趣的部分——翻译文本！我们建议您首先翻译与您负责章节对应的 _toctree.yml 文件部分。该文件用于在网站上渲染目录，并提供 Colab 笔记本的链接。您只需修改 title 字段即可。例如，对于 Chapter 0，我们需要翻译的部分如下：

- title: 0. Setup # 翻译这一行！
  sections:
  - local: chapter0/1 # 不要更改这一行！
    title: Introduction # 翻译这一行！

🚨 请确保 _toctree.yml 文件中仅包含已翻译的章节！否则您将无法在网站或本地构建内容（详见下文）。

完成 _toctree.yml 文件的翻译后，您可以开始翻译与该章节相关的 MDX 文件。

🙋 如果您的语言尚未存在 _toctree.yml 文件，您可以直接从英文版复制一份，删除与您负责章节无关的部分。只需确保该文件位于 chapters/LANG-ID/ 目录中！

👷‍♂️ 在本地构建课程

当您对所做的更改感到满意时，可以通过安装我们用于 Hugging Face 所有文档构建的工具 doc-builder 来预览效果：

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/huggingface/doc-builder.git"

doc-builder preview course ./chapters/LANG-ID --not_python_module

如果 LANG-ID 的内容是部分的，请确保 _toctree.yml 仅引用 chapters/LANG-ID 中存在的文件。

如果预览启动但所有路由都返回 404 错误，这可能是 Python 包与 SvelteKit 模板之间的 doc-builder 本地版本不匹配所致：

python -m pip uninstall -y hf-doc-builder
python -m pip install "git+https://github.com/huggingface/doc-builder.git"

然后重新运行 doc-builder preview。

preview 命令在 Windows 上无法使用。

这将会在 http://localhost:5173/ 上构建并渲染课程。尽管在 Hugging Face 官网上内容看起来会更美观，但这一步仍然可以帮助您检查格式是否正确。

🚀 提交拉取请求

如果本地翻译效果良好，最后一步就是准备提交拉取请求。首先需要检查文件格式是否正确，可以运行以下命令：

pip install -r requirements.txt
make style

运行完毕后，提交所有更改，打开拉取请求，并标记 @lewtun 和 @stevhliu 进行审核。如果您还知道其他能审查翻译的母语人士，也可以一并标记他们以获得帮助。恭喜您，您已经完成了第一次翻译 🥳！

🚨 若要在网站上构建课程，请务必确认您的语言代码已存在于 .github 文件夹中的 build_documentation.yml 和 build_pr_documentation.yml 文件的 languages 字段中。如果不存在，请按字母顺序将其添加进去。

📔 Jupyter 笔记本

包含课程所有代码的 Jupyter 笔记本托管在 huggingface/notebooks 仓库中。如果您希望在本地生成这些笔记本，首先需要安装所需的依赖项：

python -m pip install -r requirements.txt

然后运行以下脚本：

python utils/generate_notebooks.py --output_dir nbs

该脚本会从各章节中提取所有代码片段，并将其保存为笔记本文件，存放在 nbs 文件夹中（默认会被 Git 忽略）。

✍️ 贡献新章节

注意：我们目前不接受社区提交的新章节。这些说明仅供 Hugging Face 的作者使用。

为课程添加新章节非常简单：

1. 在 chapters/en/chapterX 目录下创建一个新目录，其中 chapterX 是您想要添加的章节名称。
2. 为每个小节添加编号的 MDX 文件 sectionX.mdx。如果您需要插入图片，请将图片上传到 huggingface-course/documentation-images 仓库，并使用 HTML 图片语法，路径为 https://huggingface.co/datasets/huggingface-course/documentation-images/resolve/main/{langY}/{chapterX}/{your-image.png}。
3. 更新 _toctree.yml 文件，加入您的章节内容——这些信息将用于在网站上生成目录。如果您的小节同时涉及 transformers 库的 PyTorch 和 TensorFlow API，请务必在 colab 字段中分别提供两个 Colab 笔记本的链接。

如果您遇到困难，可以参考现有的章节，这通常能帮助您了解预期的语法格式。

当您对内容满意后，打开一个拉取请求，并标记 @lewtun 进行审核。我们建议将第一章的初稿作为一个单独的拉取请求提交——团队会在内部提供反馈并迭代完善内容 🤗！

部署到 hf.co/course（仅限 HF 工作人员）

课程内容通过触发 release 分支上的 GitHub CI 流水线，部署到 hf.co/course。要触发构建，首先从 main 分支创建一个新的分支，用于更新 release 分支的状态：

git checkout main
git checkout -b bump_release

接下来，解决 release 和 bump_release 分支之间的任何冲突。由于手动解决这些冲突比较繁琐，我们可以执行以下操作来接受最新的更改：

git checkout bump_release
git merge -s ours release

然后，推送 bump_release 分支，并针对 release 分支（而非 main）打开一个拉取请求。这里有一个示例 PR。当 CI 流水线显示绿色时，合并该 PR，这将触发 GitHub CI 构建新的课程内容。整个过程大约需要 10–15 分钟，之后最新更改将在 hf.co/course 上可见！

🙌 致谢

本仓库的结构和 README 受到精彩的 Advanced NLP with spaCy 课程的启发。

Hugging Face Course 快速上手指南

本指南旨在帮助中国开发者快速开始学习 Hugging Face 官方课程，掌握 Transformer 模型在自然语言处理（NLP）及其他领域的应用。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Windows、macOS 或 Linux 均可。
• Python 版本：推荐 Python 3.8 或更高版本。
• 前置知识：具备基础的 Python 编程能力，了解基本的机器学习概念更佳。
• 账号准备：建议注册一个 Hugging Face 账号，以便使用 Model Hub 和社区功能。

国内网络提示：由于 Hugging Face 服务器位于海外，国内访问可能较慢。建议在代码中配置国内镜像源或使用代理加速下载模型和数据集。

安装步骤

你需要安装 Hugging Face 生态系统的核心库。推荐使用 pip 进行安装。

1. 基础安装

安装 Transformers、Datasets、Tokenizers 和 Accelerate 库：

pip install transformers datasets tokenizers accelerate

2. 可选：使用国内镜像加速

如果下载速度较慢，可以使用清华大学或阿里云的 PyPI 镜像源：

pip install transformers datasets tokenizers accelerate -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 验证安装

运行以下 Python 代码验证是否安装成功：

from transformers import pipeline

# 测试加载一个简单的模型
classifier = pipeline("sentiment-analysis")
print(classifier("I love using Hugging Face!"))

基本使用

本课程的核心是通过实践学习。你可以直接访问中文版课程网站开始学习，或在本地克隆仓库查看源码。

方式一：在线学习（推荐）

直接访问 Hugging Face 中文课程页面，无需配置本地环境即可阅读教程并运行部分代码示例（通过 Google Colab 或 Spaces）：

• 中文课程地址：https://huggingface.co/course/zh-CN/chapter1/1

方式二：本地运行示例

以下是一个最简单的使用示例，展示如何使用 transformers 加载预训练模型进行文本分类（情感分析）：

from transformers import pipeline

# 初始化情感分析管道
# 首次运行会自动从 Hugging Face Hub 下载模型
# 国内用户若下载失败，可设置环境变量 HF_ENDPOINT=https://hf-mirror.com
classifier = pipeline("sentiment-analysis")

# 执行预测
result = classifier("这门课程非常实用，让我快速掌握了 Transformer！")

# 输出结果
print(result)
# 预期输出类似：[{'label': 'POSITIVE', 'score': 0.9998}]

进阶：加载中文模型

针对中文任务，可以指定具体的中文预训练模型：

from transformers import AutoTokenizer, AutoModelForSequenceClassification, pipeline

model_name = "bert-base-chinese" # 或者使用其他中文模型，如 "hfl/chinese-roberta-wwm-ext"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

classifier = pipeline("sentiment-analysis", model=model, tokenizer=tokenizer)
print(classifier("人工智能技术正在改变世界"))

现在你已经准备好了环境并运行了第一个示例，接下来请前往中文课程网站系统性地学习后续章节。