Pipelines

Purpose and Scope

Pipelines are the highest-level inference interface in Transformers. They solve the first problem most users have after installation: turning an input such as text, an image, audio, or multimodal content into a model prediction without manually loading every component, preparing tensors, running the model, and post-processing outputs. The official pipelines documentation describes them as objects that abstract most of the complex library code and expose a simple API for tasks such as named entity recognition, masked language modeling, sentiment analysis, feature extraction, and question answering.

Sources: docs/source/en/main_classes/pipelines.md

The central entry point is the generic pipeline factory. It is described as the most powerful pipeline object because it encapsulates the task-specific pipelines behind one creation pattern. In practice, a developer can either pass a task identifier, such as text-classification, or pass a model name from the Hugging Face Hub when that model already declares its task. The result is a callable object that accepts user inputs and returns task-shaped Python objects, for example a list of dictionaries containing labels and confidence scores for classification.

Sources: docs/source/en/main_classes/pipelines.md

Pipelines are intentionally different from lower-level model APIs. A pipeline is optimized for convenient inference, experimentation, demos, scripts, and straightforward batch processing. Lower-level APIs such as AutoModel, AutoTokenizer, model-specific classes, processors, and training utilities are better when you need precise tensor control, custom loss computation, modified generation loops, specialized preprocessing, or integration into a larger training loop. A good rule is to start with pipelines to validate the model and task, then move downward only when the pipeline’s task-specific parameters are not enough.

Sources: docs/source/en/main_classes/pipelines.md, docs/source/en/main_classes/backbones.md, docs/source/en/main_classes/callback.md

Relevant Source Files

• docs/source/en/main_classes/pipelines.md — primary English API documentation for pipeline, task-specific pipeline categories, single-item inference, list inputs, dataset iteration, generators, and batching guidance.
• docs/source/ja/main_classes/pipelines.md — Japanese localization of the same pipeline guide, including the dataset, generator, and batching sections used to confirm the reader-facing workflow is not English-only.
• docs/source/ko/main_classes/pipelines.md — Korean localization of the pipeline guide, preserving task categories and examples for list, dataset, generator, and batched inference.
• docs/source/zh/main_classes/pipelines.md — Chinese localization of the pipeline guide, including the explicit batching warning that batching may accelerate or slow down depending on hardware, data, and model.
• docs/source/en/main_classes/backbones.md — adjacent main-class documentation that illustrates where pipelines stop: backbones expose feature extraction components for higher-level computer vision systems rather than end-to-end task inference.
• docs/source/en/main_classes/callback.md — adjacent main-class documentation for training-loop callbacks, useful as a boundary marker because callbacks customize Trainer, not pipeline inference.

Core Abstraction and Task Coverage

The docs organize pipeline abstractions into two categories. First, pipeline is the generic wrapper that selects and configures the appropriate task pipeline. Second, there are task-specific pipelines grouped by audio, computer vision, natural language processing, and multimodal tasks. This matters when reading the API reference: most users instantiate through the generic function, while the task-specific pipeline classes define the behavior and options of individual tasks such as text generation, automatic speech recognition, image classification, visual question answering, or feature extraction.

Sources: docs/source/en/main_classes/pipelines.md

A minimal text classification call demonstrates the intended ergonomics. The user imports pipeline, creates pipe = pipeline("text-classification"), and calls pipe("This restaurant is awesome"). The returned value is already post-processed into labels and scores. If the user chooses a Hub model such as FacebookAI/roberta-large-mnli, the task can be omitted when the model metadata defines it. This keeps the common path short while still allowing deliberate model selection when the default task model is not appropriate.

Sources: docs/source/en/main_classes/pipelines.md

from transformers import pipeline
 
pipe = pipeline("text-classification")
pipe("This restaurant is awesome")
 
mnli = pipeline(model="FacebookAI/roberta-large-mnli")
mnli("This restaurant is awesome")

The localized pipeline documentation in Japanese, Korean, and Chinese mirrors this same conceptual model: pipelines are easy inference objects; the generic pipeline wraps task-specific pipelines; and task groups span audio, computer vision, natural language processing, and multimodal use cases. That consistency is useful for contributors and documentation maintainers because the pipeline page is not merely a code reference. It is also the canonical explanation that translated docs use to teach the same workflow across language editions.

Sources: docs/source/ja/main_classes/pipelines.md, docs/source/ko/main_classes/pipelines.md, docs/source/zh/main_classes/pipelines.md

Execution Flow

A pipeline call can be understood as a three-stage inference flow: input acceptance, model execution, and output formatting. The docs intentionally hide the internal details, but the examples show the shape of the public contract. A caller may pass a single item, a list of items, a dataset-backed iterator, or a generator. The pipeline owns the repetitive work of preprocessing each item, sending batches through the model when applicable, and returning task-specific output records. This is why pipelines are a good first abstraction for validating a model or building a quick inference script.

Sources: docs/source/en/main_classes/pipelines.md

For many inputs, the simplest option is passing a Python list. The output shape follows the task. Text classification returns one prediction per input sentence, while generation or multimodal tasks may return nested structures depending on their task-specific contract. Lists are convenient for small batches that already fit in memory. They are less ideal when the input collection is a full dataset, a queue, or an unbounded stream, because materializing everything before inference creates unnecessary memory pressure and removes opportunities for streaming.

Sources: docs/source/en/main_classes/pipelines.md

