Pipeline

Pipeline, Hugging Face Hub'daki herhangi bir modelle çeşitli makine öğrenme görevleri için hazır olarak kullanılabilen basit ama güçlü bir çıkarım API'sidir.

Görevinize göre Pipeline’ı, toplantı notlarını transkribe etmek için otomatik konuşma tanıma (ASR) hattına zaman damgaları ekleme gibi görev özel parametrelerle özelleştirin. Pipeline, çıkarımı hızlandırmak ve bellek tasarrufu sağlamak için GPU, Apple Silicon ve yarım hassasiyetli ağırlıkları destekler.

Transformers'da iki pipeline sınıfı bulunur: genel amaçlı Pipeline ve TextGenerationPipeline gibi birçok görev özelinde pipeline. Bu bireysel pipeline'ları, Pipeline içindeki task parametresine görev tanımlayıcısını ayarlayarak yükleyebilirsiniz. Her pipeline'ın görev tanımlayıcısını API belgelerinde bulabilirsiniz.

Her görev, varsayılan olarak önceden eğitilmiş bir model ve ön işleyici kullanacak şekilde yapılandırılmıştır; ancak farklı bir model kullanmak isterseniz bunu model parametresiyle geçersiz kılabilirsiniz.

Örneğin, TextGenerationPipeline'i Gemma 2 ile kullanmak için task="text-generation" ve model="google/gemma-2-2b" değerlerini ayarlayın.

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b")
pipeline("the secret to baking a really good cake is ")
[{'generated_text': 'the secret to baking a really good cake is 1. the right ingredients 2. the'}]

Birden fazla girdiniz varsa, bunları bir liste olarak iletin.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device=device)
pipeline(["the secret to baking a really good cake is ", "a baguette is "])
[[{'generated_text': 'the secret to baking a really good cake is 1. the right ingredients 2. the'}],
 [{'generated_text': 'a baguette is 100% bread.\n\na baguette is 100%'}]]

Bu rehberde Pipeline tanıtılacak, özellikleri gösterilecek ve çeşitli parametrelerinin nasıl yapılandırılacağı açıklanacaktır.

Görevler

Pipeline, farklı modalitelerdeki birçok makine öğrenmesi göreviyle uyumludur. Pipeline'a uygun bir girdi iletin; kalan işi o halleder.

Farklı görevler ve modaliteler için Pipeline kullanımına dair bazı örnekler aşağıda verilmiştir.

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.'}

from transformers import pipeline

pipeline = pipeline(task="image-classification", model="google/vit-base-patch16-224")
pipeline(images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg")
[{'label': 'lynx, catamount', 'score': 0.43350091576576233},
 {'label': 'cougar, puma, catamount, mountain lion, painter, panther, Felis concolor',
  'score': 0.034796204417943954},
 {'label': 'snow leopard, ounce, Panthera uncia',
  'score': 0.03240183740854263},
 {'label': 'Egyptian cat', 'score': 0.02394474856555462},
 {'label': 'tiger cat', 'score': 0.02288915030658245}]

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'}]

Parametreler

En azından Pipeline, bir görev tanımlayıcısı, bir model ve uygun girdi gerektirir. Ancak, görevlere özgü parametrelerden performans optimizasyonuna kadar pipeline yapılandırmak için birçok parametre mevcuttur.

Bu bölüm, daha önemli bazı parametrelere giriş yapmanızı sağlar.

Cihaz

Pipeline, GPU, CPU, Apple Silicon ve daha fazlası dahil olmak üzere birçok donanım türüyle uyumludur. Donanım türünü device parametresiyle yapılandırın. Varsayılan olarak, device ayarlanmadığında Pipeline, modeli otomatik olarak ilk kullanılabilir hızlandırıcıya (CUDA GPU, Apple Silicon MPS, XPU, …) yerleştirir ve yalnızca hiçbiri kullanılamıyorsa CPU'ya geri döner. Çalışmayı CPU üzerinde zorlamak için device="cpu" geçin.

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device=0)
pipeline("the secret to baking a really good cake is ")

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device_map="auto")
pipeline("the secret to baking a really good cake is ")

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device="mps")
pipeline("the secret to baking a really good cake is ")

Toplu çıkarım

Pipeline, batch_size parametresiyle girdi partilerini de işleyebilir. Parti çıkarımı hızı artırabilir, özellikle GPU üzerinde, ancak bu garanti edilmez. Donanım, veri ve modelin kendisi gibi diğer değişkenler, parti çıkarımının hızı iyileştirip iyileştirmeyeceğini etkileyebilir. Bu nedenle, parti çıkarımı varsayılan olarak devre dışıdır.

Aşağıdaki örnekte, 4 giriş olduğunda ve batch_size değeri 2 olarak ayarlandığında, Pipeline modele her seferinde 2 girişlik bir parti iletir.

from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

