quicktour.mdx 16.7 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<!--Copyright 2022 The HuggingFace Team. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.
-->

# Quick tour

[[open-in-colab]]

隆Entra en marcha con los 馃 Transformers! Comienza usando [`pipeline`] para una inferencia veloz, carga un modelo preentrenado y un tokenizador con una [AutoClass](./model_doc/auto) para resolver tu tarea de texto, visi贸n o audio.

<Tip>

Todos los ejemplos de c贸digo presentados en la documentaci贸n tienen un bot贸n arriba a la izquierda para elegir entre Pytorch y TensorFlow.
Si no fuese as铆, se espera que el c贸digo funcione para ambos backends sin ning煤n cambio.

</Tip>

## Pipeline

[`pipeline`] es la forma m谩s f谩cil de usar un modelo preentrenado para una tarea dada.

<Youtube id="tiZFewofSLM"/>

El [`pipeline`] soporta muchas tareas comunes listas para usar:

**Texto**:
* An谩lisis de Sentimientos: clasifica la polaridad de un texto dado.
* Generaci贸n de texto (solo en ingl茅s): genera texto a partir de un input dado.
* Name entity recognition (NER): etiqueta cada palabra con la entidad que representa (persona, fecha, ubicaci贸n, etc.).
* Responder preguntas: extrae la respuesta del contexto dado un contexto y una pregunta.
* Fill-mask: rellena el espacio faltante dado un texto con palabras enmascaradas.
* Summarization: genera un resumen de una secuencia larga de texto o un documento.
* Traducci贸n: traduce un texto a otro idioma.
* Extracci贸n de caracter铆sticas: crea una representaci贸n tensorial del texto.

**Imagen**:
* Clasificaci贸n de im谩genes: clasifica una imagen.
* Segmentaci贸n de im谩genes: clasifica cada pixel de una imagen.
* Detecci贸n de objetos: detecta objetos dentro de una imagen.

**Audio**:
* Clasificaci贸n de audios: asigna una etiqueta a un segmento de audio.
* Automatic speech recognition (ASR): transcribe datos de audio a un texto.

<Tip>

Para m谩s detalles acerca del [`pipeline`] y tareas asociadas, consulta la documentaci贸n [aqu铆](./main_classes/pipelines).

</Tip>

### Uso del Pipeline

En el siguiente ejemplo, usar谩s el [`pipeline`] para an谩lisis de sentimiento.

Instala las siguientes dependencias si a煤n no lo has hecho:

65
66
<frameworkcontent>
<pt>
67
68
```bash
pip install torch
69
70
71
72
```
</pt>
<tf>
```bash
73
74
pip install tensorflow
```
75
76
</tf>
</frameworkcontent>
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

Importa [`pipeline`] y especifica la tarea que deseas completar:

```py
>>> from transformers import pipeline

>>> classifier = pipeline("sentiment-analysis")
```

