[翻訳] Hugging Face transformersの推論パイプライン

[Pipelines for inference](https://huggingface.co/docs/transformers/pipeline_tutorial)の翻訳です。

:::note warn
本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。
:::

[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)によって、いかなる言語、コンピュータービジョン、スピーチ、マルチモーダルタスクにおける推論において、[Hub](https://huggingface.co/models)からのモデルの利用がシンプルになります。特定のモーダル性の経験がない、あるいはモデルの背後にあるコードに慣れていない場合でも、[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)を用いることで推論にモデルを活用することができます！このチュートリアルでは以下を学びます:

- 推論での[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)の使用。
- 特定のトークナイザー、モデルの使用。
- 音声、画像、マルチモーダルタスクにおける[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)の使用。

:::note
サポートされるタスクや使用できるパラメーターの完全なリストについては、[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)のドキュメントをご覧ください。
:::

# パイプラインの使用

それぞれのタスクが[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)に関連づけられると、全てのタスク固有のパイプラインを格納する汎用の[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)抽象化レイヤーの使用がよりシンプルになります。[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)は、ご自身のタスクにおける推論を可能とするデフォルトモデルと前処理クラスを自動でロードします。

1. [pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)の作成と、推論タスクの指定からスタートします:

    ```py:Python
    from transformers import pipeline
    
    generator = pipeline(task="automatic-speech-recognition")
    ```

1. [pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)に入力テキストを引き渡します:

    ```py:Python
    generator("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で[最もダウンロードされている自動スピーチ認識モデル](https://huggingface.co/models?pipeline_tag=automatic-speech-recognition&sort=downloads)のいくつかをチェックします。[openai/whisper\-large](https://huggingface.co/openai/whisper-large)をトライしてみましょう:

```py:Python
generator = pipeline(model="openai/whisper-large")
generator("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.'}
```

より正確な結果になりました！別の言語、ご自身の領域に特化したモデルなど、Hubでモデルをチェックすることを強くお勧めします。他のものよりもフィットする、特定のケースに対応できるのかを確認するために、ブラウザから直接Hubでモデルをチェック、比較することができます。そして、ご自身のユースケースに適したモデルが見つからない場合には、いつでもご自身で[トレーニング](https://qiita.com/taka_yayoi/items/597c6b1c36abaf9c1b3c)をスタートすることができます！

複数の入力がある場合には、リストとして入力することができます:

```py:Python
generator(
    [
        "https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac",
        "https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/1.flac",
    ]
)
```

データセット全体に対して繰り返したい場合、あるいは、ウェブサーバーでの推論で活用したい場合には専用のドキュメントをご覧ください。

[Using pipelines on a dataset](https://huggingface.co/docs/transformers/pipeline_tutorial#using-pipelines-on-a-dataset)

[Using pipelines for a webserver](https://huggingface.co/docs/transformers/pipeline_webserver)

# パラメーター

[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)は数多くのパラメーターをサポートしています。いくつかはタスク固有で、いくつかは全てのパイプラインで共通です。通常、好きな場所でパラメーターを指定することができます:

```py:Python
generator = pipeline(model="openai/whisper-large", my_parameter=1)
out = generator(...)  # This will use `my_parameter=1`.
out = generator(..., my_parameter=2)  # This will override and use `my_parameter=2`.
out = generator(...)  # This will go back to using `my_parameter=1`.
```

重要な3つのパラメーターをチェックしましょう:

## デバイス

`device=n`を設定すると、パイプラインは自動で指定されたデバイスにモデルを配置します。これは、PyTorchであろうがTensorflowであろうが動作します。

```py:Python
generator = pipeline(model="openai/whisper-large", device=0)
```

モデルが単一GPUでは大きすぎる場合、🤗 [Accelerate](https://huggingface.co/docs/accelerate)がモデルの重みのロード方法、格納方法を自動で判断するように、`device_map="auto"`を設定することができます。

```py:Python
#!pip install accelerate
generator = pipeline(model="openai/whisper-large", device_map="auto")
```

`device_map="auto"`を指定する際、`pipeline`のインスタンスを作成する際の引数`device=device`の指定は不要であることに注意してください。予想しない挙動をする場合があります！

## バッチサイズ

デフォルトでは、[こちら](https://huggingface.co/docs/transformers/main_classes/pipelines#pipeline-batching)で説明している理由からパイプラインはバッチの推論を行いません。理由は、バッチ処理が必ずしも高速ではないこと、あるケースでは非常に遅くなってしまうことです。

しかし、ご自身のユースケースで問題ない場合には、活用することができます:

```py:Python
generator = pipeline(model="openai/whisper-large", device=0, batch_size=2)
audio_filenames = [f"audio_{i}.flac" for i in range(10)]
texts = generator(audio_filenames)
```

これは、指定された10の音声ファイルに対してパイプラインを実行しますが、追加のコードを必要とすることなしに、(バッチがより有効である可能性が高いGPU上の)モデルに2つのサイズのバッチを引き渡します。アウトプットは、バッチ処理を行わない際に受け取るものと常に一致しなくてはなりません。これは、パイプラインの高速化だけの役に立つ手法であることを意味します。

また、パイプラインはバッチ処理の複雑性のいくつかを軽減し、いくつかのパイプランにおいては、モデルによって処理されるように(長い音声ファイルなどの)単一のアイテムを複数のパーツにまとめる必要があります。パイプラインはあなたのために、この[チャンクパッチ処理](https://huggingface.co/docs/transformers/main_classes/pipelines#pipeline-chunk-batching)を実行します。

## タスク固有のパラメーター

全てのタスクでは、あなたがジョブを完了できるように、追加の柔軟性とオプションを提供するタスク固有のパラメーターを提供します。例えば、[transformers\.AutomaticSpeechRecognitionPipeline\.call\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.AutomaticSpeechRecognitionPipeline.__call__)メソッドは動画にキャプションをつける役に立つであろう`return_timestamps`パラメーターを持っています:

```py:Python
# Not using whisper, as it cannot provide timestamps.
generator = pipeline(model="facebook/wav2vec2-large-960h-lv60-self", return_timestamps="word")
generator("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
```

```
{'text': 'I HAVE A DREAM BUT ONE DAY THIS NATION WILL RISE UP AND LIVE OUT THE TRUE MEANING OF ITS CREED', 'chunks': [{'text': 'I', 'timestamp': (1.22, 1.24)}, {'text': 'HAVE', 'timestamp': (1.42, 1.58)}, {'text': 'A', 'timestamp': (1.66, 1.68)}, {'text': 'DREAM', 'timestamp': (1.76, 2.14)}, {'text': 'BUT', 'timestamp': (3.68, 3.8)}, {'text': 'ONE', 'timestamp': (3.94, 4.06)}, {'text': 'DAY', 'timestamp': (4.16, 4.3)}, {'text': 'THIS', 'timestamp': (6.36, 6.54)}, {'text': 'NATION', 'timestamp': (6.68, 7.1)}, {'text': 'WILL', 'timestamp': (7.32, 7.56)}, {'text': 'RISE', 'timestamp': (7.8, 8.26)}, {'text': 'UP', 'timestamp': (8.38, 8.48)}, {'text': 'AND', 'timestamp': (10.08, 10.18)}, {'text': 'LIVE', 'timestamp': (10.26, 10.48)}, {'text': 'OUT', 'timestamp': (10.58, 10.7)}, {'text': 'THE', 'timestamp': (10.82, 10.9)}, {'text': 'TRUE', 'timestamp': (10.98, 11.18)}, {'text': 'MEANING', 'timestamp': (11.26, 11.58)}, {'text': 'OF', 'timestamp': (11.66, 11.7)}, {'text': 'ITS', 'timestamp': (11.76, 11.88)}, {'text': 'CREED', 'timestamp': (12.0, 12.38)}]}
```

見てわかるように、モデルはテキストを推定するとともに、文の中で単語が**いつ**発音されたのかをアウトプットします。

それぞれのタスクで使用できるパラメーターは多数ありますので、ピンとくるものを見つけ出すにはタスクごとのAPIリファレンスをチェックしてください！例えば、[AutomaticSpeechRecognitionPipeline](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.AutomaticSpeechRecognitionPipeline)には、モデル自身では多くの場合で取り扱いができない非常に長い音声ファイル(例えば、映画全体や数時間の動画にキャプションをつける)を取り扱う際に役立つ`chunk_length_s`パラメーターがあります。

必要なパラメーターが見つからない場合には、ぜひ[リクエスト](https://github.com/huggingface/transformers/issues/new?assignees=&labels=feature&template=feature-request.yml)してください！

# データセットにパイプラインを使用

また、大規模データセットに対してパイプラインを実行することもできます。推奨の最も簡単な方法はイテレーターを用いることです:

```py:Python
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](https://pytorch.org/docs/stable/data.html#torch.utils.data.DataLoader)を活用しています)。これは、データセット全体にメモリーを割り当てる必要がなく、GPUに可能な限り高速にデータを投入できるので重要なこととなります。

バッチ処理によって高速化される場合があるので、ここで`batch_size`パラメーターのチューニングをトライすることは有用です。

データセットに対するイテレーションの最も簡単な方法は、単に🤗 [Datasets](https://github.com/huggingface/datasets/)からロードするというものです:

```py:Python
# 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)
```

# ウェブサーバーにパイプラインを使用

:::note
推論エンジンの構築は専用のページが必要となる複雑なトピックです。
:::

[Link](https://huggingface.co/docs/transformers/pipeline_webserver)

# ビジョンパイプライン

ビジョンタスクでの[pipeline\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)の活用は実際のところ同じです。

分類器にタスクを指定し、画像を入力します。画像はリンクや画像に対するローカルパスとなります。例えば、以下に示している猫の種類はなんでしょうか？
![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg)

```py:Python
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\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)の活用も同じです。

```py:Python
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\(\)](https://huggingface.co/docs/transformers/v4.29.1/en/main_classes/pipelines#transformers.pipeline)は1つ以上のモーダルをサポートしています。例えば、ビジュアル質問回答(VQA)タスクではテキストと画像を組み合わせます。お好きな画像リンクと、画像に対する質問を使用することができます。画像は、画像へのURLあるいはローカルパスとなります。

例えば、こちらの[invoice image](https://huggingface.co/spaces/impira/docquery/resolve/2359223c1837a7587402bda0f2643382a6eefeab/invoice.png)を使用します:

```py:Python
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}]
```

:::note
上のサンプルを実行するには、🤗 Transformersに加えて[pytesseract](https://pypi.org/project/pytesseract/)をインストールする必要があります:

```
sudo apt install -y tesseract-ocr
pip install pytesseract
```
:::

# 大規模モデルに対する🤗 `accelerate`と`pipeline`の活用

🤗 `accelerate`を用いることで、大規模モデルに対して容易に`pipeline`を実行することができます！最初に`pip install accelerate`で`accelerate`をインストールするようにしてください。

最初に`device_map="auto"`を用いてモデルをロードします！このサンプルでは、`facebook/opt-1.3b`を使います。

```py:Python
# 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-bitでロードされたモデルを引き渡すことができます。

```py:Python
# 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)
```

BLOOMのように大規模モデルのロードをサポートしている任意のHugging Faceモデルで`checkpoint`を置き換えることができることに注意してください！