pipeline = pipeline(task="text-generation", model="google/gemma-2-2b", device=device, batch_size=2)
pipeline(["the secret to baking a really good cake is", "a baguette is", "paris is the", "hotdogs are"])
[[{'generated_text': 'the secret to baking a really good cake is to use a good cake mix.\n\ni’'}],
 [{'generated_text': 'a baguette is'}],
 [{'generated_text': 'paris is the most beautiful city in the world.\n\ni’ve been to paris 3'}],
 [{'generated_text': 'hotdogs are a staple of the american diet. they are a great source of protein and can'}]]

Batch inference için bir diğer iyi kullanım senaryosu, Pipeline içinde veri akışıdır.

from transformers import pipeline
from accelerate import Accelerator
from transformers.pipelines.pt_utils import KeyDataset
import datasets

device = Accelerator().device

# KeyDataset is a utility that returns the item in the dict returned by the dataset
dataset = load_dataset("stanfordnlp/imdb", name="plain_text", split="unsupervised")
pipeline = pipeline(task="text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english", device=device)
for out in pipeline(KeyDataset(dataset, "text"), batch_size=8, truncation="only_first"):
    print(out)

Toplu çıkarımın performansı iyileştirmeye yardımcı olup olmadığını belirlerken aşağıdaki genel kılavuz kurallarını göz önünde bulundurun.

1. Kesin olarak bilmenin tek yolu, modelinizde, verilerinizde ve donanımınızda performansı ölçmektir.
2. Gecikme kısıtlıysa (örneğin canlı bir çıkarım ürünü) çıkarımı toplu (batch) olarak yapmayın.
3. CPU kullanıyorsanız çıkarımı toplu (batch) olarak yapmayın.
4. Verilerinizin sequence_length değerini bilmiyorsanız çıkarımı toplu (batch) olarak çalıştırmayın. Performansı ölçün, sequence_length değerine kademeli olarak eklemeler yapın ve başarısızlıklardan kurtulmak için bellek dışı (OOM) kontrolleri ekleyin.
5. sequence_length değeri düzenliyse toplu çıkarım (batch inference) yapın ve bir OOM hatası alana kadar değeri artırmaya devam edin. GPU ne kadar büyükse, toplu çıkarım o kadar faydalı olur.
6. Toplu çıkarım yapmaya karar verirseniz, OOM hatalarını yönetebildiğinizden emin olun.

Görev özel parametreler

Pipeline, her bir görev hattının desteklediği tüm parametreleri kabul eder. Kullanılabilir parametre türlerini görmek için her bir görev hattını incelemeyi unutmayın. Kullanım senaryonuza faydalı olabilecek bir parametreyi bulamıyorsanız, lütfen talep etmek için bir GitHub issue açmaktan çekinmeyin!

Aşağıdaki örnekler, kullanılabilir görev özel parametrelerinden bazılarını göstermektedir.

from transformers import pipeline

pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline(audio="https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac", return_timestamps="word")
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.',
 'chunks': [{'text': ' I', 'timestamp': (0.0, 1.1)},
  {'text': ' have', 'timestamp': (1.1, 1.44)},
  {'text': ' a', 'timestamp': (1.44, 1.62)},
  {'text': ' dream', 'timestamp': (1.62, 1.92)},
  {'text': ' that', 'timestamp': (1.92, 3.7)},
  {'text': ' one', 'timestamp': (3.7, 3.88)},
  {'text': ' day', 'timestamp': (3.88, 4.24)},
  {'text': ' this', 'timestamp': (4.24, 5.82)},
  {'text': ' nation', 'timestamp': (5.82, 6.78)},
  {'text': ' will', 'timestamp': (6.78, 7.36)},
  {'text': ' rise', 'timestamp': (7.36, 7.88)},
  {'text': ' up', 'timestamp': (7.88, 8.46)},
  {'text': ' and', 'timestamp': (8.46, 9.2)},
  {'text': ' live', 'timestamp': (9.2, 10.34)},
  {'text': ' out', 'timestamp': (10.34, 10.58)},
  {'text': ' the', 'timestamp': (10.58, 10.8)},
  {'text': ' true', 'timestamp': (10.8, 11.04)},
  {'text': ' meaning', 'timestamp': (11.04, 11.4)},
  {'text': ' of', 'timestamp': (11.4, 11.64)},
  {'text': ' its', 'timestamp': (11.64, 11.8)},
  {'text': ' creed.', 'timestamp': (11.8, 12.3)}]}

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="openai-community/gpt2")
pipeline("the secret to baking a good cake is", num_return_sequences=4, return_full_text=False)
[{'generated_text': ' how easy it is for me to do it with my hands. You must not go nuts, or the cake is going to fall out.'},
 {'generated_text': ' to prepare the cake before baking. The key is to find the right type of icing to use and that icing makes an amazing frosting cake.\n\nFor a good icing cake, we give you the basics'},
 {'generated_text': " to remember to soak it in enough water and don't worry about it sticking to the wall. In the meantime, you could remove the top of the cake and let it dry out with a paper towel.\n"},
 {'generated_text': ' the best time to turn off the oven and let it stand 30 minutes. After 30 minutes, stir and bake a cake in a pan until fully moist.\n\nRemove the cake from the heat for about 12'}]

