# Pipeline

El [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) es una API de inferencia simple pero potente, disponible de inmediato para una amplia variedad de tareas de aprendizaje automático con cualquier modelo del [Hub](https://hf.co/models) de Hugging Face.

Adapta el [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) a tu tarea mediante parámetros específicos, como añadir marcas de tiempo a un pipeline de reconocimiento automático de voz (ASR) para transcribir notas de reuniones. [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) admite GPUs, Apple Silicon y pesos de media precisión para acelerar la inferencia y ahorrar memoria.

Transformers tiene dos clases de pipeline: el [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) genérico y muchos pipelines específicos para cada tarea, como [TextGenerationPipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.TextGenerationPipeline). Cargue estos pipelines individuales estableciendo el identificador de la tarea en el parámetro `task` de [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline). Puede encontrar el identificador de la tarea de cada pipeline en su documentación de la API.

Cada tarea se configura para usar un modelo y un preprocesador preentrenados por defecto, pero esto se puede sobrescribir con el parámetro `model` si se desea utilizar un modelo diferente.

Por ejemplo, para usar [TextGenerationPipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.TextGenerationPipeline) con [Gemma 2](./model_doc/gemma2), establece `task="text-generation"` y `model="google/gemma-2-2b"`.

```py
from transformers import pipeline

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

Cuando tiene más de una entrada, páselas como una lista.

```py
from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

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

Esta guía le presentará el [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline), le mostrará sus características y le explicará cómo configurar sus diversos parámetros.

## Tareas

[Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) es compatible con muchas tareas de aprendizaje automático en distintas modalidades. Pasa una entrada adecuada a la pipeline y esta se encargará del resto.

A continuación se muestran algunos ejemplos de cómo usar [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) para diferentes tareas y modalidades.

```py
from transformers import pipeline

pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.'}
```

```py
from transformers import pipeline

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

```py
from transformers import pipeline

pipeline = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
pipeline(
    image="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg",
    question="What is in the image?",
)
[{'answer': 'statue of liberty'}]
```

## Parámetros

Como mínimo, [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) solo requiere un identificador de tarea, un modelo y la entrada adecuada. Sin embargo, hay muchos parámetros disponibles para configurar el pipeline, desde parámetros específicos de la tarea hasta la optimización del rendimiento.

Esta sección le presenta algunos de los parámetros más importantes.

### Dispositivo

[Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) es compatible con muchos tipos de hardware, incluidas GPUs, CPUs, Apple Silicon y más. Configure el tipo de hardware con el parámetro `device`. De forma predeterminada, cuando `device` no se establece, [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) coloca automáticamente el modelo en el primer acelerador disponible (GPU CUDA, Apple Silicon MPS, XPU, ...) y solo recurre a una CPU si no hay ninguno disponible. Pase `device="cpu"` para forzar su ejecución en una CPU.

Para ejecutar [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) en una GPU, establezca `device` en el id de dispositivo CUDA asociado. Por ejemplo, `device=0` se ejecuta en la primera GPU.

```py
from transformers import pipeline

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

También puedes dejar que [Accelerate](https://hf.co/docs/accelerate/index), una biblioteca para el entrenamiento distribuido, elija automáticamente cómo cargar y guardar los pesos del modelo en el dispositivo adecuado. Esto resulta especialmente útil si dispones de varios dispositivos. Accelerate carga y guarda los pesos del modelo primero en el dispositivo más rápido y, a continuación, transfiere los pesos a otros dispositivos (CPU, disco duro) según sea necesario. Establece `device_map="auto"` para que Accelerate elija el dispositivo.

> [!TIP]
> Asegúrate de que [Accelerate](https://hf.co/docs/accelerate/basic_tutorials/install) esté instalado.
>
> ```py
> !pip install -U accelerate
> ```

```py
from transformers import pipeline

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

Para ejecutar [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) en Apple silicon, establece `device="mps"`.

```py
from transformers import pipeline

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

### Inferencia por lotes

[Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) también puede procesar lotes de entradas con el parámetro `batch_size`. La inferencia por lotes puede mejorar la velocidad, especialmente en una GPU, pero no está garantizado. Otras variables, como el hardware, los datos y el propio modelo, pueden afectar si la inferencia por lotes mejora la velocidad. Por esta razón, la inferencia por lotes está deshabilitada de forma predeterminada.

En el ejemplo siguiente, cuando hay 4 entradas y `batch_size` está establecido en 2, [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) pasa al modelo un lote de 2 entradas a la vez.

```py
from transformers import pipeline
from accelerate import Accelerator

device = Accelerator().device

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

Otro buen caso de uso para la inferencia por lotes es el streaming de datos en [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline).

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

device = Accelerator().device

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

Tenga en cuenta las siguientes reglas generales para determinar si la inferencia por lotes puede ayudar a mejorar el rendimiento.

1. La única forma de estar seguro es medir el rendimiento en tu modelo, tus datos y tu hardware.
2. No realices inferencias por lotes si tienes restricciones de latencia (por ejemplo, un producto de inferencia en vivo).
3. No realices inferencias por lotes si estás usando una CPU.
4. No realices inferencia por lotes si no conoces el `sequence_length` de tus datos. Mide el rendimiento, aumenta `sequence_length` de forma iterativa e incluye comprobaciones de memoria insuficiente (OOM) para recuperarte de los fallos.
5. Realiza inferencia por lotes si tu `sequence_length` es regular y sigue aumentándola hasta que aparezca un error de OOM. Cuanto mayor sea la GPU, más útil resulta la inferencia por lotes.
6. Asegúrate de poder manejar errores de OOM si decides realizar inferencia por lotes.

### Parámetros específicos de la tarea

[Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) acepta cualquier parámetro que sea compatible con cada pipeline de tarea individual. Asegúrate de consultar cada pipeline de tarea individual para ver qué tipo de parámetros están disponibles. Si no encuentras un parámetro útil para tu caso de uso, no dudes en abrir un [issue](https://github.com/huggingface/transformers/issues/new?assignees=&labels=feature&template=feature-request.yml) en GitHub para solicitarlo.

Los ejemplos a continuación demuestran algunos de los parámetros específicos de la tarea disponibles.

Pasa el parámetro `return_timestamps="word"` a [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) para obtener el momento en que se pronunció cada palabra.

```py
from transformers import pipeline

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

Pasa `return_full_text=False` a [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) para devolver solo el texto generado en lugar del texto completo (el prompt y el texto generado).

[__call__()](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.TextGenerationPipeline.__call__) también admite argumentos de palabra clave adicionales del método [generate()](/docs/transformers/v5.23.0/es/main_classes/text_generation#transformers.GenerationMixin.generate). Para devolver más de una secuencia generada, establece `num_return_sequences` en un valor mayor que 1.

```py
from transformers import pipeline

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

## Lote de fragmentos

Hay casos en los que necesitas procesar los datos en bloques.

- para algunos tipos de datos, una única entrada (por ejemplo, un archivo de audio muy largo) puede necesitar dividirse en varias partes antes de poder procesarse
- para algunas tareas, como la clasificación zero-shot o la respuesta a preguntas, una sola entrada puede requerir múltiples pases hacia adelante, lo que puede causar problemas con el parámetro `batch_size`

La clase [ChunkPipeline](https://github.com/huggingface/transformers/blob/99e0ab6ed888136ea4877c6d8ab03690a1478363/src/transformers/pipelines/base.py#L1387) está diseñada para manejar estos casos de uso. Ambas clases de pipeline se utilizan de la misma manera, pero como [ChunkPipeline](https://github.com/huggingface/transformers/blob/99e0ab6ed888136ea4877c6d8ab03690a1478363/src/transformers/pipelines/base.py#L1387) puede manejar el batching de forma automática, no es necesario preocuparse por el número de pases hacia adelante que provocan las entradas. En su lugar, se puede optimizar `batch_size` de forma independiente a las entradas.

El siguiente ejemplo muestra en qué se diferencia de [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline).

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

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

## Conjuntos de datos grandes

Para la inferencia con conjuntos de datos grandes, puedes iterar directamente sobre el propio conjunto de datos. Esto evita asignar memoria de inmediato para todo el conjunto de datos y no necesitas preocuparte por crear lotes por tu cuenta. Prueba [inferencia por lotes](#batch-inference) con el parámetro `batch_size` para ver si mejora el rendimiento.

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

device = Accelerator().device

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

Otras formas de ejecutar inferencia en conjuntos de datos grandes con [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) incluyen el uso de un iterador o un generador.

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

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

## Modelos grandes

[Accelerate](https://hf.co/docs/accelerate/index) habilita algunas optimizaciones para ejecutar modelos grandes con [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline). Asegúrate de que Accelerate esté instalado primero.

```py
!pip install -U accelerate
```

La configuración `device_map="auto"` es útil para distribuir automáticamente el modelo primero en los dispositivos más rápidos (GPUs) y, si están disponibles, en otros dispositivos más lentos (CPU, disco duro).

[Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) admite pesos de media precisión (torch.float16), lo que puede ser significativamente más rápido y ahorrar memoria. La pérdida de rendimiento es despreciable para la mayoría de los modelos, especialmente para los más grandes. Si tu hardware lo permite, puedes habilitar torch.bfloat16 en su lugar para obtener un mayor rango.

> [!TIP]
> Las entradas se convierten internamente a torch.float16 y solo funciona con modelos que tienen un backend de PyTorch.

Por último, [Pipeline](/docs/transformers/v5.23.0/es/main_classes/pipelines#transformers.Pipeline) también acepta modelos cuantizados para reducir aún más el uso de memoria. Asegúrate de tener instalada la biblioteca [bitsandbytes](https://hf.co/docs/bitsandbytes/installation) primero y, a continuación, añade `quantization_config` a `model_kwargs` en el pipeline.

```py
import torch
from transformers import pipeline, BitsAndBytesConfig

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

