quicktour.md 17.3 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
<!--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.
11
12
13
14

鈿狅笍 Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
rendered properly in your Markdown viewer.

15
16
-->

Omar U. Espejel's avatar
Omar U. Espejel committed
17
# Tour r谩pido
18
19
20
21
22
23
24

[[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>

Omar U. Espejel's avatar
Omar U. Espejel committed
25
Todos los ejemplos de c贸digo presentados en la documentaci贸n tienen un bot贸n arriba a la derecha para elegir si quieres ocultar o mostrar el c贸digo en Pytorch o TensorFlow.
26
27
28
29
30
31
32
33
34
35
36
37
38
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**:
39
40
41
42
43
44
45
46
* An谩lisis de Sentimiento (Sentiment Analysis, en ingl茅s): clasifica la polaridad de un texto dado.
* Generaci贸n de Texto (Text Generation, en ingl茅s): genera texto a partir de un input dado.
* Reconocimiento de Entidades (Name Entity Recognition o NER, en ingl茅s): etiqueta cada palabra con la entidad que representa (persona, fecha, ubicaci贸n, etc.).
* Responder Preguntas (Question answering, en ingl茅s): extrae la respuesta del contexto dado un contexto y una pregunta.
* Rellenar M谩scara (Fill-mask, en ingl茅s): rellena el espacio faltante dado un texto con palabras enmascaradas.
* Resumir (Summarization, en ingl茅s): genera un resumen de una secuencia larga de texto o un documento.
* Traducci贸n (Translation, en ingl茅s): traduce un texto a otro idioma.
* Extracci贸n de Caracter铆sticas (Feature Extraction, en ingl茅s): crea una representaci贸n tensorial del texto.
47
48

**Imagen**:
49
50
51
* Clasificaci贸n de Im谩genes (Image Classification, en ingl茅s): clasifica una imagen.
* Segmentaci贸n de Im谩genes (Image Segmentation, en ingl茅s): clasifica cada pixel de una imagen.
* Detecci贸n de Objetos (Object Detection, en ingl茅s): detecta objetos dentro de una imagen.
52
53

**Audio**:
54
55
* Clasificaci贸n de Audios (Audio Classification, en ingl茅s): asigna una etiqueta a un segmento de audio.
* Reconocimiento de Voz Autom谩tico (Automatic Speech Recognition o ASR, en ingl茅s): transcribe datos de audio a un texto.
56
57
58
59
60
61
62
63
64
65
66
67
68

<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:

69
70
<frameworkcontent>
<pt>
71
72
```bash
pip install torch
73
74
75
76
```
</pt>
<tf>
```bash
77
78
pip install tensorflow
```
79
80
</tf>
</frameworkcontent>
81
82
83
84
85
86

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

```py
>>> from transformers import pipeline

87
>>> clasificador = pipeline("sentiment-analysis", model="pysentimiento/robertuito-sentiment-analysis")
88
89
```

90
El pipeline descarga y almacena en cach茅 el [modelo preentrenado](https://huggingface.co/pysentimiento/robertuito-sentiment-analysis) y tokeniza para an谩lisis de sentimiento. Si no hubieramos elegido un modelo el pipeline habr铆a elegido uno por defecto. Ahora puedes usar `clasificador` en tu texto objetivo:
91
92

```py
93
>>> clasificador("Estamos muy felices de mostrarte la biblioteca de 馃 Transformers.")
94
[{'label': 'POS', 'score': 0.9320}]
95
96
```

97
Para m谩s de un enunciado, entrega una lista al [`pipeline`] que devolver谩 una lista de diccionarios:
98
99
100
101

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

```bash
102
pip install datasets
103
104
105
106
107
108
109
110
```

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

111
112
113
>>> reconocedor_de_voz = pipeline(
...     "automatic-speech-recognition", model="jonatasgrosman/wav2vec2-large-xlsr-53-spanish", device=0
... )
114
115
```

116
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):
117
118

```py
119
>>> from datasets import load_dataset, Audio
120

121
>>> dataset = load_dataset("PolyAI/minds14", name="es-ES", split="train")  # doctest: +IGNORE_RESULT
122
123
```

124
Debemos asegurarnos de que la frecuencia de muestreo del conjunto de datos coincide con la frecuencia de muestreo con la que se entren贸 `jonatasgrosman/wav2vec2-large-xlsr-53-spanish`.
125
126

```py
127
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=reconocedor_de_voz.feature_extractor.sampling_rate))
128
129
```

130
131
Los archivos de audio se cargan y remuestrean autom谩ticamente cuando llamamos a la columna `"audio"`.
Extraigamos las matrices de onda cruda (raw waveform, en ingl茅s) de las primeras 4 muestras y pas茅mosla como una lista al pipeline:
132
133

```py
134
135
>>> resultado = reconocedor_de_voz(dataset[:4]["audio"])
>>> print([d["text"] for d in resultado])
136
['ahora buenas eh a ver tengo un problema con vuestra aplicaci贸n resulta que que quiero hacer una transferencia bancaria a una cuenta conocida pero me da error la aplicaci贸n a ver que a ver que puede ser', 'la aplicaci贸n no cargue saldo de mi nueva cuenta', 'hola tengo un problema con la aplicaci贸n no carga y y tampoco veo que carga el saldo de mi cuenta nueva dice que la aplicaci贸n est谩 siendo reparada y ahora no puedo acceder a mi cuenta no necesito inmediatamente', 'hora buena la aplicaci贸n no se carga la vida no carga el saldo de mi cuenta nueva dice que la villadenta siendo reparada y oro no puedo hacer a mi cuenta']
137
138
139
140
```

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.

141
### Usa otro modelo y otro tokenizador en el pipeline
142

143
El [`pipeline`] puede acomodarse 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!
144
145
146
147
148

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

149
150
<frameworkcontent>
<pt>
151
152
153
154
155
156
157
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)
158
159
160
161
162
163
164
165
```

</pt>

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

```py
166
167
168
169
170
171
>>> from transformers import AutoTokenizer, TFAutoModelForSequenceClassification

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

172
173
174
</tf>
</frameworkcontent>

175
176
177
178
179
180
181
182
183
184
185
186
187
188
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"/>

Omar U. Espejel's avatar
Omar U. Espejel committed
189
Por debajo, 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`].
190
191
192
193
194
195
196
197
198
199
200
201

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