Parça toplu işleme

Verileri parçalar halinde işlemek zorunda olduğunuz bazı durumlar vardır.

• bazı veri türlerinde, tek bir girdinin (örneğin, gerçekten uzun bir ses dosyasının) işlenebilmesi için birden fazla parçaya bölünmesi gerekebilir
• sıfır atıflı sınıflandırma veya soru-cevap gibi bazı görevlerde, tek bir girdi birden çok ileri geçiş gerektirebilir ve bu durum batch_size parametresiyle ilgili sorunlara yol açabilir

ChunkPipeline sınıfı bu kullanım senaryolarını ele almak üzere tasarlanmıştır. Her iki pipeline sınıfı da aynı şekilde kullanılır; ancak ChunkPipeline toplu işlemleri (batching) otomatik olarak yönetebildiğinden, girdilerinizin tetiklediği ileri geçiş (forward pass) sayısıyla uğraşmanıza gerek kalmaz. Bunun yerine, batch_size değerini girdilerden bağımsız olarak optimize edebilirsiniz.

Aşağıdaki örnek, bunun Pipeline'den nasıl farklılaştığını göstermektedir.

# ChunkPipeline
all_model_outputs = []
for preprocessed in pipeline.preprocess(inputs):
    model_outputs = pipeline.model_forward(preprocessed)
    all_model_outputs.append(model_outputs)
outputs =pipeline.postprocess(all_model_outputs)

# Pipeline
preprocessed = pipeline.preprocess(inputs)
model_outputs = pipeline.forward(preprocessed)
outputs = pipeline.postprocess(model_outputs)

Büyük veri setleri

Büyük veri setleriyle çıkarım için doğrudan veri setinin kendisi üzerinde yineleyebilirsiniz. Bu, tüm veri seti için belleğin hemen ayrılmamasını sağlar ve partileri kendinizin oluşturmasıyla ilgili endişelenmenize gerek kalmaz. Performansı iyileştirip iyileştirmeyeceğini görmek için batch_size parametresiyle Batch inference deneyin.

from transformers.pipelines.pt_utils import KeyDataset
from transformers import pipeline
from accelerate import Accelerator
from datasets import load_dataset

device = Accelerator().device

dataset = load_dataset("stanfordnlp/imdb", name="plain_text", split="unsupervised")
pipeline = pipeline(task="text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english", device=device)
for out in pipeline(KeyDataset(dataset, "text"), batch_size=8, truncation="only_first"):
    print(out)

Büyük veri setlerinde Pipeline ile çıkarım yapmanın diğer yolları arasında bir iteratör veya üreteç kullanmak yer alır.

def data():
    for i in range(1000):
        yield f"My example {i}"

pipeline = pipeline(model="openai-community/gpt2", device=0)
generated_characters = 0
for out in pipeline(data()):
    generated_characters += len(out[0]["generated_text"])

Büyük modeller

Accelerate, Pipeline ile büyük modelleri çalıştırmak için birkaç optimizasyon sağlar. Önce Accelerate'in yüklü olduğundan emin olun.

!pip install -U accelerate

device_map="auto" ayarı, modelin önce en hızlı cihazlara (GPU'lar) ve varsa daha yavaş diğer cihazlara (CPU, sabit disk) dağıtılmasını otomatik olarak gerçekleştirmek için kullanışlıdır.

Pipeline, yarı hassasiyetli ağırlıkları (torch.float16) destekler; bu, önemli ölçüde daha hızlı çalışmayı ve bellek tasarrufu sağlamayı mümkün kılar. Çoğu model için, özellikle de daha büyük modeller için performans kaybı ihmal edilebilir düzeydedir. Donanımınız destekliyorsa, daha geniş bir aralık için bunun yerine torch.bfloat16'yı etkinleştirebilirsiniz.

Girdiler içsel olarak torch.float16 türüne dönüştürülür ve bu özellik yalnızca PyTorch altyapısına sahip modellerde çalışır.

Son olarak, Pipeline bellek kullanımını daha da azaltmak için kuantize edilmiş modelleri de kabul eder. Önce bitsandbytes kütüphanesinin yüklü olduğundan emin olun ve ardından pipeline'da model_kwargs içine quantization_config ekleyin.

import torch
from transformers import pipeline, BitsAndBytesConfig

pipeline = pipeline(model="google/gemma-7b", dtype=torch.bfloat16, device_map="auto", model_kwargs={"quantization_config": BitsAndBytesConfig(load_in_8bit=True)})
pipeline("the secret to baking a good cake is ")
[{'generated_text': 'the secret to baking a good cake is 1. the right ingredients 2. the right'}]