El pipeline descarga y almacena en cach茅 un [modelo preentrenado](https://huggingface.co/distilbert-base-uncased-finetuned-sst-2-english) por defecto y tokeniza para an谩lisis de sentimiento. Ahora puedes usar `classifier` en tu texto objetivo:

```py
>>> classifier("We are very happy to show you the 馃 Transformers library.")
[{'label': 'POSITIVE', 'score': 0.9998}]
```

Para m谩s de un enunciado entrega una lista de frases al [`pipeline`] que devolver谩 una lista de diccionarios:

```py
>>> results = classifier(["We are very happy to show you the 馃 Transformers library.", "We hope you don't hate it."])
>>> for result in results:
...     print(f"label: {result['label']}, with score: {round(result['score'], 4)}")
label: POSITIVE, with score: 0.9998
label: NEGATIVE, with score: 0.5309
```

El [`pipeline`] tambi茅n puede iterar sobre un dataset entero. Comienza instalando la biblioteca [馃 Datasets](https://huggingface.co/docs/datasets/):

```bash
106
pip install datasets
107
108
109
110
111
112
113
114
115
116
117
```

Crea un [`pipeline`] con la tarea que deseas resolver y el modelo que quieres usar. Coloca el par谩metro `device` a `0` para poner los tensores en un dispositivo CUDA:

```py
>>> import torch
>>> from transformers import pipeline

>>> speech_recognizer = pipeline("automatic-speech-recognition", model="facebook/wav2vec2-base-960h", device=0)
```

118
A continuaci贸n, carga el dataset (ve 馃 Datasets [Quick Start](https://huggingface.co/docs/datasets/quickstart.html) para m谩s detalles) sobre el que quisieras iterar. Por ejemplo, vamos a cargar el dataset [MInDS-14](https://huggingface.co/datasets/PolyAI/minds14):
119
120

```py
121
>>> from datasets import load_dataset, Audio
122

123
>>> dataset = load_dataset("PolyAI/minds14", name="en-US", split="train")  # doctest: +IGNORE_RESULT
124
125
```

126
Debemos asegurarnos de que la frecuencia de muestreo del conjunto de datos coincide con la frecuencia de muestreo con la que se entren贸 `facebook/wav2vec2-base-960h`.
127
128

```py
129
130
131
132
133
134
135
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=speech_recognizer.feature_extractor.sampling_rate))
```

Los archivos de audio se cargan y remuestrean autom谩ticamente cuando se llama a la columna `"audio"`.
Extraigamos las matrices de forma de onda cruda de las primeras 4 muestras y pas茅mosla como una lista al pipeline:

```py
136
137
138
>>> result = speech_recognizer(dataset[:4]["audio"])
>>> print([d["text"] for d in result])
['I WOULD LIKE TO SET UP A JOINT ACCOUNT WITH MY PARTNER HOW DO I PROCEED WITH DOING THAT', "FONDERING HOW I'D SET UP A JOIN TO HET WITH MY WIFE AND WHERE THE AP MIGHT BE", "I I'D LIKE TOY SET UP A JOINT ACCOUNT WITH MY PARTNER I'M NOT SEEING THE OPTION TO DO IT ON THE APSO I CALLED IN TO GET SOME HELP CAN I JUST DO IT OVER THE PHONE WITH YOU AND GIVE YOU THE INFORMATION OR SHOULD I DO IT IN THE AP AND I'M MISSING SOMETHING UQUETTE HAD PREFERRED TO JUST DO IT OVER THE PHONE OF POSSIBLE THINGS", 'HOW DO I TURN A JOIN A COUNT']
139
140
141
142
143
144
145
146
147
148
149
150
```

Para un dataset m谩s grande, donde los inputs son de mayor tama帽o (como en habla/audio o visi贸n), querr谩s pasar un generador en lugar de una lista que carga todos los inputs en memoria. Ve la [documentaci贸n del pipeline](./main_classes/pipelines) para m谩s informaci贸n.

### Use otro modelo y otro tokenizador en el pipeline

El [`pipeline`] puede adaptarse a cualquier modelo del [Model Hub](https://huggingface.co/models) haciendo m谩s f谩cil adaptar el [`pipeline`] para otros casos de uso. Por ejemplo, si quisieras un modelo capaz de manejar texto en franc茅s, usa los tags en el Model Hub para filtrar entre los modelos apropiados. El resultado mejor filtrado devuelve un [modelo BERT](https://huggingface.co/nlptown/bert-base-multilingual-uncased-sentiment) multilingual fine-tuned para el an谩lisis de sentimiento. Genial, 隆vamos a usar este modelo!

```py
>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
```

151
152
<frameworkcontent>
<pt>
153
154
155
156
157
158
159
Usa [`AutoModelForSequenceClassification`] y ['AutoTokenizer'] para cargar un modelo preentrenado y un tokenizador asociado (m谩s en un `AutoClass` debajo):

```py
>>> from transformers import AutoTokenizer, AutoModelForSequenceClassification

>>> model = AutoModelForSequenceClassification.from_pretrained(model_name)
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)
160
161
162
163
164
165
166
167
```

</pt>

<tf>
Usa [`TFAutoModelForSequenceClassification`] y ['AutoTokenizer'] para cargar un modelo preentrenado y un tokenizador asociado (m谩s en un `TFAutoClass` debajo):

```py
168
169
170
171
172
173
>>> from transformers import AutoTokenizer, TFAutoModelForSequenceClassification

>>> model = TFAutoModelForSequenceClassification.from_pretrained(model_name)
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)
```

174
175
176
</tf>
</frameworkcontent>

177
178
179
180
181
182
183
184
185
186
187
188
189
190
Despu茅s puedes especificar el modelo y el tokenizador en el [`pipeline`], y aplicar el `classifier` en tu texto objetivo:

```py
>>> classifier = pipeline("sentiment-analysis", model=model, tokenizer=tokenizer)
>>> classifier("Nous sommes tr猫s heureux de vous pr茅senter la biblioth猫que 馃 Transformers.")
[{'label': '5 stars', 'score': 0.7273}]
```

Si no pudieras encontrar el modelo para tu caso respectivo de uso necesitar谩s ajustar un modelo preentrenado a tus datos. Mira nuestro [tutorial de fine-tuning](./training) para aprender c贸mo. Finalmente, despu茅s de que has ajustado tu modelo preentrenado, 隆por favor considera compartirlo (ve el tutorial [aqu铆](./model_sharing)) con la comunidad en el Model Hub para democratizar el NLP! 馃

## AutoClass

<Youtube id="AhChOFRegn4"/>

191
Debajo del cap贸, las clases [`AutoModelForSequenceClassification`] y [`AutoTokenizer`] trabajan juntas para dar poder al [`pipeline`]. Una [AutoClass](./model_doc/auto) es un atajo que autom谩ticamente recupera la arquitectura de un modelo preentrenado con su nombre o el path. S贸lo necesitar谩s seleccionar el `AutoClass` apropiado para tu tarea y tu tokenizador asociado con [`AutoTokenizer`].
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226

Regresemos a nuestro ejemplo y veamos c贸mo puedes usar el `AutoClass` para reproducir los resultados del [`pipeline`].

### AutoTokenizer

Un tokenizador es responsable de procesar el texto a un formato que sea entendible para el modelo. Primero, el tokenizador separar谩 el texto en palabras llamadas *tokens*. Hay m煤ltiples reglas que gobiernan el proceso de tokenizaci贸n incluyendo el c贸mo separar una palabra y en qu茅 nivel (aprende m谩s sobre tokenizaci贸n [aqu铆](./tokenizer_summary)). Lo m谩s importante es recordar que necesitar谩s instanciar el tokenizador con el mismo nombre del modelo para asegurar que est谩s usando las mismas reglas de tokenizaci贸n con las que el modelo fue preentrenado.

Carga un tokenizador con [`AutoTokenizer`]:

```py
>>> from transformers import AutoTokenizer

>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)
```

Despu茅s, el tokenizador convierte los tokens a n煤meros para construir un tensor que servir谩 como input para el modelo. Esto es conocido como el *vocabulario* del modelo.

Pasa tu texto al tokenizador:

```py
>>> encoding = tokenizer("We are very happy to show you the 馃 Transformers library.")
>>> print(encoding)
{'input_ids': [101, 11312, 10320, 12495, 19308, 10114, 11391, 10855, 10103, 100, 58263, 13299, 119, 102],
 'token_type_ids': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
 'attention_mask': [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]}
```

El tokenizador devolver谩 un diccionario conteniendo:

* [input_ids](./glossary#input-ids): representaciones num茅ricas de los tokens.
* [atttention_mask](.glossary#attention-mask): indica cu谩les tokens deben ser atendidos.

Como con el [`pipeline`], el tokenizador aceptar谩 una lista de inputs. Adem谩s, el tokenizador tambi茅n puede rellenar (pad, en ingl茅s) y truncar el texto para devolver un lote (batch, en ingl茅s) de longitud uniforme:

227
228
<frameworkcontent>
<pt>
229
230
231
232
233
234
235
236
```py
>>> pt_batch = tokenizer(
...     ["We are very happy to show you the 馃 Transformers library.", "We hope you don't hate it."],
...     padding=True,
...     truncation=True,
...     max_length=512,
...     return_tensors="pt",
... )
237
238
239
240
```
</pt>
<tf>
```py
241
242
243
244
245
246
247
248
>>> tf_batch = tokenizer(
...     ["We are very happy to show you the 馃 Transformers library.", "We hope you don't hate it."],
...     padding=True,
...     truncation=True,
...     max_length=512,
...     return_tensors="tf",
... )
```
249
250
</tf>
</frameworkcontent>
251
252
253
254
255

Lee el tutorial de [preprocessing](./preprocessing) para m谩s detalles acerca de la tokenizaci贸n.

### AutoModel

256
257
258
<frameworkcontent>
<pt>
馃 Transformers provee una forma simple y unificada de cargar tus instancias preentrenadas. Esto significa que puedes cargar un [`AutoModel`] como cargar铆as un [`AutoTokenizer`]. La 煤nica diferencia es seleccionar el [`AutoModel`] correcto para la tarea. Ya que est谩s clasificando texto, o secuencias, carga [`AutoModelForSequenceClassification`]:
259
260
261
262
263
264
265
266
267
268
269
270
271
272

```py
>>> from transformers import AutoModelForSequenceClassification

>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(model_name)
```

<Tip>

Ve el [task summary](./task_summary) para revisar qu茅 clase del [`AutoModel`] deber铆as usar para cada tarea.

</Tip>

273
Ahora puedes pasar tu lote (batch) preprocesado de inputs directamente al modelo. Solo tienes que desempacar el diccionario a帽adiendo `**`:
274
275
276
277
278
279
280
281
282
283
284
285
286
287

```py
>>> pt_outputs = pt_model(**pt_batch)
```

El modelo producir谩 las activaciones finales en el atributo `logits`. Aplica la funci贸n softmax a `logits` para obtener las probabilidades:

```py
>>> from torch import nn

>>> pt_predictions = nn.functional.softmax(pt_outputs.logits, dim=-1)
>>> print(pt_predictions)
tensor([[0.0021, 0.0018, 0.0115, 0.2121, 0.7725],
        [0.2084, 0.1826, 0.1969, 0.1755, 0.2365]], grad_fn=<SoftmaxBackward0>)
288
289
290
291
292
293
294
```
</pt>
<tf>
馃 Transformers provee una forma simple y unificada de cargar tus instancias preentrenadas. Esto significa que puedes cargar un [`TFAutoModel`] como cargar铆as un [`AutoTokenizer`]. La 煤nica diferencia es seleccionar el [`TFAutoModel`] correcto para la tarea. Ya que est谩s clasificando texto, o secuencias, carga [`TFAutoModelForSequenceClassification`]:

```py
>>> from transformers import TFAutoModelForSequenceClassification
295

296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained(model_name)
```

<Tip>
  Ve el [task summary](./task_summary) para revisar qu茅 clase del [`AutoModel`]
  deber铆as usar para cada tarea.
</Tip>

Ahora puedes pasar tu lote preprocesado de inputs directamente al modelo pasando las llaves del diccionario directamente a los tensores:

```py
>>> tf_outputs = tf_model(tf_batch)
```

El modelo producir谩 las activaciones finales en el atributo `logits`. Aplica la funci贸n softmax a `logits` para obtener las probabilidades:

```py
314
315
316
>>> import tensorflow as tf

>>> tf_predictions = tf.nn.softmax(tf_outputs.logits, axis=-1)
317
>>> print(tf.math.round(tf_predictions * 10**4) / 10**4)
318
tf.Tensor(
319
320
[[0.0021 0.0018 0.0116 0.2121 0.7725]
 [0.2084 0.1826 0.1969 0.1755  0.2365]], shape=(2, 5), dtype=float32)
321
```
322
323
</tf>
</frameworkcontent>
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342

<Tip>

Todos los modelos de 馃 Transformers (PyTorch o TensorFlow) producir谩n los tensores *antes* de la funci贸n de activaci贸n
final (como softmax) porque la funci贸n de activaci贸n final es com煤nmente fusionada con la p茅rdida.

</Tip>

Los modelos son [`torch.nn.Module`](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) o [`tf.keras.Model`](https://www.tensorflow.org/api_docs/python/tf/keras/Model) est谩ndares as铆 que podr谩s usarlos en tu training loop usual. Sin embargo, para facilitar las cosas, 馃 Transformers provee una clase [`Trainer`] para PyTorch que a帽ade funcionalidades para entrenamiento distribuido, precici贸n mixta, y m谩s. Para TensorFlow, puedes usar el m茅todo `fit` desde [Keras](https://keras.io/). Consulta el [tutorial de entrenamiento](./training) para m谩s detalles.

<Tip>

Los outputs del modelo de 馃 Transformers son dataclasses especiales por lo que sus atributos pueden ser completados en un IDE.
Los outputs del modelo tambi茅n se comportan como tuplas o diccionarios (e.g., puedes indexar con un entero, un slice o una cadena) en cuyo caso los atributos que son `None` son ignorados.

</Tip>

### Guarda un modelo

343
344
<frameworkcontent>
<pt>
345
346
347
348
349
350
Una vez que tu modelo est茅 fine-tuned puedes guardarlo con tu tokenizador usando [`PreTrainedModel.save_pretrained`]:

```py
>>> pt_save_directory = "./pt_save_pretrained"
>>> tokenizer.save_pretrained(pt_save_directory)  # doctest: +IGNORE_RESULT
>>> pt_model.save_pretrained(pt_save_directory)
351
352
353
354
355
356
357
358
359
360
361
362
363
364
```

Cuando quieras usar el modelo otra vez c谩rgalo con [`PreTrainedModel.from_pretrained`]:

```py
>>> pt_model = AutoModelForSequenceClassification.from_pretrained("./pt_save_pretrained")
```

</pt>

<tf>
Una vez que tu modelo est茅 fine-tuned puedes guardarlo con tu tokenizador usando [`TFPreTrainedModel.save_pretrained`]:

```py
365
366
367
368
369
>>> tf_save_directory = "./tf_save_pretrained"
>>> tokenizer.save_pretrained(tf_save_directory)  # doctest: +IGNORE_RESULT
>>> tf_model.save_pretrained(tf_save_directory)
```

370
Cuando quieras usar el modelo otra vez c谩rgalo con [`TFPreTrainedModel.from_pretrained`]:
371
372
373
374

```py
>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained("./tf_save_pretrained")
```
375
376
</tf>
</frameworkcontent>
377
378
379

Una caracter铆stica particularmente cool de 馃 Transformers es la habilidad de guardar el modelo y cargarlo como un modelo de PyTorch o TensorFlow. El par谩metro `from_pt` o `from_tf` puede convertir el modelo de un framework al otro:

380
381
<frameworkcontent>
<pt>
382
383
384
385
386
```py
>>> from transformers import AutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(tf_save_directory)
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(tf_save_directory, from_tf=True)
387
388
389
390
```
</pt>
<tf>
```py
391
392
393
394
395
>>> from transformers import TFAutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(pt_save_directory)
>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained(pt_save_directory, from_pt=True)
```
396
397
</tf>
</frameworkcontent>