Pipelines
The pipelines are a great and easy way to use models for inference. These pipelines are objects that abstract most of the complex code from the library, offering a simple API dedicated to several tasks, including Named Entity Recognition, Masked Language Modeling, Sentiment Analysis, Feature Extraction and Question Answering. See the task summary for examples of use.
There are two categories of pipeline abstractions to be aware about:
- The pipeline() which is the most powerful object encapsulating all other pipelines.
- Task-specific pipelines are available for audio, computer vision, natural language processing, and multimodal tasks.
The pipeline abstraction
The pipeline abstraction is a wrapper around all the other available pipelines. It is instantiated as any other pipeline but can provide additional quality of life.
Simple call on one item:
>>> pipe = pipeline("text-classification")
>>> pipe("This restaurant is awesome")
[{'label': 'POSITIVE', 'score': 0.9998743534088135}]
If you want to use a specific model from the hub you can ignore the task if the model on the hub already defines it:
>>> pipe = pipeline(model="FacebookAI/roberta-large-mnli")
>>> pipe("This restaurant is awesome")
[{'label': 'NEUTRAL', 'score': 0.7313136458396912}]
To call a pipeline on many items, you can call it with a list.
>>> pipe = pipeline("text-classification")
>>> pipe(["This restaurant is awesome", "This restaurant is awful"])
[{'label': 'POSITIVE', 'score': 0.9998743534088135},
{'label': 'NEGATIVE', 'score': 0.9996669292449951}]
To iterate over full datasets it is recommended to use a dataset
directly. This means you don’t need to allocate
the whole dataset at once, nor do you need to do batching yourself. This should work just as fast as custom loops on
GPU. If it doesn’t don’t hesitate to create an issue.
import datasets
from transformers import pipeline
from transformers.pipelines.pt_utils import KeyDataset
from tqdm.auto import tqdm
pipe = pipeline("automatic-speech-recognition", model="facebook/wav2vec2-base-960h", device=0)
dataset = datasets.load_dataset("superb", name="asr", split="test")
# KeyDataset (only *pt*) will simply return the item in the dict returned by the dataset item
# as we're not interested in the *target* part of the dataset. For sentence pair use KeyPairDataset
for out in tqdm(pipe(KeyDataset(dataset, "file"))):
print(out)
# {"text": "NUMBER TEN FRESH NELLY IS WAITING ON YOU GOOD NIGHT HUSBAND"}
# {"text": ....}
# ....
For ease of use, a generator is also possible:
from transformers import pipeline
pipe = pipeline("text-classification")
def data():
while True:
# This could come from a dataset, a database, a queue or HTTP request
# in a server
# Caveat: because this is iterative, you cannot use `num_workers > 1` variable
# to use multiple threads to preprocess data. You can still have 1 thread that
# does the preprocessing while the main runs the big inference
yield "This is a test"
for out in pipe(data()):
print(out)
# {"text": "NUMBER TEN FRESH NELLY IS WAITING ON YOU GOOD NIGHT HUSBAND"}
# {"text": ....}
# ....
transformers.pipeline
< source >( task: str = None model: Union = None config: Union = None tokenizer: Union = None feature_extractor: Union = None image_processor: Union = None framework: Optional = None revision: Optional = None use_fast: bool = True token: Union = None device: Union = None device_map = None torch_dtype = None trust_remote_code: Optional = None model_kwargs: Dict = None pipeline_class: Optional = None **kwargs ) → Pipeline
Parameters
- task (
str
) — The task defining which pipeline will be returned. Currently accepted tasks are:"audio-classification"
: will return a AudioClassificationPipeline."automatic-speech-recognition"
: will return a AutomaticSpeechRecognitionPipeline."depth-estimation"
: will return a DepthEstimationPipeline."document-question-answering"
: will return a DocumentQuestionAnsweringPipeline."feature-extraction"
: will return a FeatureExtractionPipeline."fill-mask"
: will return a FillMaskPipeline:."image-classification"
: will return a ImageClassificationPipeline."image-feature-extraction"
: will return an ImageFeatureExtractionPipeline."image-segmentation"
: will return a ImageSegmentationPipeline."image-to-image"
: will return a ImageToImagePipeline."image-to-text"
: will return a ImageToTextPipeline."mask-generation"
: will return a MaskGenerationPipeline."object-detection"
: will return a ObjectDetectionPipeline."question-answering"
: will return a QuestionAnsweringPipeline."summarization"
: will return a SummarizationPipeline."table-question-answering"
: will return a TableQuestionAnsweringPipeline."text2text-generation"
: will return a Text2TextGenerationPipeline."text-classification"
(alias"sentiment-analysis"
available): will return a TextClassificationPipeline."text-generation"
: will return a TextGenerationPipeline:."text-to-audio"
(alias"text-to-speech"
available): will return a TextToAudioPipeline:."token-classification"
(alias"ner"
available): will return a TokenClassificationPipeline."translation"
: will return a TranslationPipeline."translation_xx_to_yy"
: will return a TranslationPipeline."video-classification"
: will return a VideoClassificationPipeline."visual-question-answering"
: will return a VisualQuestionAnsweringPipeline."zero-shot-classification"
: will return a ZeroShotClassificationPipeline."zero-shot-image-classification"
: will return a ZeroShotImageClassificationPipeline."zero-shot-audio-classification"
: will return a ZeroShotAudioClassificationPipeline."zero-shot-object-detection"
: will return a ZeroShotObjectDetectionPipeline.
- model (
str
or PreTrainedModel or TFPreTrainedModel, optional) — The model that will be used by the pipeline to make predictions. This can be a model identifier or an actual instance of a pretrained model inheriting from PreTrainedModel (for PyTorch) or TFPreTrainedModel (for TensorFlow).If not provided, the default for the
task
will be loaded. - config (
str
or PretrainedConfig, optional) — The configuration that will be used by the pipeline to instantiate the model. This can be a model identifier or an actual pretrained model configuration inheriting from PretrainedConfig.If not provided, the default configuration file for the requested model will be used. That means that if
model
is given, its default configuration will be used. However, ifmodel
is not supplied, thistask
’s default model’s config is used instead. - tokenizer (
str
or PreTrainedTokenizer, optional) — The tokenizer that will be used by the pipeline to encode data for the model. This can be a model identifier or an actual pretrained tokenizer inheriting from PreTrainedTokenizer.If not provided, the default tokenizer for the given
model
will be loaded (if it is a string). Ifmodel
is not specified or not a string, then the default tokenizer forconfig
is loaded (if it is a string). However, ifconfig
is also not given or not a string, then the default tokenizer for the giventask
will be loaded. - feature_extractor (
str
orPreTrainedFeatureExtractor
, optional) — The feature extractor that will be used by the pipeline to encode data for the model. This can be a model identifier or an actual pretrained feature extractor inheriting fromPreTrainedFeatureExtractor
.Feature extractors are used for non-NLP models, such as Speech or Vision models as well as multi-modal models. Multi-modal models will also require a tokenizer to be passed.
If not provided, the default feature extractor for the given
model
will be loaded (if it is a string). Ifmodel
is not specified or not a string, then the default feature extractor forconfig
is loaded (if it is a string). However, ifconfig
is also not given or not a string, then the default feature extractor for the giventask
will be loaded. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - revision (
str
, optional, defaults to"main"
) — When passing a task name or a string model identifier: The specific model version to use. It can be a branch name, a tag name, or a commit id, since we use a git-based system for storing models and other artifacts on huggingface.co, sorevision
can be any identifier allowed by git. - use_fast (
bool
, optional, defaults toTrue
) — Whether or not to use a Fast tokenizer if possible (a PreTrainedTokenizerFast). - use_auth_token (
str
or bool, optional) — The token to use as HTTP bearer authorization for remote files. IfTrue
, will use the token generated when runninghuggingface-cli login
(stored in~/.huggingface
). - device (
int
orstr
ortorch.device
) — Defines the device (e.g.,"cpu"
,"cuda:1"
,"mps"
, or a GPU ordinal rank like1
) on which this pipeline will be allocated. - device_map (
str
orDict[str, Union[int, str, torch.device]
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut). Whenaccelerate
library is present, setdevice_map="auto"
to compute the most optimizeddevice_map
automatically (see here for more information).Do not use
device_map
ANDdevice
at the same time as they will conflict - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
). - trust_remote_code (
bool
, optional, defaults toFalse
) — Whether or not to allow for custom code defined on the Hub in their own modeling, configuration, tokenization or even pipeline files. This option should only be set toTrue
for repositories you trust and in which you have read the code, as it will execute code present on the Hub on your local machine. - model_kwargs (
Dict[str, Any]
, optional) — Additional dictionary of keyword arguments passed along to the model’sfrom_pretrained(..., **model_kwargs)
function. - kwargs (
Dict[str, Any]
, optional) — Additional keyword arguments passed along to the specific pipeline init (see the documentation for the corresponding pipeline class for possible values).
Returns
A suitable pipeline for the task.
Utility factory method to build a Pipeline.
Pipelines are made of:
- A tokenizer in charge of mapping raw textual input to token.
- A model to make predictions from the inputs.
- Some (optional) post processing for enhancing model’s output.
Examples:
>>> from transformers import pipeline, AutoModelForTokenClassification, AutoTokenizer
>>> # Sentiment analysis pipeline
>>> analyzer = pipeline("sentiment-analysis")
>>> # Question answering pipeline, specifying the checkpoint identifier
>>> oracle = pipeline(
... "question-answering", model="distilbert/distilbert-base-cased-distilled-squad", tokenizer="google-bert/bert-base-cased"
... )
>>> # Named entity recognition pipeline, passing in a specific model and tokenizer
>>> model = AutoModelForTokenClassification.from_pretrained("dbmdz/bert-large-cased-finetuned-conll03-english")
>>> tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-cased")
>>> recognizer = pipeline("ner", model=model, tokenizer=tokenizer)
Pipeline batching
All pipelines can use batching. This will work
whenever the pipeline uses its streaming ability (so when passing lists or Dataset
or generator
).
from transformers import pipeline
from transformers.pipelines.pt_utils import KeyDataset
import datasets
dataset = datasets.load_dataset("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)
# [{'label': 'POSITIVE', 'score': 0.9998743534088135}]
# Exactly the same output as before, but the content are passed
# as batches to the model
However, this is not automatically a win for performance. It can be either a 10x speedup or 5x slowdown depending on hardware, data and the actual model being used.
Example where it’s mostly a speedup:
from transformers import pipeline
from torch.utils.data import Dataset
from tqdm.auto import tqdm
pipe = pipeline("text-classification", device=0)
class MyDataset(Dataset):
def __len__(self):
return 5000
def __getitem__(self, i):
return "This is a test"
dataset = MyDataset()
for batch_size in [1, 8, 64, 256]:
print("-" * 30)
print(f"Streaming batch_size={batch_size}")
for out in tqdm(pipe(dataset, batch_size=batch_size), total=len(dataset)):
pass
# On GTX 970
------------------------------
Streaming no batching
100%|██████████████████████████████████████████████████████████████████████| 5000/5000 [00:26<00:00, 187.52it/s]
------------------------------
Streaming batch_size=8
100%|█████████████████████████████████████████████████████████████████████| 5000/5000 [00:04<00:00, 1205.95it/s]
------------------------------
Streaming batch_size=64
100%|█████████████████████████████████████████████████████████████████████| 5000/5000 [00:02<00:00, 2478.24it/s]
------------------------------
Streaming batch_size=256
100%|█████████████████████████████████████████████████████████████████████| 5000/5000 [00:01<00:00, 2554.43it/s]
(diminishing returns, saturated the GPU)
Example where it’s most a slowdown:
class MyDataset(Dataset):
def __len__(self):
return 5000
def __getitem__(self, i):
if i % 64 == 0:
n = 100
else:
n = 1
return "This is a test" * n
This is a occasional very long sentence compared to the other. In that case, the whole batch will need to be 400 tokens long, so the whole batch will be [64, 400] instead of [64, 4], leading to the high slowdown. Even worse, on bigger batches, the program simply crashes.
------------------------------
Streaming no batching
100%|█████████████████████████████████████████████████████████████████████| 1000/1000 [00:05<00:00, 183.69it/s]
------------------------------
Streaming batch_size=8
100%|█████████████████████████████████████████████████████████████████████| 1000/1000 [00:03<00:00, 265.74it/s]
------------------------------
Streaming batch_size=64
100%|██████████████████████████████████████████████████████████████████████| 1000/1000 [00:26<00:00, 37.80it/s]
------------------------------
Streaming batch_size=256
0%| | 0/1000 [00:00<?, ?it/s]
Traceback (most recent call last):
File "/home/nicolas/src/transformers/test.py", line 42, in <module>
for out in tqdm(pipe(dataset, batch_size=256), total=len(dataset)):
....
q = q / math.sqrt(dim_per_head) # (bs, n_heads, q_length, dim_per_head)
RuntimeError: CUDA out of memory. Tried to allocate 376.00 MiB (GPU 0; 3.95 GiB total capacity; 1.72 GiB already allocated; 354.88 MiB free; 2.46 GiB reserved in total by PyTorch)
There are no good (general) solutions for this problem, and your mileage may vary depending on your use cases. Rule of thumb:
For users, a rule of thumb is:
Measure performance on your load, with your hardware. Measure, measure, and keep measuring. Real numbers are the only way to go.
If you are latency constrained (live product doing inference), don’t batch.
If you are using CPU, don’t batch.
If you are using throughput (you want to run your model on a bunch of static data), on GPU, then:
- If you have no clue about the size of the sequence_length (“natural” data), by default don’t batch, measure and try tentatively to add it, add OOM checks to recover when it will fail (and it will at some point if you don’t control the sequence_length.)
- If your sequence_length is super regular, then batching is more likely to be VERY interesting, measure and push it until you get OOMs.
- The larger the GPU the more likely batching is going to be more interesting
As soon as you enable batching, make sure you can handle OOMs nicely.
Pipeline chunk batching
zero-shot-classification
and question-answering
are slightly specific in the sense, that a single input might yield
multiple forward pass of a model. Under normal circumstances, this would yield issues with batch_size
argument.
In order to circumvent this issue, both of these pipelines are a bit specific, they are ChunkPipeline
instead of
regular Pipeline
. In short:
preprocessed = pipe.preprocess(inputs) model_outputs = pipe.forward(preprocessed) outputs = pipe.postprocess(model_outputs)
Now becomes:
all_model_outputs = []
for preprocessed in pipe.preprocess(inputs):
model_outputs = pipe.forward(preprocessed)
all_model_outputs.append(model_outputs)
outputs = pipe.postprocess(all_model_outputs)
This should be very transparent to your code because the pipelines are used in the same way.
This is a simplified view, since the pipeline can handle automatically the batch to ! Meaning you don’t have to care
about how many forward passes you inputs are actually going to trigger, you can optimize the batch_size
independently of the inputs. The caveats from the previous section still apply.
Pipeline FP16 inference
Models can be run in FP16 which can be significantly faster on GPU while saving memory. Most models will not suffer noticeable performance loss from this. The larger the model, the less likely that it will.
To enable FP16 inference, you can simply pass torch_dtype=torch.float16
or torch_dtype='float16'
to the pipeline constructor. Note that this only works for models with a PyTorch backend. Your inputs will be converted to FP16 internally.
Pipeline custom code
If you want to override a specific pipeline.
Don’t hesitate to create an issue for your task at hand, the goal of the pipeline is to be easy to use and support most
cases, so transformers
could maybe support your use case.
If you want to try simply you can:
- Subclass your pipeline of choice
class MyPipeline(TextClassificationPipeline):
def postprocess():
# Your code goes here
scores = scores * 100
# And here
my_pipeline = MyPipeline(model=model, tokenizer=tokenizer, ...)
# or if you use *pipeline* function, then:
my_pipeline = pipeline(model="xxxx", pipeline_class=MyPipeline)
That should enable you to do all the custom code you want.
Implementing a pipeline
Audio
Pipelines available for audio tasks include the following.
AudioClassificationPipeline
class transformers.AudioClassificationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- feature_extractor (SequenceFeatureExtractor) — The feature extractor that will be used by the pipeline to encode data for the model. This object inherits from SequenceFeatureExtractor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Audio classification pipeline using any AutoModelForAudioClassification
. This pipeline predicts the class of a
raw waveform or an audio file. In case of an audio file, ffmpeg should be installed to support multiple audio
formats.
Example:
>>> from transformers import pipeline
>>> classifier = pipeline(model="superb/wav2vec2-base-superb-ks")
>>> classifier("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/1.flac")
[{'score': 0.997, 'label': '_unknown_'}, {'score': 0.002, 'label': 'left'}, {'score': 0.0, 'label': 'yes'}, {'score': 0.0, 'label': 'down'}, {'score': 0.0, 'label': 'stop'}]
Learn more about the basics of using a pipeline in the pipeline tutorial
This pipeline can currently be loaded from pipeline() using the following task identifier:
"audio-classification"
.
See the list of available models on huggingface.co/models.
__call__
< source >( inputs: Union **kwargs ) → A list of dict
with the following keys
Parameters
- inputs (
np.ndarray
orbytes
orstr
ordict
) — The inputs is either :str
that is the filename of the audio file, the file will be read at the correct sampling rate to get the waveform using ffmpeg. This requires ffmpeg to be installed on the system.bytes
it is supposed to be the content of an audio file and is interpreted by ffmpeg in the same way.- (
np.ndarray
of shape (n, ) of typenp.float32
ornp.float64
) Raw audio at the correct sampling rate (no further check will be done) dict
form can be used to pass raw audio sampled at arbitrarysampling_rate
and let this pipeline do the resampling. The dict must be either be in the format{"sampling_rate": int, "raw": np.array}
, or{"sampling_rate": int, "array": np.array}
, where the key"raw"
or"array"
is used to denote the raw audio waveform.
- top_k (
int
, optional, defaults to None) — The number of top labels that will be returned by the pipeline. If the provided number isNone
or higher than the number of labels available in the model configuration, it will default to the number of labels.
Returns
A list of dict
with the following keys
- label (
str
) — The label predicted. - score (
float
) — The corresponding probability.
Classify the sequence(s) given as inputs. See the AutomaticSpeechRecognitionPipeline documentation for more information.
AutomaticSpeechRecognitionPipeline
class transformers.AutomaticSpeechRecognitionPipeline
< source >( model: PreTrainedModel feature_extractor: Union = None tokenizer: Optional = None decoder: Union = None device: Union = None torch_dtype: Union = None **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- feature_extractor (SequenceFeatureExtractor) — The feature extractor that will be used by the pipeline to encode waveform for the model.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- decoder (
pyctcdecode.BeamSearchDecoderCTC
, optional) — PyCTCDecode’s BeamSearchDecoderCTC can be passed for language model boosted decoding. See Wav2Vec2ProcessorWithLM for more information. - chunk_length_s (
float
, optional, defaults to 0) — The input length for in each chunk. Ifchunk_length_s = 0
then chunking is disabled (default).For more information on how to effectively use
chunk_length_s
, please have a look at the ASR chunking blog post. - stride_length_s (
float
, optional, defaults tochunk_length_s / 6
) — The length of stride on the left and right of each chunk. Used only withchunk_length_s > 0
. This enables the model to see more context and infer letters better than without this context but the pipeline discards the stride bits at the end to make the final reconstitution as perfect as possible.For more information on how to effectively use
stride_length_s
, please have a look at the ASR chunking blog post. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed. If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of themodel
, or to PyTorch if no model is provided. - device (Union[
int
,torch.device
], optional) — Device ordinal for CPU/GPU supports. Setting this toNone
will leverage CPU, a positive will run the model on the associated CUDA device id. - torch_dtype (Union[
int
,torch.dtype
], optional) — The data-type (dtype) of the computation. Setting this toNone
will use float32 precision. Set totorch.float16
ortorch.bfloat16
to use half-precision in the respective dtypes.
Pipeline that aims at extracting spoken text contained within some audio.
The input can be either a raw waveform or a audio file. In case of the audio file, ffmpeg should be installed for to support multiple audio formats
Example:
>>> from transformers import pipeline
>>> transcriber = pipeline(model="openai/whisper-base")
>>> transcriber("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/1.flac")
{'text': ' He hoped there would be stew for dinner, turnips and carrots and bruised potatoes and fat mutton pieces to be ladled out in thick, peppered flour-fatten sauce.'}
Learn more about the basics of using a pipeline in the pipeline tutorial
__call__
< source >( inputs: Union **kwargs ) → Dict
Parameters
- inputs (
np.ndarray
orbytes
orstr
ordict
) — The inputs is either :str
that is either the filename of a local audio file, or a public URL address to download the audio file. The file will be read at the correct sampling rate to get the waveform using ffmpeg. This requires ffmpeg to be installed on the system.bytes
it is supposed to be the content of an audio file and is interpreted by ffmpeg in the same way.- (
np.ndarray
of shape (n, ) of typenp.float32
ornp.float64
) Raw audio at the correct sampling rate (no further check will be done) dict
form can be used to pass raw audio sampled at arbitrarysampling_rate
and let this pipeline do the resampling. The dict must be in the format{"sampling_rate": int, "raw": np.array}
with optionally a"stride": (left: int, right: int)
than can ask the pipeline to treat the firstleft
samples and lastright
samples to be ignored in decoding (but used at inference to provide more context to the model). Only usestride
with CTC models.
- return_timestamps (optional,
str
orbool
) — Only available for pure CTC models (Wav2Vec2, HuBERT, etc) and the Whisper model. Not available for other sequence-to-sequence models.For CTC models, timestamps can take one of two formats:
"char"
: the pipeline will return timestamps along the text for every character in the text. For instance, if you get[{"text": "h", "timestamp": (0.5, 0.6)}, {"text": "i", "timestamp": (0.7, 0.9)}]
, then it means the model predicts that the letter “h” was spoken after0.5
and before0.6
seconds."word"
: the pipeline will return timestamps along the text for every word in the text. For instance, if you get[{"text": "hi ", "timestamp": (0.5, 0.9)}, {"text": "there", "timestamp": (1.0, 1.5)}]
, then it means the model predicts that the word “hi” was spoken after0.5
and before0.9
seconds.
For the Whisper model, timestamps can take one of two formats:
"word"
: same as above for word-level CTC timestamps. Word-level timestamps are predicted through the dynamic-time warping (DTW) algorithm, an approximation to word-level timestamps by inspecting the cross-attention weights.True
: the pipeline will return timestamps along the text for segments of words in the text. For instance, if you get[{"text": " Hi there!", "timestamp": (0.5, 1.5)}]
, then it means the model predicts that the segment “Hi there!” was spoken after0.5
and before1.5
seconds. Note that a segment of text refers to a sequence of one or more words, rather than individual words as with word-level timestamps.
- generate_kwargs (
dict
, optional) — The dictionary of ad-hoc parametrization ofgenerate_config
to be used for the generation call. For a complete overview of generate, check the following guide. - max_new_tokens (
int
, optional) — The maximum numbers of tokens to generate, ignoring the number of tokens in the prompt.
Returns
Dict
A dictionary with the following keys:
- text (
str
): The recognized text. - chunks (optional(,
List[Dict]
) When usingreturn_timestamps
, thechunks
will become a list containing all the various text chunks identified by the model, e.g.*[{"text": "hi ", "timestamp": (0.5, 0.9)}, {"text": "there", "timestamp": (1.0, 1.5)}]
. The original full text can roughly be recovered by doing"".join(chunk["text"] for chunk in output["chunks"])
.
Transcribe the audio sequence(s) given as inputs to text. See the AutomaticSpeechRecognitionPipeline documentation for more information.
TextToAudioPipeline
class transformers.TextToAudioPipeline
< source >( *args vocoder = None sampling_rate = None **kwargs )
Text-to-audio generation pipeline using any AutoModelForTextToWaveform
or AutoModelForTextToSpectrogram
. This
pipeline generates an audio file from an input text and optional other conditional inputs.
Example:
>>> from transformers import pipeline
>>> pipe = pipeline(model="suno/bark-small")
>>> output = pipe("Hey it's HuggingFace on the phone!")
>>> audio = output["audio"]
>>> sampling_rate = output["sampling_rate"]
Learn more about the basics of using a pipeline in the pipeline tutorial
You can specify parameters passed to the model by using TextToAudioPipeline.__call__.forward_params
or
TextToAudioPipeline.__call__.generate_kwargs
.
Example:
>>> from transformers import pipeline
>>> music_generator = pipeline(task="text-to-audio", model="facebook/musicgen-small", framework="pt")
>>> # diversify the music generation by adding randomness with a high temperature and set a maximum music length
>>> generate_kwargs = {
... "do_sample": True,
... "temperature": 0.7,
... "max_new_tokens": 35,
... }
>>> outputs = music_generator("Techno music with high melodic riffs", generate_kwargs=generate_kwargs)
This pipeline can currently be loaded from pipeline() using the following task identifiers: "text-to-speech"
or
"text-to-audio"
.
See the list of available models on huggingface.co/models.
__call__
< source >( text_inputs: Union **forward_params ) → A dict
or a list of dict
Parameters
- text_inputs (
str
orList[str]
) — The text(s) to generate. - forward_params (
dict
, optional) — Parameters passed to the model generation/forward method.forward_params
are always passed to the underlying model. - generate_kwargs (
dict
, optional) — The dictionary of ad-hoc parametrization ofgenerate_config
to be used for the generation call. For a complete overview of generate, check the following guide.generate_kwargs
are only passed to the underlying model if the latter is a generative model.
Returns
A dict
or a list of dict
The dictionaries have two keys:
- audio (
np.ndarray
of shape(nb_channels, audio_length)
) — The generated audio waveform. - sampling_rate (
int
) — The sampling rate of the generated audio waveform.
Generates speech/audio from the inputs. See the TextToAudioPipeline documentation for more information.
ZeroShotAudioClassificationPipeline
class transformers.ZeroShotAudioClassificationPipeline
< source >( **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- feature_extractor (SequenceFeatureExtractor) — The feature extractor that will be used by the pipeline to encode data for the model. This object inherits from SequenceFeatureExtractor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Zero shot audio classification pipeline using ClapModel
. This pipeline predicts the class of an audio when you
provide an audio and a set of candidate_labels
.
The default hypothesis_template
is : "This is a sound of {}."
. Make sure you update it for your usage.
Example:
>>> from transformers import pipeline
>>> from datasets import load_dataset
>>> dataset = load_dataset("ashraq/esc50")
>>> audio = next(iter(dataset["train"]["audio"]))["array"]
>>> classifier = pipeline(task="zero-shot-audio-classification", model="laion/clap-htsat-unfused")
>>> classifier(audio, candidate_labels=["Sound of a dog", "Sound of vaccum cleaner"])
[{'score': 0.9996, 'label': 'Sound of a dog'}, {'score': 0.0004, 'label': 'Sound of vaccum cleaner'}]
Learn more about the basics of using a pipeline in the pipeline tutorial This audio
classification pipeline can currently be loaded from pipeline() using the following task identifier:
"zero-shot-audio-classification"
. See the list of available models on
huggingface.co/models.
__call__
< source >( audios: Union **kwargs )
Parameters
- audios (
str
,List[str]
,np.array
orList[np.array]
) — The pipeline handles three types of inputs:- A string containing a http link pointing to an audio
- A string containing a local path to an audio
- An audio loaded in numpy
- candidate_labels (
List[str]
) — The candidate labels for this audio. They will be formatted using hypothesis_template. - hypothesis_template (
str
, optional, defaults to"This is a sound of {}"
) — The format used in conjunction with candidate_labels to attempt the audio classification by replacing the placeholder with the candidate_labels. Pass ”{}” if candidate_labels are already formatted.
Assign labels to the audio(s) passed as inputs.
Computer vision
Pipelines available for computer vision tasks include the following.
DepthEstimationPipeline
class transformers.DepthEstimationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Depth estimation pipeline using any AutoModelForDepthEstimation
. This pipeline predicts the depth of an image.
Example:
>>> from transformers import pipeline
>>> depth_estimator = pipeline(task="depth-estimation", model="LiheYoung/depth-anything-base-hf")
>>> output = depth_estimator("http://images.cocodataset.org/val2017/000000039769.jpg")
>>> # This is a tensor with the values being the depth expressed in meters for each pixel
>>> output["predicted_depth"].shape
torch.Size([1, 384, 384])
Learn more about the basics of using a pipeline in the pipeline tutorial
This depth estimation pipeline can currently be loaded from pipeline() using the following task identifier:
"depth-estimation"
.
See the list of available models on huggingface.co/models.
__call__
< source >( images: Union **kwargs )
Parameters
- images (
str
,List[str]
,PIL.Image
orList[PIL.Image]
) — The pipeline handles three types of images:- A string containing a http link pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
The pipeline accepts either a single image or a batch of images, which must then be passed as a string. Images in a batch must all be in the same format: all as http links, all as local paths, or all as PIL images.
- timeout (
float
, optional, defaults to None) — The maximum time in seconds to wait for fetching images from the web. If None, no timeout is set and the call may block forever.
Predict the depth(s) of the image(s) passed as inputs.
ImageClassificationPipeline
class transformers.ImageClassificationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text. - function_to_apply (
str
, optional, defaults to"default"
) — The function to apply to the model outputs in order to retrieve the scores. Accepts four different values:"default"
: if the model has a single label, will apply the sigmoid function on the output. If the model has several labels, will apply the softmax function on the output."sigmoid"
: Applies the sigmoid function on the output."softmax"
: Applies the softmax function on the output."none"
: Does not apply any function on the output.
Image classification pipeline using any AutoModelForImageClassification
. This pipeline predicts the class of an
image.
Example:
>>> from transformers import pipeline
>>> classifier = pipeline(model="microsoft/beit-base-patch16-224-pt22k-ft22k")
>>> classifier("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
[{'score': 0.442, 'label': 'macaw'}, {'score': 0.088, 'label': 'popinjay'}, {'score': 0.075, 'label': 'parrot'}, {'score': 0.073, 'label': 'parodist, lampooner'}, {'score': 0.046, 'label': 'poll, poll_parrot'}]
Learn more about the basics of using a pipeline in the pipeline tutorial
This image classification pipeline can currently be loaded from pipeline() using the following task identifier:
"image-classification"
.
See the list of available models on huggingface.co/models.
__call__
< source >( images: Union **kwargs )
Parameters
- images (
str
,List[str]
,PIL.Image
orList[PIL.Image]
) — The pipeline handles three types of images:- A string containing a http link pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
The pipeline accepts either a single image or a batch of images, which must then be passed as a string. Images in a batch must all be in the same format: all as http links, all as local paths, or all as PIL images.
- function_to_apply (
str
, optional, defaults to"default"
) — The function to apply to the model outputs in order to retrieve the scores. Accepts four different values:If this argument is not specified, then it will apply the following functions according to the number of labels:
- If the model has a single label, will apply the sigmoid function on the output.
- If the model has several labels, will apply the softmax function on the output.
Possible values are:
"sigmoid"
: Applies the sigmoid function on the output."softmax"
: Applies the softmax function on the output."none"
: Does not apply any function on the output.
- top_k (
int
, optional, defaults to 5) — The number of top labels that will be returned by the pipeline. If the provided number is higher than the number of labels available in the model configuration, it will default to the number of labels. - timeout (
float
, optional, defaults to None) — The maximum time in seconds to wait for fetching images from the web. If None, no timeout is set and the call may block forever.
Assign labels to the image(s) passed as inputs.
ImageSegmentationPipeline
class transformers.ImageSegmentationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Image segmentation pipeline using any AutoModelForXXXSegmentation
. This pipeline predicts masks of objects and
their classes.
Example:
>>> from transformers import pipeline
>>> segmenter = pipeline(model="facebook/detr-resnet-50-panoptic")
>>> segments = segmenter("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
>>> len(segments)
2
>>> segments[0]["label"]
'bird'
>>> segments[1]["label"]
'bird'
>>> type(segments[0]["mask"]) # This is a black and white mask showing where is the bird on the original image.
<class 'PIL.Image.Image'>
>>> segments[0]["mask"].size
(768, 512)
This image segmentation pipeline can currently be loaded from pipeline() using the following task identifier:
"image-segmentation"
.
See the list of available models on huggingface.co/models.
__call__
< source >( images **kwargs )
Parameters
- images (
str
,List[str]
,PIL.Image
orList[PIL.Image]
) — The pipeline handles three types of images:- A string containing an HTTP(S) link pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
The pipeline accepts either a single image or a batch of images. Images in a batch must all be in the same format: all as HTTP(S) links, all as local paths, or all as PIL images.
- subtask (
str
, optional) — Segmentation task to be performed, choose [semantic
,instance
andpanoptic
] depending on model capabilities. If not set, the pipeline will attempt tp resolve in the following order:panoptic
,instance
,semantic
. - threshold (
float
, optional, defaults to 0.9) — Probability threshold to filter out predicted masks. - mask_threshold (
float
, optional, defaults to 0.5) — Threshold to use when turning the predicted masks into binary values. - overlap_mask_area_threshold (
float
, optional, defaults to 0.5) — Mask overlap threshold to eliminate small, disconnected segments. - timeout (
float
, optional, defaults to None) — The maximum time in seconds to wait for fetching images from the web. If None, no timeout is set and the call may block forever.
Perform segmentation (detect masks & classes) in the image(s) passed as inputs.
ImageToImagePipeline
class transformers.ImageToImagePipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Image to Image pipeline using any AutoModelForImageToImage
. This pipeline generates an image based on a previous
image input.
Example:
>>> from PIL import Image
>>> import requests
>>> from transformers import pipeline
>>> upscaler = pipeline("image-to-image", model="caidas/swin2SR-classical-sr-x2-64")
>>> img = Image.open(requests.get("http://images.cocodataset.org/val2017/000000039769.jpg", stream=True).raw)
>>> img = img.resize((64, 64))
>>> upscaled_img = upscaler(img)
>>> img.size
(64, 64)
>>> upscaled_img.size
(144, 144)
This image to image pipeline can currently be loaded from pipeline() using the following task identifier:
"image-to-image"
.
See the list of available models on huggingface.co/models.
__call__
< source >( images: Union **kwargs )
Parameters
- images (
str
,List[str]
,PIL.Image
orList[PIL.Image]
) — The pipeline handles three types of images:- A string containing a http link pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
The pipeline accepts either a single image or a batch of images, which must then be passed as a string. Images in a batch must all be in the same format: all as http links, all as local paths, or all as PIL images.
- timeout (
float
, optional, defaults to None) — The maximum time in seconds to wait for fetching images from the web. If None, no timeout is used and the call may block forever.
Transform the image(s) passed as inputs.
ObjectDetectionPipeline
class transformers.ObjectDetectionPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Object detection pipeline using any AutoModelForObjectDetection
. This pipeline predicts bounding boxes of objects
and their classes.
Example:
>>> from transformers import pipeline
>>> detector = pipeline(model="facebook/detr-resnet-50")
>>> detector("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
[{'score': 0.997, 'label': 'bird', 'box': {'xmin': 69, 'ymin': 171, 'xmax': 396, 'ymax': 507}}, {'score': 0.999, 'label': 'bird', 'box': {'xmin': 398, 'ymin': 105, 'xmax': 767, 'ymax': 507}}]
>>> # x, y are expressed relative to the top left hand corner.
Learn more about the basics of using a pipeline in the pipeline tutorial
This object detection pipeline can currently be loaded from pipeline() using the following task identifier:
"object-detection"
.
See the list of available models on huggingface.co/models.
__call__
< source >( *args **kwargs )
Parameters
- images (
str
,List[str]
,PIL.Image
orList[PIL.Image]
) — The pipeline handles three types of images:- A string containing an HTTP(S) link pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
The pipeline accepts either a single image or a batch of images. Images in a batch must all be in the same format: all as HTTP(S) links, all as local paths, or all as PIL images.
- threshold (
float
, optional, defaults to 0.5) — The probability necessary to make a prediction. - timeout (
float
, optional, defaults to None) — The maximum time in seconds to wait for fetching images from the web. If None, no timeout is set and the call may block forever.
Detect objects (bounding boxes & classes) in the image(s) passed as inputs.
VideoClassificationPipeline
class transformers.VideoClassificationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Video classification pipeline using any AutoModelForVideoClassification
. This pipeline predicts the class of a
video.
This video classification pipeline can currently be loaded from pipeline() using the following task identifier:
"video-classification"
.
See the list of available models on huggingface.co/models.
__call__
< source >( videos: Union **kwargs )
Parameters
- videos (
str
,List[str]
) — The pipeline handles three types of videos:- A string containing a http link pointing to a video
- A string containing a local path to a video
The pipeline accepts either a single video or a batch of videos, which must then be passed as a string. Videos in a batch must all be in the same format: all as http links or all as local paths.
- top_k (
int
, optional, defaults to 5) — The number of top labels that will be returned by the pipeline. If the provided number is higher than the number of labels available in the model configuration, it will default to the number of labels. - num_frames (
int
, optional, defaults toself.model.config.num_frames
) — The number of frames sampled from the video to run the classification on. If not provided, will default to the number of frames specified in the model configuration. - frame_sampling_rate (
int
, optional, defaults to 1) — The sampling rate used to select frames from the video. If not provided, will default to 1, i.e. every frame will be used.
Assign labels to the video(s) passed as inputs.
ZeroShotImageClassificationPipeline
class transformers.ZeroShotImageClassificationPipeline
< source >( **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Zero shot image classification pipeline using CLIPModel
. This pipeline predicts the class of an image when you
provide an image and a set of candidate_labels
.
Example:
>>> from transformers import pipeline
>>> classifier = pipeline(model="google/siglip-so400m-patch14-384")
>>> classifier(
... "https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png",
... candidate_labels=["animals", "humans", "landscape"],
... )
[{'score': 0.965, 'label': 'animals'}, {'score': 0.03, 'label': 'humans'}, {'score': 0.005, 'label': 'landscape'}]
>>> classifier(
... "https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png",
... candidate_labels=["black and white", "photorealist", "painting"],
... )
[{'score': 0.996, 'label': 'black and white'}, {'score': 0.003, 'label': 'photorealist'}, {'score': 0.0, 'label': 'painting'}]
Learn more about the basics of using a pipeline in the pipeline tutorial
This image classification pipeline can currently be loaded from pipeline() using the following task identifier:
"zero-shot-image-classification"
.
See the list of available models on huggingface.co/models.
__call__
< source >( images: Union **kwargs )
Parameters
- images (
str
,List[str]
,PIL.Image
orList[PIL.Image]
) — The pipeline handles three types of images:- A string containing a http link pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
- candidate_labels (
List[str]
) — The candidate labels for this image. They will be formatted using hypothesis_template. - hypothesis_template (
str
, optional, defaults to"This is a photo of {}"
) — The format used in conjunction with candidate_labels to attempt the image classification by replacing the placeholder with the candidate_labels. Pass ”{}” if candidate_labels are already formatted. - timeout (
float
, optional, defaults to None) — The maximum time in seconds to wait for fetching images from the web. If None, no timeout is set and the call may block forever. - tokenizer_kwargs (
dict
, optional) — Additional dictionary of keyword arguments passed along to the tokenizer.
Assign labels to the image(s) passed as inputs.
ZeroShotObjectDetectionPipeline
class transformers.ZeroShotObjectDetectionPipeline
< source >( **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- image_processor (BaseImageProcessor) — The image processor that will be used by the pipeline to encode data for the model. This object inherits from BaseImageProcessor.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Zero shot object detection pipeline using OwlViTForObjectDetection
. This pipeline predicts bounding boxes of
objects when you provide an image and a set of candidate_labels
.
Example:
>>> from transformers import pipeline
>>> detector = pipeline(model="google/owlvit-base-patch32", task="zero-shot-object-detection")
>>> detector(
... "http://images.cocodataset.org/val2017/000000039769.jpg",
... candidate_labels=["cat", "couch"],
... )
[{'score': 0.287, 'label': 'cat', 'box': {'xmin': 324, 'ymin': 20, 'xmax': 640, 'ymax': 373}}, {'score': 0.254, 'label': 'cat', 'box': {'xmin': 1, 'ymin': 55, 'xmax': 315, 'ymax': 472}}, {'score': 0.121, 'label': 'couch', 'box': {'xmin': 4, 'ymin': 0, 'xmax': 642, 'ymax': 476}}]
>>> detector(
... "https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png",
... candidate_labels=["head", "bird"],
... )
[{'score': 0.119, 'label': 'bird', 'box': {'xmin': 71, 'ymin': 170, 'xmax': 410, 'ymax': 508}}]
Learn more about the basics of using a pipeline in the pipeline tutorial
This object detection pipeline can currently be loaded from pipeline() using the following task identifier:
"zero-shot-object-detection"
.
See the list of available models on huggingface.co/models.
__call__
< source >( image: Union candidate_labels: Union = None **kwargs )
Parameters
- image (
str
,PIL.Image
orList[Dict[str, Any]]
) — The pipeline handles three types of images:- A string containing an http url pointing to an image
- A string containing a local path to an image
- An image loaded in PIL directly
You can use this parameter to send directly a list of images, or a dataset or a generator like so:
Detect objects (bounding boxes & classes) in the image(s) passed as inputs.
Natural Language Processing
Pipelines available for natural language processing tasks include the following.
FillMaskPipeline
class transformers.FillMaskPipeline
< source >( model: Union tokenizer: Optional = None feature_extractor: Optional = None image_processor: Optional = None modelcard: Optional = None framework: Optional = None task: str = '' args_parser: ArgumentHandler = None device: Union = None torch_dtype: Union = None binary_output: bool = False **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text. - top_k (
int
, optional, defaults to 5) — The number of predictions to return. - targets (
str
orList[str]
, optional) — When passed, the model will limit the scores to the passed targets instead of looking up in the whole vocab. If the provided targets are not in the model vocab, they will be tokenized and the first resulting token will be used (with a warning, and that might be slower). - tokenizer_kwargs (
dict
, optional) — Additional dictionary of keyword arguments passed along to the tokenizer.
Masked language modeling prediction pipeline using any ModelWithLMHead
. See the masked language modeling
examples for more information.
Example:
>>> from transformers import pipeline
>>> fill_masker = pipeline(model="google-bert/bert-base-uncased")
>>> fill_masker("This is a simple [MASK].")
[{'score': 0.042, 'token': 3291, 'token_str': 'problem', 'sequence': 'this is a simple problem.'}, {'score': 0.031, 'token': 3160, 'token_str': 'question', 'sequence': 'this is a simple question.'}, {'score': 0.03, 'token': 8522, 'token_str': 'equation', 'sequence': 'this is a simple equation.'}, {'score': 0.027, 'token': 2028, 'token_str': 'one', 'sequence': 'this is a simple one.'}, {'score': 0.024, 'token': 3627, 'token_str': 'rule', 'sequence': 'this is a simple rule.'}]
Learn more about the basics of using a pipeline in the pipeline tutorial
This mask filling pipeline can currently be loaded from pipeline() using the following task identifier:
"fill-mask"
.
The models that this pipeline can use are models that have been trained with a masked language modeling objective, which includes the bi-directional models in the library. See the up-to-date list of available models on huggingface.co/models.
This pipeline only works for inputs with exactly one token masked. Experimental: We added support for multiple masks. The returned values are raw model output, and correspond to disjoint probabilities where one might expect joint probabilities (See discussion).
This pipeline now supports tokenizer_kwargs. For example try:
>>> from transformers import pipeline
>>> fill_masker = pipeline(model="google-bert/bert-base-uncased")
>>> tokenizer_kwargs = {"truncation": True}
>>> fill_masker(
... "This is a simple [MASK]. " + "...with a large amount of repeated text appended. " * 100,
... tokenizer_kwargs=tokenizer_kwargs,
... )
__call__
< source >( inputs *args **kwargs ) → A list or a list of list of dict
Parameters
- args (
str
orList[str]
) — One or several texts (or one list of prompts) with masked tokens. - targets (
str
orList[str]
, optional) — When passed, the model will limit the scores to the passed targets instead of looking up in the whole vocab. If the provided targets are not in the model vocab, they will be tokenized and the first resulting token will be used (with a warning, and that might be slower). - top_k (
int
, optional) — When passed, overrides the number of predictions to return.
Returns
A list or a list of list of dict
Each result comes as list of dictionaries with the following keys:
- sequence (
str
) — The corresponding input with the mask token prediction. - score (
float
) — The corresponding probability. - token (
int
) — The predicted token id (to replace the masked one). - token_str (
str
) — The predicted token (to replace the masked one).
Fill the masked token in the text(s) given as inputs.
QuestionAnsweringPipeline
class transformers.QuestionAnsweringPipeline
< source >( model: Union tokenizer: PreTrainedTokenizer modelcard: Optional = None framework: Optional = None task: str = '' **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Question Answering pipeline using any ModelForQuestionAnswering
. See the question answering
examples for more information.
Example:
>>> from transformers import pipeline
>>> oracle = pipeline(model="deepset/roberta-base-squad2")
>>> oracle(question="Where do I live?", context="My name is Wolfgang and I live in Berlin")
{'score': 0.9191, 'start': 34, 'end': 40, 'answer': 'Berlin'}
Learn more about the basics of using a pipeline in the pipeline tutorial
This question answering pipeline can currently be loaded from pipeline() using the following task identifier:
"question-answering"
.
The models that this pipeline can use are models that have been fine-tuned on a question answering task. See the up-to-date list of available models on huggingface.co/models.
__call__
< source >( *args **kwargs ) → A dict
or a list of dict
Parameters
- args (
SquadExample
or a list ofSquadExample
) — One or severalSquadExample
containing the question and context. - X (
SquadExample
or a list ofSquadExample
, optional) — One or severalSquadExample
containing the question and context (will be treated the same way as if passed as the first positional argument). - data (
SquadExample
or a list ofSquadExample
, optional) — One or severalSquadExample
containing the question and context (will be treated the same way as if passed as the first positional argument). - question (
str
orList[str]
) — One or several question(s) (must be used in conjunction with thecontext
argument). - context (
str
orList[str]
) — One or several context(s) associated with the question(s) (must be used in conjunction with thequestion
argument). - topk (
int
, optional, defaults to 1) — The number of answers to return (will be chosen by order of likelihood). Note that we return less than topk answers if there are not enough options available within the context. - doc_stride (
int
, optional, defaults to 128) — If the context is too long to fit with the question for the model, it will be split in several chunks with some overlap. This argument controls the size of that overlap. - max_answer_len (
int
, optional, defaults to 15) — The maximum length of predicted answers (e.g., only answers with a shorter length are considered). - max_seq_len (
int
, optional, defaults to 384) — The maximum length of the total sentence (context + question) in tokens of each chunk passed to the model. The context will be split in several chunks (usingdoc_stride
as overlap) if needed. - max_question_len (
int
, optional, defaults to 64) — The maximum length of the question after tokenization. It will be truncated if needed. - handle_impossible_answer (
bool
, optional, defaults toFalse
) — Whether or not we accept impossible as an answer. - align_to_words (
bool
, optional, defaults toTrue
) — Attempts to align the answer to real words. Improves quality on space separated langages. Might hurt on non-space-separated languages (like Japanese or Chinese)
Returns
A dict
or a list of dict
Each result comes as a dictionary with the following keys:
- score (
float
) — The probability associated to the answer. - start (
int
) — The character start index of the answer (in the tokenized version of the input). - end (
int
) — The character end index of the answer (in the tokenized version of the input). - answer (
str
) — The answer to the question.
Answer the question(s) given as inputs by using the context(s).
create_sample
< source >( question: Union context: Union ) → One or a list of SquadExample
QuestionAnsweringPipeline leverages the SquadExample
internally. This helper method encapsulate all the
logic for converting question(s) and context(s) to SquadExample
.
We currently support extractive question answering.
span_to_answer
< source >( text: str start: int end: int ) → Dictionary like `{‘answer’
When decoding from token probabilities, this method maps token indexes to actual word in the initial context.
SummarizationPipeline
class transformers.SummarizationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Summarize news articles and other documents.
This summarizing pipeline can currently be loaded from pipeline() using the following task identifier:
"summarization"
.
The models that this pipeline can use are models that have been fine-tuned on a summarization task, which is currently, ’bart-large-cnn’, ’google-t5/t5-small’, ’google-t5/t5-base’, ’google-t5/t5-large’, ’google-t5/t5-3b’, ’google-t5/t5-11b’. See the up-to-date list of available models on huggingface.co/models. For a list of available parameters, see the following documentation
Usage:
# use bart in pytorch
summarizer = pipeline("summarization")
summarizer("An apple a day, keeps the doctor away", min_length=5, max_length=20)
# use t5 in tf
summarizer = pipeline("summarization", model="google-t5/t5-base", tokenizer="google-t5/t5-base", framework="tf")
summarizer("An apple a day, keeps the doctor away", min_length=5, max_length=20)
__call__
< source >( *args **kwargs ) → A list or a list of list of dict
Parameters
- documents (str or
List[str]
) — One or several articles (or one list of articles) to summarize. - return_text (
bool
, optional, defaults toTrue
) — Whether or not to include the decoded texts in the outputs - return_tensors (
bool
, optional, defaults toFalse
) — Whether or not to include the tensors of predictions (as token indices) in the outputs. - clean_up_tokenization_spaces (
bool
, optional, defaults toFalse
) — Whether or not to clean up the potential extra spaces in the text output. generate_kwargs — Additional keyword arguments to pass along to the generate method of the model (see the generate method corresponding to your framework here).
Returns
A list or a list of list of dict
Each result comes as a dictionary with the following keys:
- summary_text (
str
, present whenreturn_text=True
) — The summary of the corresponding input. - summary_token_ids (
torch.Tensor
ortf.Tensor
, present whenreturn_tensors=True
) — The token ids of the summary.
Summarize the text(s) given as inputs.
TableQuestionAnsweringPipeline
class transformers.TableQuestionAnsweringPipeline
< source >( args_parser = <transformers.pipelines.table_question_answering.TableQuestionAnsweringArgumentHandler object at 0x7fbeb1607460> *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Table Question Answering pipeline using a ModelForTableQuestionAnswering
. This pipeline is only available in
PyTorch.
Example:
>>> from transformers import pipeline
>>> oracle = pipeline(model="google/tapas-base-finetuned-wtq")
>>> table = {
... "Repository": ["Transformers", "Datasets", "Tokenizers"],
... "Stars": ["36542", "4512", "3934"],
... "Contributors": ["651", "77", "34"],
... "Programming language": ["Python", "Python", "Rust, Python and NodeJS"],
... }
>>> oracle(query="How many stars does the transformers repository have?", table=table)
{'answer': 'AVERAGE > 36542', 'coordinates': [(0, 1)], 'cells': ['36542'], 'aggregator': 'AVERAGE'}
Learn more about the basics of using a pipeline in the pipeline tutorial
This tabular question answering pipeline can currently be loaded from pipeline() using the following task
identifier: "table-question-answering"
.
The models that this pipeline can use are models that have been fine-tuned on a tabular question answering task. See the up-to-date list of available models on huggingface.co/models.
__call__
< source >( *args **kwargs ) → A dictionary or a list of dictionaries containing results
Parameters
- table (
pd.DataFrame
orDict
) — Pandas DataFrame or dictionary that will be converted to a DataFrame containing all the table values. See above for an example of dictionary. - query (
str
orList[str]
) — Query or list of queries that will be sent to the model alongside the table. - sequential (
bool
, optional, defaults toFalse
) — Whether to do inference sequentially or as a batch. Batching is faster, but models like SQA require the inference to be done sequentially to extract relations within sequences, given their conversational nature. - padding (
bool
,str
or PaddingStrategy, optional, defaults toFalse
) — Activates and controls padding. Accepts the following values:True
or'longest'
: Pad to the longest sequence in the batch (or no padding if only a single sequence if provided).'max_length'
: Pad to a maximum length specified with the argumentmax_length
or to the maximum acceptable input length for the model if that argument is not provided.False
or'do_not_pad'
(default): No padding (i.e., can output a batch with sequences of different lengths).
- truncation (
bool
,str
orTapasTruncationStrategy
, optional, defaults toFalse
) — Activates and controls truncation. Accepts the following values:True
or'drop_rows_to_fit'
: Truncate to a maximum length specified with the argumentmax_length
or to the maximum acceptable input length for the model if that argument is not provided. This will truncate row by row, removing rows from the table.False
or'do_not_truncate'
(default): No truncation (i.e., can output batch with sequence lengths greater than the model maximum admissible input size).
Returns
A dictionary or a list of dictionaries containing results
Each result is a dictionary with the following keys:
- answer (
str
) — The answer of the query given the table. If there is an aggregator, the answer will be preceded byAGGREGATOR >
. - coordinates (
List[Tuple[int, int]]
) — Coordinates of the cells of the answers. - cells (
List[str]
) — List of strings made up of the answer cell values. - aggregator (
str
) — If the model has an aggregator, this returns the aggregator.
Answers queries according to a table. The pipeline accepts several types of inputs which are detailed below:
pipeline(table, query)
pipeline(table, [query])
pipeline(table=table, query=query)
pipeline(table=table, query=[query])
pipeline({"table": table, "query": query})
pipeline({"table": table, "query": [query]})
pipeline([{"table": table, "query": query}, {"table": table, "query": query}])
The table
argument should be a dict or a DataFrame built from that dict, containing the whole table:
Example:
data = {
"actors": ["brad pitt", "leonardo di caprio", "george clooney"],
"age": ["56", "45", "59"],
"number of movies": ["87", "53", "69"],
"date of birth": ["7 february 1967", "10 june 1996", "28 november 1967"],
}
This dictionary can be passed in as such, or can be converted to a pandas DataFrame:
TextClassificationPipeline
class transformers.TextClassificationPipeline
< source >( **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text. - return_all_scores (
bool
, optional, defaults toFalse
) — Whether to return all prediction scores or just the one of the predicted class. - function_to_apply (
str
, optional, defaults to"default"
) — The function to apply to the model outputs in order to retrieve the scores. Accepts four different values:"default"
: if the model has a single label, will apply the sigmoid function on the output. If the model has several labels, will apply the softmax function on the output."sigmoid"
: Applies the sigmoid function on the output."softmax"
: Applies the softmax function on the output."none"
: Does not apply any function on the output.
Text classification pipeline using any ModelForSequenceClassification
. See the sequence classification
examples for more information.
Example:
>>> from transformers import pipeline
>>> classifier = pipeline(model="distilbert/distilbert-base-uncased-finetuned-sst-2-english")
>>> classifier("This movie is disgustingly good !")
[{'label': 'POSITIVE', 'score': 1.0}]
>>> classifier("Director tried too much.")
[{'label': 'NEGATIVE', 'score': 0.996}]
Learn more about the basics of using a pipeline in the pipeline tutorial
This text classification pipeline can currently be loaded from pipeline() using the following task identifier:
"sentiment-analysis"
(for classifying sequences according to positive or negative sentiments).
If multiple classification labels are available (model.config.num_labels >= 2
), the pipeline will run a softmax
over the results. If there is a single label, the pipeline will run a sigmoid over the result.
The models that this pipeline can use are models that have been fine-tuned on a sequence classification task. See the up-to-date list of available models on huggingface.co/models.
__call__
< source >( inputs **kwargs ) → A list or a list of list of dict
Parameters
- inputs (
str
orList[str]
orDict[str]
, orList[Dict[str]]
) — One or several texts to classify. In order to use text pairs for your classification, you can send a dictionary containing{"text", "text_pair"}
keys, or a list of those. - top_k (
int
, optional, defaults to1
) — How many results to return. - function_to_apply (
str
, optional, defaults to"default"
) — The function to apply to the model outputs in order to retrieve the scores. Accepts four different values:If this argument is not specified, then it will apply the following functions according to the number of labels:
- If the model has a single label, will apply the sigmoid function on the output.
- If the model has several labels, will apply the softmax function on the output.
Possible values are:
"sigmoid"
: Applies the sigmoid function on the output."softmax"
: Applies the softmax function on the output."none"
: Does not apply any function on the output.
Returns
A list or a list of list of dict
Each result comes as list of dictionaries with the following keys:
- label (
str
) — The label predicted. - score (
float
) — The corresponding probability.
If top_k
is used, one such dictionary is returned per label.
Classify the text(s) given as inputs.
TextGenerationPipeline
class transformers.TextGenerationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Language generation pipeline using any ModelWithLMHead
. This pipeline predicts the words that will follow a
specified text prompt. When the underlying model is a conversational model, it can also accept one or more chats,
in which case the pipeline will operate in chat mode and will continue the chat(s) by adding its response(s).
Each chat takes the form of a list of dicts, where each dict contains “role” and “content” keys.
Examples:
>>> from transformers import pipeline
>>> generator = pipeline(model="openai-community/gpt2")
>>> generator("I can't believe you did such a ", do_sample=False)
[{'generated_text': "I can't believe you did such a icky thing to me. I'm so sorry. I'm so sorry. I'm so sorry. I'm so sorry. I'm so sorry. I'm so sorry. I'm so sorry. I"}]
>>> # These parameters will return suggestions, and only the newly created text making it easier for prompting suggestions.
>>> outputs = generator("My tart needs some", num_return_sequences=4, return_full_text=False)
>>> from transformers import pipeline
>>> generator = pipeline(model="HuggingFaceH4/zephyr-7b-beta")
>>> # Zephyr-beta is a conversational model, so let's pass it a chat instead of a single string
>>> generator([{"role": "user", "content": "What is the capital of France? Answer in one word."}], do_sample=False, max_new_tokens=2)
[{'generated_text': [{'role': 'user', 'content': 'What is the capital of France? Answer in one word.'}, {'role': 'assistant', 'content': 'Paris'}]}]
Learn more about the basics of using a pipeline in the pipeline tutorial. You can pass text generation parameters to this pipeline to control stopping criteria, decoding strategy, and more. Learn more about text generation parameters in Text generation strategies and Text generation.
This language generation pipeline can currently be loaded from pipeline() using the following task identifier:
"text-generation"
.
The models that this pipeline can use are models that have been trained with an autoregressive language modeling objective. See the list of available text completion models and the list of conversational models on [huggingface.co/models].
__call__
< source >( text_inputs **kwargs ) → A list or a list of lists of dict
Parameters
- text_inputs (
str
,List[str]
, List[Dict[str, str]], orList[List[Dict[str, str]]]
) — One or several prompts (or one list of prompts) to complete. If strings or a list of string are passed, this pipeline will continue each prompt. Alternatively, a “chat”, in the form of a list of dicts with “role” and “content” keys, can be passed, or a list of such chats. When chats are passed, the model’s chat template will be used to format them before passing them to the model. - return_tensors (
bool
, optional, defaults toFalse
) — Whether or not to return the tensors of predictions (as token indices) in the outputs. If set toTrue
, the decoded text is not returned. - return_text (
bool
, optional, defaults toTrue
) — Whether or not to return the decoded texts in the outputs. - return_full_text (
bool
, optional, defaults toTrue
) — If set toFalse
only added text is returned, otherwise the full text is returned. Only meaningful if return_text is set to True. - clean_up_tokenization_spaces (
bool
, optional, defaults toTrue
) — Whether or not to clean up the potential extra spaces in the text output. - continue_final_message(
bool
, optional) — This indicates that you want the model to continue the last message in the input chat rather than starting a new one, allowing you to “prefill” its response. By default this isTrue
when the final message in the input chat has theassistant
role andFalse
otherwise, but you can manually override that behaviour by setting this flag. - prefix (
str
, optional) — Prefix added to prompt. - handle_long_generation (
str
, optional) — By default, this pipelines does not handle long generation (ones that exceed in one form or the other the model maximum length). There is no perfect way to adress this (more info :https://github.com/huggingface/transformers/issues/14033#issuecomment-948385227). This provides common strategies to work around that problem depending on your use case.None
: default strategy where nothing in particular happens"hole"
: Truncates left of input, and leaves a gap wide enough to let generation happen (might truncate a lot of the prompt and not suitable when generation exceed the model capacity)
- generate_kwargs (
dict
, optional) — Additional keyword arguments to pass along to the generate method of the model (see the generate method corresponding to your framework here).
Returns
A list or a list of lists of dict
Returns one of the following dictionaries (cannot return a combination
of both generated_text
and generated_token_ids
):
- generated_text (
str
, present whenreturn_text=True
) — The generated text. - generated_token_ids (
torch.Tensor
ortf.Tensor
, present whenreturn_tensors=True
) — The token ids of the generated text.
Complete the prompt(s) given as inputs.
Text2TextGenerationPipeline
class transformers.Text2TextGenerationPipeline
< source >( *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text.
Pipeline for text to text generation using seq2seq models.
Example:
>>> from transformers import pipeline
>>> generator = pipeline(model="mrm8488/t5-base-finetuned-question-generation-ap")
>>> generator(
... "answer: Manuel context: Manuel has created RuPERTa-base with the support of HF-Transformers and Google"
... )
[{'generated_text': 'question: Who created the RuPERTa-base?'}]
Learn more about the basics of using a pipeline in the pipeline tutorial. You can pass text generation parameters to this pipeline to control stopping criteria, decoding strategy, and more. Learn more about text generation parameters in Text generation strategies and Text generation.
This Text2TextGenerationPipeline pipeline can currently be loaded from pipeline() using the following task
identifier: "text2text-generation"
.
The models that this pipeline can use are models that have been fine-tuned on a translation task. See the up-to-date list of available models on huggingface.co/models. For a list of available parameters, see the following documentation
Usage:
text2text_generator = pipeline("text2text-generation")
text2text_generator("question: What is 42 ? context: 42 is the answer to life, the universe and everything")
__call__
< source >( *args **kwargs ) → A list or a list of list of dict
Parameters
- args (
str
orList[str]
) — Input text for the encoder. - return_tensors (
bool
, optional, defaults toFalse
) — Whether or not to include the tensors of predictions (as token indices) in the outputs. - return_text (
bool
, optional, defaults toTrue
) — Whether or not to include the decoded texts in the outputs. - clean_up_tokenization_spaces (
bool
, optional, defaults toFalse
) — Whether or not to clean up the potential extra spaces in the text output. - truncation (
TruncationStrategy
, optional, defaults toTruncationStrategy.DO_NOT_TRUNCATE
) — The truncation strategy for the tokenization within the pipeline.TruncationStrategy.DO_NOT_TRUNCATE
(default) will never truncate, but it is sometimes desirable to truncate the input to fit the model’s max_length instead of throwing an error down the line. generate_kwargs — Additional keyword arguments to pass along to the generate method of the model (see the generate method corresponding to your framework here).
Returns
A list or a list of list of dict
Each result comes as a dictionary with the following keys:
- generated_text (
str
, present whenreturn_text=True
) — The generated text. - generated_token_ids (
torch.Tensor
ortf.Tensor
, present whenreturn_tensors=True
) — The token ids of the generated text.
Generate the output text(s) using text(s) given as inputs.
Checks whether there might be something wrong with given input with regard to the model.
TokenClassificationPipeline
class transformers.TokenClassificationPipeline
< source >( args_parser = <transformers.pipelines.token_classification.TokenClassificationArgumentHandler object at 0x7fbeb1559450> *args **kwargs )
Parameters
- model (PreTrainedModel or TFPreTrainedModel) — The model that will be used by the pipeline to make predictions. This needs to be a model inheriting from PreTrainedModel for PyTorch and TFPreTrainedModel for TensorFlow.
- tokenizer (PreTrainedTokenizer) — The tokenizer that will be used by the pipeline to encode data for the model. This object inherits from PreTrainedTokenizer.
- modelcard (
str
orModelCard
, optional) — Model card attributed to the model for this pipeline. - framework (
str
, optional) — The framework to use, either"pt"
for PyTorch or"tf"
for TensorFlow. The specified framework must be installed.If no framework is specified, will default to the one currently installed. If no framework is specified and both frameworks are installed, will default to the framework of the
model
, or to PyTorch if no model is provided. - task (
str
, defaults to""
) — A task-identifier for the pipeline. - num_workers (
int
, optional, defaults to 8) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the number of workers to be used. - batch_size (
int
, optional, defaults to 1) — When the pipeline will use DataLoader (when passing a dataset, on GPU for a Pytorch model), the size of the batch to use, for inference this is not always beneficial, please read Batching with pipelines . - args_parser (ArgumentHandler, optional) — Reference to the object in charge of parsing supplied pipeline parameters.
- device (
int
, optional, defaults to -1) — Device ordinal for CPU/GPU supports. Setting this to -1 will leverage CPU, a positive will run the model on the associated CUDA device id. You can pass nativetorch.device
or astr
too - torch_dtype (
str
ortorch.dtype
, optional) — Sent directly asmodel_kwargs
(just a simpler shortcut) to use the available precision for this model (torch.float16
,torch.bfloat16
, … or"auto"
) - binary_output (
bool
, optional, defaults toFalse
) — Flag indicating if the output the pipeline should happen in a serialized format (i.e., pickle) or as the raw output data e.g. text. - ignore_labels (
List[str]
, defaults to["O"]
) — A list of labels to ignore. - grouped_entities (
bool
, optional, defaults toFalse
) — DEPRECATED, useaggregation_strategy
instead. Whether or not to group the tokens corresponding to the same entity together in the predictions or not. - stride (
int
, optional) — If stride is provided, the pipeline is applied on all the text. The text is split into chunks of size model_max_length. Works only with fast tokenizers andaggregation_strategy
different fromNONE
. The value of this argument defines the number of overlapping tokens between chunks. In other words, the model will shift forward bytokenizer.model_max_length - stride
tokens each step. - aggregation_strategy (
str
, optional, defaults to"none"
) — The strategy to fuse (or not) tokens based on the model prediction.- “none” : Will simply not do any aggregation and simply return raw results from the model
- “simple” : Will attempt to group entities following the default schema. (A, B-TAG), (B, I-TAG), (C, I-TAG), (D, B-TAG2) (E, B-TAG2) will end up being [{“word”: ABC, “entity”: “TAG”}, {“word”: “D”, “entity”: “TAG2”}, {“word”: “E”, “entity”: “TAG2”}] Notice that two consecutive B tags will end up as different entities. On word based languages, we might end up splitting words undesirably : Imagine Microsoft being tagged as [{“word”: “Micro”, “entity”: “ENTERPRISE”}, {“word”: “soft”, “entity”: “NAME”}]. Look for FIRST, MAX, AVERAGE for ways to mitigate that and disambiguate words (on languages that support that meaning, which is basically tokens separated by a space). These mitigations will only work on real words, “New york” might still be tagged with two different entities.
- “first” : (works only on word based models) Will use the
SIMPLE
strategy except that words, cannot end up with different tags. Words will simply use the tag of the first token of the word when there is ambiguity. - “average” : (works only on word based models) Will use the
SIMPLE
strategy except that words, cannot end up with different tags. scores will be averaged first across tokens, and then the maximum label is applied. - “max” : (works only on word based models) Will use the
SIMPLE
strategy except that words, c