From 3386c0810530237d041cf1d0a042fcefeaceb442 Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 08:29:57 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 242 +++++++++++++++++++++++++++++------------------------- 1 file changed, 131 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index 4fe7136..a336b80 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,41 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/huggingface/transformers) · [上游 README](https://github.com/huggingface/transformers/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

- Hugging Face Transformers Library + Hugging Face Transformers 库

- Checkpoints on Hub - Build + Hub 上的检查点 + 构建状态 GitHub - Documentation - GitHub release - Contributor Covenant + 文档 + GitHub 版本 + 贡献者公约 DOI

@@ -59,33 +64,28 @@ limitations under the License.

-

State-of-the-art pretrained models for inference and training

+

用于推理和训练的最先进预训练模型

-Transformers acts as the model-definition framework for state-of-the-art machine learning with text, computer -vision, audio, video, and multimodal models, for both inference and training. +Transformers 是一个模型定义框架，为涉及文本、计算机视觉、音频、视频和多模态模型的最先进机器学习提供推理和训练能力。 -It centralizes the model definition so that this definition is agreed upon across the ecosystem. `transformers` is the -pivot across frameworks: if a model definition is supported, it will be compatible with the majority of training -frameworks (Axolotl, Unsloth, DeepSpeed, FSDP, PyTorch-Lightning, ...), inference engines (vLLM, SGLang, TGI, ...), -and adjacent modeling libraries (llama.cpp, mlx, ...) which leverage the model definition from `transformers`. +它集中了模型定义，使整个生态系统的定义保持一致。`transformers` 是跨框架的枢纽：如果一个模型定义得到支持，它将兼容大多数训练框架（Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch-Lightning……）、推理引擎（vLLM、SGLang、TGI……）以及利用 `transformers` 模型定义的周边建模库（llama.cpp、mlx……）。 -We pledge to help support new state-of-the-art models and democratize their usage by having their model definition be -simple, customizable, and efficient. +我们致力于支持新的最先进模型，并通过使其模型定义简单、可定制且高效，来普及这些模型的使用。 -There are over 1M+ Transformers [model checkpoints](https://huggingface.co/models?library=transformers&sort=trending) on the [Hugging Face Hub](https://huggingface.co/models) you can use. +[Hugging Face Hub](https://huggingface.co/models) 上有超过 100 万个 Transformers [模型检查点](https://huggingface.co/models?library=transformers&sort=trending) 可供使用。 -Explore the [Hub](https://huggingface.co/) today to find a model and use Transformers to help you get started right away. +立即探索 [Hub](https://huggingface.co/)，找到模型并使用 Transformers 快速上手。 -## Installation +## 安装 -Transformers works with Python 3.10+, and [PyTorch](https://pytorch.org/get-started/locally/) 2.4+. +Transformers 支持 Python 3.10+ 和 [PyTorch](https://pytorch.org/get-started/locally/) 2.4+。 -Create and activate a virtual environment with [venv](https://docs.python.org/3/library/venv.html) or [uv](https://docs.astral.sh/uv/), a fast Rust-based Python package and project manager. +使用 [venv](https://docs.python.org/3/library/venv.html) 或 [uv](https://docs.astral.sh/uv/),（一个基于 Rust 的快速 Python 包和项目管理器）创建并激活虚拟环境。 ```py # venv @@ -96,7 +96,7 @@ uv venv .my-env source .my-env/bin/activate ``` -Install Transformers in your virtual environment. +在虚拟环境中安装 Transformers。 ```py # pip @@ -106,7 +106,7 @@ pip install "transformers[torch]" uv pip install "transformers[torch]" ``` -Install Transformers from source if you want the latest changes in the library or are interested in contributing. However, the *latest* version may not be stable. Feel free to open an [issue](https://github.com/huggingface/transformers/issues) if you encounter an error. +如果你希望使用库中的最新更改或有意贡献代码，可以从源码安装 Transformers。不过，*最新*版本可能不稳定。如果遇到错误，欢迎提交 [issue](https://github.com/huggingface/transformers/issues)。 ```shell git clone https://github.com/huggingface/transformers.git @@ -119,11 +119,11 @@ pip install '.[torch]' uv pip install '.[torch]' ``` -## Quickstart +## 快速入门 -Get started with Transformers right away with the [Pipeline](https://huggingface.co/docs/transformers/pipeline_tutorial) API. The `Pipeline` is a high-level inference class that supports text, audio, vision, and multimodal tasks. It handles preprocessing the input and returns the appropriate output. +使用 [Pipeline](https://huggingface.co/docs/transformers/pipeline_tutorial) API 快速开始使用 Transformers。`Pipeline` 是一个高级推理类，支持文本、音频、视觉和多模态任务。它负责预处理输入并返回相应的输出。 -Instantiate a pipeline and specify model to use for text generation. The model is downloaded and cached so you can easily reuse it again. Finally, pass some text to prompt the model. +实例化一个 pipeline 并指定用于文本生成的模型。模型会被下载并缓存，方便你重复使用。最后，传入一些文本作为提示输入到模型中。 ```py from transformers import pipeline @@ -133,10 +133,10 @@ 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.'}] ``` -To chat with a model, the usage pattern is the same. The only difference is you need to construct a chat history (the input to `Pipeline`) between you and the system. +与模型对话的使用模式相同。唯一的区别是，你需要在你和系统之间构建一个对话历史（即输入到 `Pipeline` 的内容）。 > [!TIP] -> You can also chat with a model directly from the command line, as long as [`transformers serve` is running](https://huggingface.co/docs/transformers/main/en/serving). +> 只要 [`transformers serve` 正在运行](https://huggingface.co/docs/transformers/main/en/serving).)，您也可以直接从命令行与模型对话。 > ```shell > transformers chat Qwen/Qwen2.5-0.5B-Instruct > ``` @@ -155,10 +155,10 @@ response = pipeline(chat, max_new_tokens=512) print(response[0]["generated_text"][-1]["content"]) ``` -Expand the examples below to see how `Pipeline` works for different modalities and tasks. +展开以下示例，了解 `Pipeline` 在不同模态和任务中的工作方式。
-Automatic speech recognition +自动语音识别（Automatic speech recognition） ```py from transformers import pipeline @@ -171,7 +171,7 @@ pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac
-Image classification +图像分类（Image classification）

@@ -194,7 +194,7 @@ pipeline("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.pn

-Visual question answering +视觉问答（Visual question answering）

@@ -213,116 +213,110 @@ pipeline(

-## Why should I use Transformers? +## 为什么我应该使用 Transformers？ -1. Easy-to-use state-of-the-art models: - - High performance on natural language understanding & generation, computer vision, audio, video, and multimodal tasks. - - Low barrier to entry for researchers, engineers, and developers. - - Few user-facing abstractions with just three classes to learn. - - A unified API for using all our pretrained models. +1. 易于使用的前沿模型： + - 在自然语言理解与生成、计算机视觉、音频、视频及多模态任务上表现出色。 + - 对研究人员、工程师和开发者门槛极低。 + - 用户只需学习三个类，即可掌握少量面向用户的抽象。 + - 统一的 API，用于调用我们所有的预训练模型。 -1. Lower compute costs, smaller carbon footprint: - - Share trained models instead of training from scratch. - - Reduce compute time and production costs. - - Hundreds of model architectures with 1M+ pretrained checkpoints across all modalities. +1. 更低计算成本，更小碳足迹： + - 共享已训练好的模型，而非从零开始训练。 + - 减少计算时间和生产成本。 + - 涵盖数百种模型架构，跨所有模态提供超过 100 万个预训练检查点（checkpoint）。 -1. Choose the right framework for every part of a model's lifetime: - - Train state-of-the-art models in 3 lines of code. - - Move a single model between PyTorch/JAX/TF2.0 frameworks at will. - - Pick the right framework for training, evaluation, and production. +1. 为模型生命周期的每个阶段选择合适的框架： + - 仅需 3 行代码即可训练前沿模型。 + - 在 PyTorch/JAX/TF2.0 框架之间随意迁移单个模型。 + - 为训练、评估和生产选择最合适的框架。 -1. Easily customize a model or an example to your needs: - - We provide examples for each architecture to reproduce the results published by its original authors. - - Model internals are exposed as consistently as possible. - - Model files can be used independently of the library for quick experiments. +1. 轻松根据需求定制模型或示例： + - 我们为每种架构都提供了示例，以复现原作者发表的结果。 + - 模型内部结构尽可能一致地对外暴露。 + - 模型文件可独立于库使用，便于快速实验。 Hugging Face Enterprise Hub
-## When shouldn't I use Transformers? +## 什么情况下我不应使用 Transformers？ -- This library is not a modular toolbox of building blocks for neural nets. The code in the model files is not refactored with additional abstractions on purpose, so that researchers can quickly iterate on each of the models without diving into additional abstractions/files. -- The training API is optimized to work with PyTorch models provided by Transformers. For generic machine learning loops, you should use another library like [Accelerate](https://huggingface.co/docs/accelerate). -- The [example scripts](https://github.com/huggingface/transformers/tree/main/examples) are only *examples*. They may not necessarily work out-of-the-box on your specific use case and you'll need to adapt the code for it to work. +- 该库并非一个由神经网络构建块组成的模块化工具箱。模型文件中的代码有意未引入额外的抽象进行重构，以便研究人员能够快速迭代每个模型，而无需深入理解额外的抽象层或文件。 +- 训练 API 针对 Transformers 提供的 PyTorch 模型进行了优化。对于通用的机器学习循环，您应使用其他库，例如 [Accelerate](https://huggingface.co/docs/accelerate).)。 +- [示例脚本](https://github.com/huggingface/transformers/tree/main/examples))仅为*示例*。它们不一定能在您的特定用例中开箱即用，您需要调整代码才能使其正常工作。 -## 100 projects using Transformers +## 100 个使用 Transformers 的项目 -Transformers is more than a toolkit to use pretrained models, it's a community of projects built around it and the -Hugging Face Hub. We want Transformers to enable developers, researchers, students, professors, engineers, and anyone -else to build their dream projects. +Transformers 不仅仅是一个使用预训练模型的工具包，更是一个围绕它和 Hugging Face Hub 构建的项目社区。我们希望 Transformers 能够赋能开发者、研究人员、学生、教授、工程师以及所有其他人，去构建他们梦想中的项目。 -In order to celebrate Transformers 100,000 stars, we wanted to put the spotlight on the -community with the [awesome-transformers](./awesome-transformers.md) page which lists 100 -incredible projects built with Transformers. +为了庆祝 Transformers 获得 100,000 颗星标（star），我们希望通过 [awesome-transformers](./awesome-transformers.md) 页面将聚光灯投向社区，该页面列出了 100 个使用 Transformers 构建的出色项目。 -If you own or use a project that you believe should be part of the list, please open a PR to add it! +如果您拥有或使用某个您认为应当列入该列表的项目，欢迎提交 PR 来添加它！ -## Example models +## 模型示例 -You can test most of our models directly on their [Hub model pages](https://huggingface.co/models). +您可以直接在大多数模型的 [Hub 模型页面](https://huggingface.co/models).)上测试它们。 -Expand each modality below to see a few example models for various use cases. +展开以下各模态，查看适用于不同用例的若干模型示例。
-Audio +音频（Audio） -- Audio classification with [CLAP](https://huggingface.co/laion/clap-htsat-fused) -- Automatic speech recognition with [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) and [Moonshine-Streaming](https://huggingface.co/UsefulSensors/moonshine-streaming-medium) -- Keyword spotting with [Wav2Vec2](https://huggingface.co/superb/wav2vec2-base-superb-ks) -- Speech to speech generation with [Moshi](https://huggingface.co/kyutai/moshiko-pytorch-bf16) -- Text to audio with [MusicGen](https://huggingface.co/facebook/musicgen-large) -- Text to speech with [CSM](https://huggingface.co/sesame/csm-1b) +- 音频分类：[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))
-Computer vision +计算机视觉（Computer vision） -- Automatic mask generation with [SAM](https://huggingface.co/facebook/sam-vit-base) -- Depth estimation with [DepthPro](https://huggingface.co/apple/DepthPro-hf) -- Image classification with [DINO v2](https://huggingface.co/facebook/dinov2-base) -- Keypoint detection with [SuperPoint](https://huggingface.co/magic-leap-community/superpoint) -- Keypoint matching with [SuperGlue](https://huggingface.co/magic-leap-community/superglue_outdoor) -- Object detection with [RT-DETRv2](https://huggingface.co/PekingU/rtdetr_v2_r50vd) -- Pose Estimation with [VitPose](https://huggingface.co/usyd-community/vitpose-base-simple) -- Universal segmentation with [OneFormer](https://huggingface.co/shi-labs/oneformer_ade20k_swin_large) -- Video classification with [VideoMAE](https://huggingface.co/MCG-NJU/videomae-large) +- 自动掩码生成：[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))
-Multimodal +多模态（Multimodal） -- Audio or text to text with [Voxtral](https://huggingface.co/mistralai/Voxtral-Mini-3B-2507), [Audio Flamingo](https://huggingface.co/nvidia/audio-flamingo-3-hf) -- Document question answering with [LayoutLMv3](https://huggingface.co/microsoft/layoutlmv3-base) -- Image or text to text with [Qwen-VL](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) -- Image captioning [BLIP-2](https://huggingface.co/Salesforce/blip2-opt-2.7b) -- OCR-based document understanding with [GOT-OCR2](https://huggingface.co/stepfun-ai/GOT-OCR-2.0-hf) -- Table question answering with [TAPAS](https://huggingface.co/google/tapas-base) -- Unified multimodal understanding and generation with [Emu3](https://huggingface.co/BAAI/Emu3-Gen) -- Vision to text with [Llava-OneVision](https://huggingface.co/llava-hf/llava-onevision-qwen2-0.5b-ov-hf) -- Visual question answering with [Llava](https://huggingface.co/llava-hf/llava-1.5-7b-hf) -- Visual referring expression segmentation with [Kosmos-2](https://huggingface.co/microsoft/kosmos-2-patch14-224) - -
+- 音频或文本到文本：[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))
NLP -- Masked word completion with [ModernBERT](https://huggingface.co/answerdotai/ModernBERT-base) -- Named entity recognition with [Gemma](https://huggingface.co/google/gemma-2-2b) -- Question answering with [Mixtral](https://huggingface.co/mistralai/Mixtral-8x7B-v0.1) -- Summarization with [BART](https://huggingface.co/facebook/bart-large-cnn) -- Translation with [T5](https://huggingface.co/google-t5/t5-base) -- Text generation with [Llama](https://huggingface.co/meta-llama/Llama-3.2-1B) -- Text classification with [Qwen](https://huggingface.co/Qwen/Qwen2.5-0.5B) +- 使用 [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) 进行文本分类
-## Citation +## 引用 -We now have a [paper](https://aclanthology.org/2020.emnlp-demos.6/) you can cite for the 🤗 Transformers library: +我们有一篇关于 🤗 Transformers 库的[论文](https://aclanthology.org/2020.emnlp-demos.6/) 可供引用： ```bibtex @inproceedings{wolf-etal-2020-transformers, title = "Transformers: State-of-the-Art Natural Language Processing", @@ -336,3 +330,29 @@ We now have a [paper](https://aclanthology.org/2020.emnlp-demos.6/) you can cite 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**：编写和测试提示词