pipe = pipeline("text-classification")
pipe(["This restaurant is awesome", "This restaurant is awful"])

For full datasets, the docs recommend passing a dataset directly rather than allocating the entire dataset or writing a custom batching loop. The documented automatic speech recognition example loads superb with datasets.load_dataset, wraps the file column with KeyDataset, and iterates over pipe(KeyDataset(dataset, "file")). KeyDataset is described in the example as a PyTorch helper that returns only the selected key from each dataset item, while sentence-pair inputs should use KeyPairDataset. This pattern gives pipeline users streaming-style iteration without abandoning the high-level interface.

Sources: docs/source/en/main_classes/pipelines.md

Generators cover another common integration style: data may come from a database, a queue, or HTTP requests in a server. The docs show a generator that yields strings forever and then iterates over pipe(data()). The important caveat is that iterative generators cannot use num_workers > 1 to preprocess with multiple worker threads. You can still let one thread preprocess while the main process performs inference, but if preprocessing becomes the bottleneck, that is a signal to design a more explicit serving or data-loading architecture.

Sources: docs/source/en/main_classes/pipelines.md

Batching Behavior and Performance Tradeoffs

Batching is available for all pipelines when the pipeline uses streaming features, which the docs define as passing a list, a Dataset, or a generator. The user-facing control is batch_size, and task-specific preprocessing options such as truncation="only_first" can be supplied at call time. In the documented IMDb example, a text-classification pipeline runs on device=0, iterates over KeyDataset(dataset, "text"), and sends content to the model in batches of eight while producing the same logical predictions as the unbatched path.

Sources: docs/source/ko/main_classes/pipelines.md, docs/source/zh/main_classes/pipelines.md

from transformers import pipeline
from transformers.pipelines.pt_utils import KeyDataset
import datasets
 
dataset = datasets.load_dataset("stanfordnlp/imdb", name="plain_text", split="unsupervised")
pipe = pipeline("text-classification", device=0)
 
for out in pipe(KeyDataset(dataset, "text"), batch_size=8, truncation="only_first"):
    print(out)

The most important batching lesson in the pipeline docs is that batching is not automatically faster. The Chinese localization preserves the warning that batching can produce a 10x speedup or a 5x slowdown depending on hardware, data, and the actual model. Long, uneven sequence lengths can create padding overhead; small models may not benefit enough from larger batches; and CPU preprocessing can dominate runtime. Treat batch_size as a tunable parameter, not a universal optimization. Measure throughput and latency with realistic inputs before committing to a production setting.

Sources: docs/source/zh/main_classes/pipelines.md

Device selection is another practical dimension. Pipeline examples use device=0 for GPU execution, and the tutorial evidence describes GPU, Apple Silicon, and half-precision weights as acceleration and memory-saving options. In repository documentation terms, the pipeline page gives the high-level call patterns, while more specialized optimization pages should cover backend-specific tuning. For this page, the safe operating guidance is simple: use pipelines to prove the task and model, then benchmark batching, device placement, and input shape before scaling the workload.

Sources: docs/source/en/main_classes/pipelines.md

When to Move to Lower-Level APIs

Move below pipelines when the abstraction starts hiding something you must control. If you are building a computer vision system that needs intermediate feature maps rather than finished task predictions, the backbone documentation points to AutoBackbone, BackboneMixin, BackboneConfigMixin, TimmBackbone, and TimmBackboneConfig. Those classes are documented for feature extraction and output feature selection, not for the end-to-end task packaging that pipelines provide. That is a clear boundary: pipelines return user-facing predictions; backbones provide reusable model components for custom architectures.

Sources: docs/source/en/main_classes/backbones.md

Training is another boundary. The callback documentation describes callbacks as objects that customize the PyTorch Trainer loop, inspect TrainerState, and return TrainerControl decisions such as early stopping. It also states that callbacks are read-only apart from the control object, and deeper loop changes require subclassing Trainer. None of that belongs inside a pipeline, because pipelines are inference-oriented. If your work involves progress reporting, logging integrations, evaluation control, optimizer behavior, or custom loop semantics, use Trainer and callbacks rather than trying to stretch a pipeline into a training framework.

Sources: docs/source/en/main_classes/callback.md

Finally, move to lower-level APIs when you need custom preprocessing or post-processing that the task-specific pipeline cannot express. Pipelines expose many task parameters, but they are still designed around common task contracts. If your application requires custom token alignment, nonstandard model heads, special multimodal packing, manual attention masks, custom logits processing, or output schemas that differ from the built-in task, load the tokenizer or processor and model directly. Keep the pipeline example as a regression oracle: it shows what the standard task path produces before you introduce custom code.

Sources: docs/source/en/main_classes/pipelines.md

Compact API Reference

Next Steps

Start with pipeline whenever you need fast inference feedback: choose a task, optionally choose a Hub model, run one example, then try a list of representative inputs. If the input source is large, switch to a dataset iterator with KeyDataset; if the input source is dynamic, try a generator and remember the num_workers caveat. Before production use, benchmark batch_size, device placement, and realistic input distributions. If you need intermediate features, training-loop customization, or exact tensor control, continue with the pages on Auto classes, preprocessing, backbones, Trainer, generation, and inference optimization.

Sources: docs/source/en/main_classes/pipelines.md, docs/source/en/main_classes/backbones.md, docs/source/en/main_classes/callback.md