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
73
```bash
pip install torch
74
75
76
```
</pt>
<tf>
77

78
```bash
79
80
pip install tensorflow
```
81
82
</tf>
</frameworkcontent>
83
84
85
86
87
88

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

```py
>>> from transformers import pipeline

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

92
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:
93
94

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

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

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

```bash
104
pip install datasets
105
106
107
108
109
110
111
112
```

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

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

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="es-ES", 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贸 `jonatasgrosman/wav2vec2-large-xlsr-53-spanish`.
127
128

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

132
133
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:
134
135

```py
136
137
>>> resultado = reconocedor_de_voz(dataset[:4]["audio"])
>>> print([d["text"] for d in resultado])
138
['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']
139
140
141
142
```

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.

143
### Usa otro modelo y otro tokenizador en el pipeline
144

145
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!
146
147
148
149
150

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

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

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

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

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
213
>>> encoding = tokenizer("Estamos muy felices de mostrarte la biblioteca de 馃 Transformers.")
214
>>> print(encoding)
215
216
217
{'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]}
218
219
220
221
222
223
224
225
226
```

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
237
```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",
... )
238
239
240
```
</pt>
<tf>
241

242
```py
243
244
245
246
247
248
249
250
>>> 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",
... )
```
251
252
</tf>
</frameworkcontent>
253
254
255
256
257

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

### AutoModel

258
259
260
<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`]:
261
262
263
264
265
266
267
268
269
270
271
272
273
274

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

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

```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>)
290
291
292
293
294
295
296
```
</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
297

298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
>>> 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
316
317
318
>>> import tensorflow as tf

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

<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

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

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

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

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

</pt>

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

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

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

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

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

382
383
<frameworkcontent>
<pt>
384

385
386
387
388
389
```py
>>> from transformers import AutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(tf_save_directory)
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(tf_save_directory, from_tf=True)
390
391
392
```
</pt>
<tf>
393

394
```py
395
396
397
398
399
>>> from transformers import TFAutoModel

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