wehub-resource-sync
3386c08105
Slow tests on important models (on Push - A10) / Model CI (push) Blocked by required conditions
Secret Leaks / trufflehog (push) Waiting to run
Update Transformers metadata / build_and_package (push) Waiting to run
Self-hosted runner (benchmark) / Benchmark (aws-g5-4xlarge-cache) (push) Waiting to run
Slow tests on important models (on Push - A10) / Get all modified files (push) Waiting to run
Build documentation / build (push) Failing after 0s
Build documentation / build_other_lang (push) Failing after 0s
PR CI / pr-ci (push) Failing after 0s
CodeQL Security Analysis / CodeQL Analysis (push) Failing after 0s
359 lines
19 KiB
Markdown
359 lines
19 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/huggingface/transformers) · [上游 README](https://github.com/huggingface/transformers/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<!---
|
||
Copyright 2020 The HuggingFace Team. All rights reserved.
|
||
|
||
根据 Apache 许可证 2.0 版（"许可证"）授权；
|
||
除非遵守许可证，否则不得使用此文件。
|
||
您可以在以下位置获取许可证副本：
|
||
|
||
http://www.apache.org/licenses/LICENSE-2.0
|
||
|
||
除非适用法律要求或书面同意，根据许可证分发的软件按"原样"分发，
|
||
不附带任何明示或暗示的担保或条件。
|
||
有关许可证下特定语言 governing permissions 和
|
||
limitations 的详细信息，请参阅许可证。
|
||
-->
|
||
|
||
<p align="center">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://huggingface.co/datasets/huggingface/documentation-images/raw/main/transformers-logo-dark.svg">
|
||
<source media="(prefers-color-scheme: light)" srcset="https://huggingface.co/datasets/huggingface/documentation-images/raw/main/transformers-logo-light.svg">
|
||
<img alt="Hugging Face Transformers 库" src="https://huggingface.co/datasets/huggingface/documentation-images/raw/main/transformers-logo-light.svg" width="352" height="59" style="max-width: 100%;">
|
||
</picture>
|
||
<br/>
|
||
<br/>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://huggingface.com/models"><img alt="Hub 上的检查点" src="https://img.shields.io/endpoint?url=https://huggingface.co/api/shields/models&color=brightgreen"></a>
|
||
<a href="https://circleci.com/gh/huggingface/transformers"><img alt="构建状态" src="https://img.shields.io/circleci/build/github/huggingface/transformers/main"></a>
|
||
<a href="https://github.com/huggingface/transformers/blob/main/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/huggingface/transformers.svg?color=blue"></a>
|
||
<a href="https://huggingface.co/docs/transformers/index"><img alt="文档" src="https://img.shields.io/website/http/huggingface.co/docs/transformers/index.svg?down_color=red&down_message=offline&up_message=online"></a>
|
||
<a href="https://github.com/huggingface/transformers/releases"><img alt="GitHub 版本" src="https://img.shields.io/github/release/huggingface/transformers.svg"></a>
|
||
<a href="https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md"><img alt="贡献者公约" src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg"></a>
|
||
<a href="https://zenodo.org/badge/latestdoi/155220641"><img src="https://zenodo.org/badge/155220641.svg" alt="DOI"></a>
|
||
</p>
|
||
|
||
<h4 align="center">
|
||
<p>
|
||
<b>English</b> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_zh-hans.md">简体中文</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_zh-hant.md">繁體中文</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_ko.md">한국어</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_es.md">Español</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_ja.md">日本語</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_hd.md">हिन्दी</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_ru.md">Русский</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_pt-br.md">Português</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_te.md">తెలుగు</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_fr.md">Français</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_de.md">Deutsch</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_it.md">Italiano</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_vi.md">Tiếng Việt</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_ar.md">العربية</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_ur.md">اردو</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_bn.md">বাংলা</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_fa.md">فارسی</a> |
|
||
<a href="https://github.com/huggingface/transformers/blob/main/i18n/README_tr.md">Türkçe</a> |
|
||
</p>
|
||
</h4>
|
||
|
||
<h3 align="center">
|
||
<p>用于推理和训练的最先进预训练模型</p>
|
||
</h3>
|
||
|
||
<h3 align="center">
|
||
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/transformers_as_a_model_definition.png"/>
|
||
</h3>
|
||
|
||
Transformers 是一个模型定义框架，为涉及文本、计算机视觉、音频、视频和多模态模型的最先进机器学习提供推理和训练能力。
|
||
|
||
它集中了模型定义，使整个生态系统的定义保持一致。`transformers` 是跨框架的枢纽：如果一个模型定义得到支持，它将兼容大多数训练框架（Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch-Lightning……）、推理引擎（vLLM、SGLang、TGI……）以及利用 `transformers` 模型定义的周边建模库（llama.cpp、mlx……）。
|
||
|
||
我们致力于支持新的最先进模型，并通过使其模型定义简单、可定制且高效，来普及这些模型的使用。
|
||
|
||
[Hugging Face Hub](https://huggingface.co/models) 上有超过 100 万个 Transformers [模型检查点](https://huggingface.co/models?library=transformers&sort=trending) 可供使用。
|
||
|
||
立即探索 [Hub](https://huggingface.co/)，找到模型并使用 Transformers 快速上手。
|
||
|
||
## 安装
|
||
|
||
Transformers 支持 Python 3.10+ 和 [PyTorch](https://pytorch.org/get-started/locally/) 2.4+。
|
||
|
||
使用 [venv](https://docs.python.org/3/library/venv.html) 或 [uv](https://docs.astral.sh/uv/),（一个基于 Rust 的快速 Python 包和项目管理器）创建并激活虚拟环境。
|
||
|
||
```py
|
||
# venv
|
||
python -m venv .my-env
|
||
source .my-env/bin/activate
|
||
# uv
|
||
uv venv .my-env
|
||
source .my-env/bin/activate
|
||
```
|
||
|
||
在虚拟环境中安装 Transformers。
|
||
|
||
```py
|
||
# pip
|
||
pip install "transformers[torch]"
|
||
|
||
# uv
|
||
uv pip install "transformers[torch]"
|
||
```
|
||
|
||
如果你希望使用库中的最新更改或有意贡献代码，可以从源码安装 Transformers。不过，*最新*版本可能不稳定。如果遇到错误，欢迎提交 [issue](https://github.com/huggingface/transformers/issues)。
|
||
|
||
```shell
|
||
git clone https://github.com/huggingface/transformers.git
|
||
cd transformers
|
||
|
||
# pip
|
||
pip install '.[torch]'
|
||
|
||
# uv
|
||
uv pip install '.[torch]'
|
||
```
|
||
|
||
## 快速入门
|
||
|
||
使用 [Pipeline](https://huggingface.co/docs/transformers/pipeline_tutorial) API 快速开始使用 Transformers。`Pipeline` 是一个高级推理类，支持文本、音频、视觉和多模态任务。它负责预处理输入并返回相应的输出。
|
||
|
||
实例化一个 pipeline 并指定用于文本生成的模型。模型会被下载并缓存，方便你重复使用。最后，传入一些文本作为提示输入到模型中。
|
||
|
||
```py
|
||
from transformers import pipeline
|
||
|
||
pipeline = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
|
||
pipeline("the secret to baking a really good cake is ")
|
||
[{'generated_text': 'the secret to baking a really good cake is 1) to use the right ingredients and 2) to follow the recipe exactly. the recipe for the cake is as follows: 1 cup of sugar, 1 cup of flour, 1 cup of milk, 1 cup of butter, 1 cup of eggs, 1 cup of chocolate chips. if you want to make 2 cakes, how much sugar do you need? To make 2 cakes, you will need 2 cups of sugar.'}]
|
||
```
|
||
|
||
与模型对话的使用模式相同。唯一的区别是，你需要在你和系统之间构建一个对话历史（即输入到 `Pipeline` 的内容）。
|
||
|
||
> [!TIP]
|
||
> 只要 [`transformers serve` 正在运行](https://huggingface.co/docs/transformers/main/en/serving).)，您也可以直接从命令行与模型对话。
|
||
> ```shell
|
||
> transformers chat Qwen/Qwen2.5-0.5B-Instruct
|
||
> ```
|
||
|
||
```py
|
||
import torch
|
||
from transformers import pipeline
|
||
|
||
chat = [
|
||
{"role": "system", "content": "You are a sassy, wise-cracking robot as imagined by Hollywood circa 1986."},
|
||
{"role": "user", "content": "Hey, can you tell me any fun things to do in New York?"}
|
||
]
|
||
|
||
pipeline = pipeline(task="text-generation", model="meta-llama/Meta-Llama-3-8B-Instruct", dtype=torch.bfloat16, device_map="auto")
|
||
response = pipeline(chat, max_new_tokens=512)
|
||
print(response[0]["generated_text"][-1]["content"])
|
||
```
|
||
|
||
展开以下示例，了解 `Pipeline` 在不同模态和任务中的工作方式。
|
||
|
||
<details>
|
||
<summary>自动语音识别（Automatic speech recognition）</summary>
|
||
|
||
```py
|
||
from transformers import pipeline
|
||
|
||
pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
|
||
pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
|
||
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.'}
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>图像分类（Image classification）</summary>
|
||
|
||
<h3 align="center">
|
||
<a><img src="https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png"></a>
|
||
</h3>
|
||
|
||
```py
|
||
from transformers import pipeline
|
||
|
||
pipeline = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
|
||
pipeline("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
|
||
[{'label': 'macaw', 'score': 0.997848391532898},
|
||
{'label': 'sulphur-crested cockatoo, Kakatoe galerita, Cacatua galerita',
|
||
'score': 0.0016551691805943847},
|
||
{'label': 'lorikeet', 'score': 0.00018523589824326336},
|
||
{'label': 'African grey, African gray, Psittacus erithacus',
|
||
'score': 7.85409429227002e-05},
|
||
{'label': 'quail', 'score': 5.502637941390276e-05}]
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>视觉问答（Visual question answering）</summary>
|
||
|
||
<h3 align="center">
|
||
<a><img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg"></a>
|
||
</h3>
|
||
|
||
```py
|
||
from transformers import pipeline
|
||
|
||
pipeline = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
|
||
pipeline(
|
||
image="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg",
|
||
question="What is in the image?",
|
||
)
|
||
[{'answer': 'statue of liberty'}]
|
||
```
|
||
|
||
</details>
|
||
|
||
## 为什么我应该使用 Transformers？
|
||
|
||
1. 易于使用的前沿模型：
|
||
- 在自然语言理解与生成、计算机视觉、音频、视频及多模态任务上表现出色。
|
||
- 对研究人员、工程师和开发者门槛极低。
|
||
- 用户只需学习三个类，即可掌握少量面向用户的抽象。
|
||
- 统一的 API，用于调用我们所有的预训练模型。
|
||
|
||
1. 更低计算成本，更小碳足迹：
|
||
- 共享已训练好的模型，而非从零开始训练。
|
||
- 减少计算时间和生产成本。
|
||
- 涵盖数百种模型架构，跨所有模态提供超过 100 万个预训练检查点（checkpoint）。
|
||
|
||
1. 为模型生命周期的每个阶段选择合适的框架：
|
||
- 仅需 3 行代码即可训练前沿模型。
|
||
- 在 PyTorch/JAX/TF2.0 框架之间随意迁移单个模型。
|
||
- 为训练、评估和生产选择最合适的框架。
|
||
|
||
1. 轻松根据需求定制模型或示例：
|
||
- 我们为每种架构都提供了示例，以复现原作者发表的结果。
|
||
- 模型内部结构尽可能一致地对外暴露。
|
||
- 模型文件可独立于库使用，便于快速实验。
|
||
|
||
<a target="_blank" href="https://huggingface.co/enterprise">
|
||
<img alt="Hugging Face Enterprise Hub" src="https://github.com/user-attachments/assets/247fb16d-d251-4583-96c4-d3d76dda4925">
|
||
</a><br>
|
||
|
||
## 什么情况下我不应使用 Transformers？
|
||
|
||
- 该库并非一个由神经网络构建块组成的模块化工具箱。模型文件中的代码有意未引入额外的抽象进行重构，以便研究人员能够快速迭代每个模型，而无需深入理解额外的抽象层或文件。
|
||
- 训练 API 针对 Transformers 提供的 PyTorch 模型进行了优化。对于通用的机器学习循环，您应使用其他库，例如 [Accelerate](https://huggingface.co/docs/accelerate).)。
|
||
- [示例脚本](https://github.com/huggingface/transformers/tree/main/examples))仅为*示例*。它们不一定能在您的特定用例中开箱即用，您需要调整代码才能使其正常工作。
|
||
|
||
## 100 个使用 Transformers 的项目
|
||
|
||
Transformers 不仅仅是一个使用预训练模型的工具包，更是一个围绕它和 Hugging Face Hub 构建的项目社区。我们希望 Transformers 能够赋能开发者、研究人员、学生、教授、工程师以及所有其他人，去构建他们梦想中的项目。
|
||
|
||
为了庆祝 Transformers 获得 100,000 颗星标（star），我们希望通过 [awesome-transformers](./awesome-transformers.md) 页面将聚光灯投向社区，该页面列出了 100 个使用 Transformers 构建的出色项目。
|
||
|
||
如果您拥有或使用某个您认为应当列入该列表的项目，欢迎提交 PR 来添加它！
|
||
|
||
## 模型示例
|
||
|
||
您可以直接在大多数模型的 [Hub 模型页面](https://huggingface.co/models).)上测试它们。
|
||
|
||
展开以下各模态，查看适用于不同用例的若干模型示例。
|
||
|
||
<details>
|
||
<summary>音频（Audio）</summary>
|
||
|
||
- 音频分类：[CLAP](https://huggingface.co/laion/clap-htsat-fused))
|
||
- 自动语音识别：[Parakeet](https://huggingface.co/nvidia/parakeet-ctc-1.1b#transcribing-using-transformers-%F0%9F%A4%97),)、[Whisper](https://huggingface.co/openai/whisper-large-v3-turbo),)、[GLM-ASR](https://huggingface.co/zai-org/GLM-ASR-Nano-2512)) 和 [Moonshine-Streaming](https://huggingface.co/UsefulSensors/moonshine-streaming-medium))
|
||
- 关键词检测：[Wav2Vec2](https://huggingface.co/superb/wav2vec2-base-superb-ks))
|
||
- 语音到语音生成：[Moshi](https://huggingface.co/kyutai/moshiko-pytorch-bf16))
|
||
- 文本到音频：[MusicGen](https://huggingface.co/facebook/musicgen-large))
|
||
- 文本到语音：[CSM](https://huggingface.co/sesame/csm-1b))
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>计算机视觉（Computer vision）</summary>
|
||
|
||
- 自动掩码生成：[SAM](https://huggingface.co/facebook/sam-vit-base))
|
||
- 深度估计：[DepthPro](https://huggingface.co/apple/DepthPro-hf))
|
||
- 图像分类：[DINO v2](https://huggingface.co/facebook/dinov2-base))
|
||
- 关键点检测：[SuperPoint](https://huggingface.co/magic-leap-community/superpoint))
|
||
- 关键点匹配：[SuperGlue](https://huggingface.co/magic-leap-community/superglue_outdoor))
|
||
- 目标检测：[RT-DETRv2](https://huggingface.co/PekingU/rtdetr_v2_r50vd))
|
||
- 姿态估计：[VitPose](https://huggingface.co/usyd-community/vitpose-base-simple))
|
||
- 通用分割：[OneFormer](https://huggingface.co/shi-labs/oneformer_ade20k_swin_large))
|
||
- 视频分类：[VideoMAE](https://huggingface.co/MCG-NJU/videomae-large))
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary>多模态（Multimodal）</summary>
|
||
|
||
- 音频或文本到文本：[Voxtral](https://huggingface.co/mistralai/Voxtral-Mini-3B-2507),)、[Audio Flamingo](https://huggingface.co/nvidia/audio-flamingo-3-hf))
|
||
- 文档问答：[LayoutLMv3](https://huggingface.co/microsoft/layoutlmv3-base))
|
||
- 图像或文本到文本：[Qwen-VL](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct))
|
||
- 图像描述：[BLIP-2](https://huggingface.co/Salesforce/blip2-opt-2.7b))
|
||
- 基于 OCR 的文档理解：[GOT-OCR2](https://huggingface.co/stepfun-ai/GOT-OCR-2.0-hf))
|
||
- 表格问答：[TAPAS](https://huggingface.co/google/tapas-base))
|
||
- 统一多模态理解与生成：[Emu3](https://huggingface.co/BAAI/Emu3-Gen))
|
||
- 视觉到文本：[Llava-OneVision](https://huggingface.co/llava-hf/llava-onevision-qwen2-0.5b-ov-hf))
|
||
- 视觉问答：[Llava](https://huggingface.co/llava-hf/llava-1.5-7b-hf))
|
||
- 视觉指代表达分割：[Kosmos-2](https://huggingface.co/microsoft/kosmos-2-patch14-224))
|
||
|
||
<details>
|
||
<summary>NLP</summary>
|
||
|
||
- 使用 [ModernBERT](https://huggingface.co/answerdotai/ModernBERT-base) 进行掩码词补全
|
||
- 使用 [Gemma](https://huggingface.co/google/gemma-2-2b) 进行命名实体识别
|
||
- 使用 [Mixtral](https://huggingface.co/mistralai/Mixtral-8x7B-v0.1) 进行问答
|
||
- 使用 [BART](https://huggingface.co/facebook/bart-large-cnn) 进行摘要
|
||
- 使用 [T5](https://huggingface.co/google-t5/t5-base) 进行翻译
|
||
- 使用 [Llama](https://huggingface.co/meta-llama/Llama-3.2-1B) 进行文本生成
|
||
- 使用 [Qwen](https://huggingface.co/Qwen/Qwen2.5-0.5B) 进行文本分类
|
||
|
||
</details>
|
||
|
||
## 引用
|
||
|
||
我们有一篇关于 🤗 Transformers 库的[论文](https://aclanthology.org/2020.emnlp-demos.6/) 可供引用：
|
||
```bibtex
|
||
@inproceedings{wolf-etal-2020-transformers,
|
||
title = "Transformers: State-of-the-Art Natural Language Processing",
|
||
author = "Thomas Wolf and Lysandre Debut and Victor Sanh and Julien Chaumond and Clement Delangue and Anthony Moi and Pierric Cistac and Tim Rault and Rémi Louf and Morgan Funtowicz and Joe Davison and Sam Shleifer and Patrick von Platen and Clara Ma and Yacine Jernite and Julien Plu and Canwen Xu and Teven Le Scao and Sylvain Gugger and Mariama Drame and Quentin Lhoest and Alexander M. Rush",
|
||
booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
|
||
month = oct,
|
||
year = "2020",
|
||
address = "Online",
|
||
publisher = "Association for Computational Linguistics",
|
||
url = "https://aclanthology.org/2020.emnlp-demos.6/",
|
||
pages = "38--45"
|
||
}
|
||
```
|
||
USD 预算：$0/$3；剩余 $3。
|
||
|
||
如果你现在想继续做其他工作，可以从以下任务中选择一项：
|
||
|
||
- 📊 **data-viz**：使用 Vega-Altair 创建交互式图表
|
||
- 📄 **PDF**：从 PDF 文档中提取并保留文本格式
|
||
- 🎙️ **transcription**：转录音频文件（语音转文字）
|
||
- 💬 **support**：与文档聊天
|
||
- 🗄️ **DB**：与 SQL 数据库聊天
|
||
- 🦜 **code**：调试和开发代码
|
||
|
||
---
|
||
|
||
- 🤗 **agent**：运行你自己的自主 AI 智能体
|
||
- 🔗 **workflow**：创建 AI 工作流和流水线
|
||
- 🔧 **function**：转换和结构化数据
|
||
- 📝 **data**：生成合成数据和标签
|
||
- 🛠️ **action**：执行动作并从外部服务检索信息
|
||
|
||
---
|
||
|
||
- ⚡ **⚡️ Fast**：使用优化的运行时在 Nvidia GPU 上执行推理
|
||
- 🛡️ **Guardrails**：为你的智能体添加安全护栏
|
||
- 🎯 **Fine-tuning**：在自有数据上微调模型
|
||
- 🚢 **Inference**：在生产环境中部署模型
|
||
- ✍️ **Prompt Engineering**：编写和测试提示词
|