Transformers 4.37 中文文档（一）（2）https://developer.aliyun.com/article/1565781
安装
为您正在使用的任何深度学习库安装🤗 Transformers，设置您的缓存，并可选择配置🤗 Transformers 以离线运行。
🤗 Transformers 在 Python 3.6+、PyTorch 1.1.0+、TensorFlow 2.0+和 Flax 上进行了测试。按照下面的安装说明为您正在使用的深度学习库安装：
- PyTorch安装说明。
- TensorFlow 2.0安装说明。
- Flax安装说明。
使用 pip 安装
您应该在virtual environment中安装🤗 Transformers。如果您不熟悉 Python 虚拟环境，请查看这个guide。虚拟环境使得管理不同项目更容易，并避免依赖项之间的兼容性问题。
首先在项目目录中创建一个虚拟环境：
python -m venv .env
激活虚拟环境。在 Linux 和 MacOs 上：
source .env/bin/activate
在 Windows 上激活虚拟环境
.env/Scripts/activate
现在您可以使用以下命令安装🤗 Transformers：
pip install transformers
仅支持 CPU 的情况下，您可以方便地在一行中安装🤗 Transformers 和一个深度学习库。例如，使用以下命令安装🤗 Transformers 和 PyTorch：
pip install 'transformers[torch]'
🤗 Transformers 和 TensorFlow 2.0：
pip install 'transformers[tf-cpu]'
M1 / ARM 用户
在安装 TensorFLow 2.0 之前，您需要安装以下内容
brew install cmake brew install pkg-config
🤗 Transformers 和 Flax：
pip install 'transformers[flax]'
最后，通过运行以下命令检查🤗 Transformers 是否已正确安装。它将下载一个预训练模型：
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('we love you'))"
然后打印标签和分数：
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
从源代码安装
使用以下命令从源代码安装🤗 Transformers：
pip install git+https://github.com/huggingface/transformers
此命令安装最新的stable版本而不是最新的main版本。main版本对于保持与最新发展保持最新是有用的。例如，如果自上次官方发布以来修复了错误但尚未推出新版本。但是，这意味着main版本可能不总是稳定的。我们努力保持main版本的运行，并且大多数问题通常在几个小时或一天内解决。如果遇到问题，请打开一个Issue，以便我们更快地解决！
通过运行以下命令检查🤗 Transformers 是否已正确安装：
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('I love you'))"
可编辑安装
如果您想要，您将需要一个可编辑的安装：
- 使用源代码的
main版本。 - 为🤗 Transformers 做出贡献并需要测试代码更改。
克隆存储库并使用以下命令安装🤗 Transformers：
git clone https://github.com/huggingface/transformers.git cd transformers pip install -e .
这些命令将链接您克隆存储库的文件夹和您的 Python 库路径。现在 Python 将在您克隆到的文件夹中查找，除了正常的库路径。例如，如果您的 Python 包通常安装在~/anaconda3/envs/main/lib/python3.7/site-packages/中，Python 还将搜索您克隆到的文件夹：~/transformers/。
如果要继续使用该库，必须保留transformers文件夹。
现在您可以使用以下命令轻松将克隆更新到最新版本的🤗 Transformers：
cd ~/transformers/ git pull
您的 Python 环境将在下一次运行时找到🤗 Transformers 的main版本。
使用 conda 安装
从 conda 频道conda-forge安装：
conda install conda-forge::transformers
缓存设置
预训练模型将被下载并在~/.cache/huggingface/hub中本地缓存。这是由 shell 环境变量TRANSFORMERS_CACHE给出的默认目录。在 Windows 上，默认目录由C:\Users\username\.cache\huggingface\hub给出。您可以更改下面显示的 shell 环境变量 - 以优先顺序列出 - 以指定不同的缓存目录：
- Shell 环境变量（默认）：
HUGGINGFACE_HUB_CACHE或TRANSFORMERS_CACHE。 - Shell 环境变量：
HF_HOME。 - Shell 环境变量：
XDG_CACHE_HOME+/huggingface。
🤗 Transformers 将使用 shell 环境变量PYTORCH_TRANSFORMERS_CACHE或PYTORCH_PRETRAINED_BERT_CACHE，如果您来自此库的早期版本并设置了这些环境变量，除非您指定 shell 环境变量TRANSFORMERS_CACHE。
离线模式
通过设置环境变量TRANSFORMERS_OFFLINE=1在防火墙或离线环境中运行🤗 Transformers，并使用本地缓存文件。
通过环境变量HF_DATASETS_OFFLINE=1将🤗 Datasets添加到您的离线训练工作流程。
HF_DATASETS_OFFLINE=1 TRANSFORMERS_OFFLINE=1 \ python examples/pytorch/translation/run_translation.py --model_name_or_path t5-small --dataset_name wmt16 --dataset_config ro-en ...
此脚本应该可以在不挂起或等待超时的情况下运行，因为它不会尝试从 Hub 下载模型。
您还可以通过local_files_only参数在每个 from_pretrained()调用中绕过从 Hub 加载模型。当设置为True时，只加载本地文件：
from transformers import T5Model model = T5Model.from_pretrained("./path/to/local/directory", local_files_only=True)
获取模型和分词器以离线使用
另一种离线使用🤗 Transformers 的选项是提前下载文件，然后在需要离线使用时指向它们的本地路径。有三种方法可以做到这一点：
- 通过点击↓图标在Model Hub上的用户界面下载文件。
- 使用 PreTrainedModel.from_pretrained()和 PreTrainedModel.save_pretrained()工作流程：
- 使用 PreTrainedModel.from_pretrained()提前下载您的文件：
>>> from transformers import AutoTokenizer, AutoModelForSeq2SeqLM >>> tokenizer = AutoTokenizer.from_pretrained("bigscience/T0_3B") >>> model = AutoModelForSeq2SeqLM.from_pretrained("bigscience/T0_3B")
- 使用 PreTrainedModel.save_pretrained()将文件保存到指定目录：
>>> tokenizer.save_pretrained("./your/path/bigscience_t0") >>> model.save_pretrained("./your/path/bigscience_t0")
- 现在当您离线时，通过从指定目录重新加载您的文件使用 PreTrainedModel.from_pretrained()：
>>> tokenizer = AutoTokenizer.from_pretrained("./your/path/bigscience_t0") >>> model = AutoModel.from_pretrained("./your/path/bigscience_t0")
- 使用huggingface_hub库以编程方式下载文件：
- 在您的虚拟环境中安装
huggingface_hub库：
python -m pip install huggingface_hub
- 使用
hf_hub_download函数将文件下载到特定路径。例如，以下命令将从T0模型下载config.json文件到您想要的路径：
>>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="bigscience/T0_3B", filename="config.json", cache_dir="./your/path/bigscience_t0")
一旦您的文件被下载并本地缓存，指定它的本地路径以加载和使用它：
>>> from transformers import AutoConfig >>> config = AutoConfig.from_pretrained("./your/path/bigscience_t0/config.json")
查看如何从 Hub 下载文件部分，了解有关下载存储在 Hub 上的文件的更多详细信息。
教程
用于推断的管道
原始文本：
huggingface.co/docs/transformers/v4.37.2/en/pipeline_tutorial
pipeline()使得在任何语言、计算机视觉、语音和多模态任务上使用 Hub 中的任何模型进行推断变得简单。即使您没有使用特定模态的经验或不熟悉模型背后的代码，您仍然可以使用 pipeline()进行推断！本教程将教您：
- 用于推断的 pipeline()。
- 使用特定的分词器或模型。
- 为音频、视觉和多模态任务使用 pipeline()。
查看 pipeline()文档，了解支持的任务和可用参数的完整列表。
管道用法
虽然每个任务都有一个相关的 pipeline()，但使用包含所有特定任务管道的通用 pipeline()抽象更简单。pipeline()会自动加载默认模型和适用于您任务的推断预处理类。让我们以使用 pipeline()进行自动语音识别（ASR）或语音转文本为例。
- 首先创建一个 pipeline()，并指定推断任务：
>>> from transformers import pipeline >>> transcriber = pipeline(task="automatic-speech-recognition")
- 将您的输入传递给 pipeline()。在语音识别的情况下，这是一个音频输入文件：
>>> transcriber("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac") {'text': 'I HAVE A DREAM BUT ONE DAY THIS NATION WILL RISE UP LIVE UP THE TRUE MEANING OF ITS TREES'}
不是您想要的结果？查看 Hub 上一些最受欢迎的自动语音识别模型，看看是否可以获得更好的转录。
让我们尝试来自 OpenAI 的Whisper large-v2模型。Whisper 比 Wav2Vec2 晚发布了 2 年，训练数据接近 10 倍。因此，它在大多数下游基准测试中击败了 Wav2Vec2。它还具有预测标点和大小写的附加好处，而这两者在 Wav2Vec2 中都不可能。
Wav2Vec2。
让我们在这里尝试一下，看看它的表现如何：
>>> transcriber = pipeline(model="openai/whisper-large-v2") >>> transcriber("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.'}
现在这个结果看起来更准确了！要深入比较 Wav2Vec2 和 Whisper，请参考音频变换器课程。我们真的鼓励您查看 Hub 中不同语言的模型、专门针对您领域的模型等。您可以直接从 Hub 在浏览器上查看和比较模型结果，看看它是否比其他模型更适合或更好地处理边缘情况。如果您找不到适用于您用例的模型，您始终可以开始训练您自己的模型！
如果您有多个输入，可以将输入作为列表传递：
transcriber( [ "https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac", "https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/1.flac", ] )
管道对于实验很有用，因为从一个模型切换到另一个模型很简单；然而，有一些方法可以优化它们以处理比实验更大的工作量。查看以下指南，深入探讨如何迭代整个数据集或在 web 服务器中使用管道：文档中的：
- 在数据集上使用管道
- 在 web 服务器上使用管道
参数
pipeline()支持许多参数；一些是任务特定的，一些是所有管道通用的。一般来说，您可以在任何地方指定参数：
transcriber = pipeline(model="openai/whisper-large-v2", my_parameter=1) out = transcriber(...) # This will use `my_parameter=1`. out = transcriber(..., my_parameter=2) # This will override and use `my_parameter=2`. out = transcriber(...) # This will go back to using `my_parameter=1`.
让我们看看 3 个重要的参数：
设备
如果您使用device=n，管道会自动将模型放在指定的设备上。无论您使用 PyTorch 还是 Tensorflow，这都可以工作。
transcriber = pipeline(model="openai/whisper-large-v2", device=0)
如果模型对单个 GPU 来说太大，并且您使用的是 PyTorch，您可以设置device_map="auto"来自动确定如何加载和存储模型权重。使用device_map参数需要 🤗 Accelerate 软件包：
pip install --upgrade accelerate
以下代码会自动在设备之间加载和存储模型权重：
transcriber = pipeline(model="openai/whisper-large-v2", device_map="auto")
请注意，如果传递了device_map="auto"，在实例化您的pipeline时无需添加参数device=device，否则可能会遇到一些意外行为！
批处理大小
默认情况下，管道不会批量推理，原因在这里有详细解释。原因是批处理不一定更快，在某些情况下实际上可能会更慢。
但如果在您的使用案例中有效，您可以使用：
transcriber = pipeline(model="openai/whisper-large-v2", device=0, batch_size=2) audio_filenames = [f"https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/{i}.flac" for i in range(1, 5)] texts = transcriber(audio_filenames)
这会在提供的 4 个音频文件上运行管道，但会将它们分批传递给模型（模型在 GPU 上，批处理更有可能有所帮助），而无需您进一步编写任何代码。输出应始终与没有批处理时收到的结果相匹配。这只是一种帮助您从管道中获得更快速度的方法。
管道还可以减轻一些批处理的复杂性，因为对于某些管道，单个项目（如长音频文件）需要被分成多个部分才能被模型处理。管道会为您执行这种块批处理。
任务特定参数
所有任务都提供任务特定参数，这些参数允许额外的灵活性和选项，帮助您完成工作。例如，transformers.AutomaticSpeechRecognitionPipeline.call()方法有一个return_timestamps参数，对于为视频添加字幕听起来很有希望：
>>> transcriber = pipeline(model="openai/whisper-large-v2", return_timestamps=True) >>> transcriber("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.', 'chunks': [{'timestamp': (0.0, 11.88), 'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its'}, {'timestamp': (11.88, 12.38), 'text': ' creed.'}]}
正如您所看到的，模型推断了文本，并且还输出了各个句子的发音时间。
每个任务都有许多可用的参数，因此请查看每个任务的 API 参考，看看您可以调整哪些参数！例如，AutomaticSpeechRecognitionPipeline 有一个chunk_length_s参数，对于处理非常长的音频文件（例如，为整部电影或长达一小时的视频添加字幕）非常有帮助，这是模型通常无法独立处理的：
>>> transcriber = pipeline(model="openai/whisper-large-v2", chunk_length_s=30, return_timestamps=True) >>> transcriber("https://huggingface.co/datasets/sanchit-gandhi/librispeech_long/resolve/main/audio.wav") {'text': " Chapter 16\. I might have told you of the beginning of this liaison in a few lines, but I wanted you to see every step by which we came. I, too, agree to whatever Marguerite wished, Marguerite to be unable to live apart from me. It was the day after the evening...
如果找不到一个真正有帮助的参数，请随时请求！
在数据集上使用管道
管道还可以在大型数据集上运行推理。我们建议的最简单方法是使用迭代器：
def data(): for i in range(1000): yield f"My example {i}" pipe = pipeline(model="gpt2", device=0) generated_characters = 0 for out in pipe(data()): generated_characters += len(out[0]["generated_text"])
迭代器data()会产生每个结果，管道会自动识别输入是可迭代的，并在继续在 GPU 上处理数据的同时开始获取数据（这在底层使用DataLoader）。这很重要，因为您不必为整个数据集分配内存，可以尽可能快地将数据馈送到 GPU。
由于批处理可能加快速度，尝试调整这里的batch_size参数可能会有用。
迭代数据集的最简单方法就是从 🤗 Datasets 加载一个：
# KeyDataset is a util that will just output the item we're interested in. from transformers.pipelines.pt_utils import KeyDataset from datasets import load_dataset pipe = pipeline(model="hf-internal-testing/tiny-random-wav2vec2", device=0) dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation[:10]") for out in pipe(KeyDataset(dataset, "audio")): print(out)
在 web 服务器上使用管道
创建推理引擎是一个复杂的主题，值得有自己的页面。
链接
视觉管道
对于视觉任务使用 pipeline()几乎是相同的。
指定您的任务并将图像传递给分类器。图像可以是链接，本地路径或 base64 编码的图像。例如，下面显示了什么品种的猫？
>>> from transformers import pipeline >>> vision_classifier = pipeline(model="google/vit-base-patch16-224") >>> preds = vision_classifier( ... images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg" ... ) >>> preds = [{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds] >>> preds [{'score': 0.4335, 'label': 'lynx, catamount'}, {'score': 0.0348, 'label': 'cougar, puma, catamount, mountain lion, painter, panther, Felis concolor'}, {'score': 0.0324, 'label': 'snow leopard, ounce, Panthera uncia'}, {'score': 0.0239, 'label': 'Egyptian cat'}, {'score': 0.0229, 'label': 'tiger cat'}]
文本管道
对于 NLP 任务使用 pipeline()几乎是相同的。
>>> from transformers import pipeline >>> # This model is a `zero-shot-classification` model. >>> # It will classify text, except you are free to choose any label you might imagine >>> classifier = pipeline(model="facebook/bart-large-mnli") >>> classifier( ... "I have a problem with my iphone that needs to be resolved asap!!", ... candidate_labels=["urgent", "not urgent", "phone", "tablet", "computer"], ... ) {'sequence': 'I have a problem with my iphone that needs to be resolved asap!!', 'labels': ['urgent', 'phone', 'computer', 'not urgent', 'tablet'], 'scores': [0.504, 0.479, 0.013, 0.003, 0.002]}
多模态管道
pipeline()支持多种模态。例如，视觉问答（VQA）任务结合了文本和图像。随意使用您喜欢的任何图像链接和您想要询问有关图像的问题。图像可以是 URL 或图像的本地路径。
例如，如果您使用这个发票图像：
>>> from transformers import pipeline >>> vqa = pipeline(model="impira/layoutlm-document-qa") >>> vqa( ... image="https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png", ... question="What is the invoice number?", ... ) [{'score': 0.42515, 'answer': 'us-001', 'start': 16, 'end': 16}]
要运行上面的示例，您需要安装pytesseract以及🤗 Transformers：
sudo apt install -y tesseract-ocr pip install pytesseract
在大型模型上使用🤗加速器：
您可以轻松地在大型模型上使用🤗accelerate运行pipeline！首先确保您已经安装了accelerate和pip install accelerate。
首先使用device_map="auto"加载您的模型！我们将在示例中使用facebook/opt-1.3b。
# pip install accelerate import torch from transformers import pipeline pipe = pipeline(model="facebook/opt-1.3b", torch_dtype=torch.bfloat16, device_map="auto") output = pipe("This is a cool example!", do_sample=True, top_p=0.95)
如果安装了bitsandbytes并添加参数load_in_8bit=True，还可以传递 8 位加载的模型
# pip install accelerate bitsandbytes import torch from transformers import pipeline pipe = pipeline(model="facebook/opt-1.3b", device_map="auto", model_kwargs={"load_in_8bit": True}) output = pipe("This is a cool example!", do_sample=True, top_p=0.95)
请注意，您可以用支持大型模型加载的任何 Hugging Face 模型替换检查点，例如 BLOOM！
Transformers 4.37 中文文档（一）（4）https://developer.aliyun.com/article/1565783