202
203
>>> nombre_del_modelo = "nlptown/bert-base-multilingual-uncased-sentiment"
>>> tokenizer = AutoTokenizer.from_pretrained(nombre_del_modelo)
204
205
206
207
208
209
210
```

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
211
>>> encoding = tokenizer("Estamos muy felices de mostrarte la biblioteca de 馃 Transformers.")
212
>>> print(encoding)
213
214
215
{'input_ids': [101, 10602, 14000, 13653, 43353, 10107, 10102, 47201, 10218, 10106, 18283, 10102, 100, 58263, 119, 102],
 'token_type_ids': [0, 0, 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, 1, 1]}
216
217
218
219
220
221
222
223
224
```

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:

225
226
<frameworkcontent>
<pt>
227
228
229
230
231
232
233
234
```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",
... )
235
236
237
238
```
</pt>
<tf>
```py
239
240
241
242
243
244
245
246
>>> 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",
... )
```
247
248
</tf>
</frameworkcontent>
249
250
251
252
253

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

### AutoModel

254
255
256
<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`]:
257
258
259
260
261
262
263
264
265
266
267
268
269
270

```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>

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

```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>)
286
287
288
289
290
291
292
```
</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
293

294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
>>> 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
312
313
314
>>> import tensorflow as tf

>>> tf_predictions = tf.nn.softmax(tf_outputs.logits, axis=-1)
315
>>> print(tf.math.round(tf_predictions * 10**4) / 10**4)
316
tf.Tensor(
317
318
[[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)
319
```
320
321
</tf>
</frameworkcontent>
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340

<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

341
342
<frameworkcontent>
<pt>
343
Una vez que se haya hecho fine-tuning a tu modelo puedes guardarlo con tu tokenizador usando [`PreTrainedModel.save_pretrained`]:
344
345
346
347
348

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

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

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

</pt>

<tf>
360
Una vez que se haya hecho fine-tuning a tu modelo puedes guardarlo con tu tokenizador usando [`TFPreTrainedModel.save_pretrained`]:
361
362

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

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

```py
>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained("./tf_save_pretrained")
```
373
374
</tf>
</frameworkcontent>
375

376
Una caracter铆stica particularmente interesante 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:
377

378
379
<frameworkcontent>
<pt>
380
381
382
383
384
```py
>>> from transformers import AutoModel

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

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