Transformers documentation
Contribución de modelos heredados
Contribución de modelos heredados
Prueba primero a añadir nuevos modelos con un enfoque más modular. Esto hace que sea mucho más fácil contribuir con un modelo a Transformers.
Muchos de los modelos de Transformers son aportados por desarrolladores e investigadores. Como proyecto de código abierto, estamos comprometidos a empoderar a la comunidad para que añada más modelos de forma activa e independiente.
Cuando añades un modelo a Transformers, aprenderás:
- más sobre las mejores prácticas de código abierto
- sobre la arquitectura de un modelo
- sobre los principios de diseño de Transformers
- cómo probar modelos grandes de manera eficiente
- cómo usar utilidades de Python como Black y Ruff para crear código limpio y legible
Es un proceso desafiante pero gratificante.
Esta guía te guiará paso a paso para añadir un modelo de ejemplo BrandNewLlama de PyTorch a Transformers. Antes de comenzar, es buena idea familiarizarte con la biblioteca.
Resumen de Transformers
Transformers es una biblioteca con una filosofía y decisiones de diseño propias y únicas. Estas elecciones nos permiten escalar y mantener Transformers de manera sostenible.
Obtén más información sobre nuestros principios de diseño en el documento Philosophy.
Algunas de estas decisiones de diseño son:
- composición > sobreabstracción
- el código duplicado no siempre es malo si mejora significativamente la legibilidad y la accesibilidad
- los archivos del modelo son autosuficientes y todo el código necesario del modelo se encuentra en el archivo
modeling_mymodel.py
Estas decisiones de diseño son importantes para todos los que interactúan con el modelo. Es más fácil de leer, comprender y modificar.
Esta sección describe cómo interactúan las clases de modelo y de configuración y el estilo de código de Transformers.
Modelo y configuración
Todos los modelos de Transformers heredan de una clase base PreTrainedModel y PreTrainedConfig. La configuración es el plano de los modelos.
Nunca hay más de dos niveles de abstracción para ningún modelo, con el fin de mantener el código legible. El modelo de ejemplo aquí, BrandNewLlama, hereda de BrandNewLlamaPreTrainedModel y PreTrainedModel. Es importante que un modelo nuevo dependa únicamente de PreTrainedModel para que pueda utilizar los métodos from_pretrained() y save_pretrained().
Otras funciones importantes, como el método forward, se definen en el archivo modeling.py.
Las cabezas de modelo específicas (por ejemplo, clasificación de secuencias o modelado de lenguaje) deben llamar al modelo base en la pasada hacia adelante en lugar de heredar de él, para mantener la abstracción baja.
Los nuevos modelos requieren una configuración, por ejemplo BrandNewLlamaConfig, que se almacena como un atributo de PreTrainedModel.
model = BrandNewLlamaModel.from_pretrained("username/brand_new_llama")
model.configPreTrainedConfig proporciona los métodos from_pretrained() y save_pretrained().
Cuando usas PreTrainedModel.save_pretrained(), se llama automáticamente a PreTrainedConfig.save_pretrained() para que el modelo y la configuración se guarden juntos.
Un modelo se guarda en un archivo model.safetensors y una configuración se guarda en un archivo config.json.
Estilo de código
Transformers prefiere un código limpio y legible a un estilo de código más abstracto. Algunas de las decisiones de estilo de código incluyen:
El código debe ser accesible para usuarios que no hablan inglés. Elija nombres de variables descriptivos y evite las abreviaturas. Por ejemplo, se prefiere “activation” sobre “act”. Los nombres de variables de una sola letra están fuertemente desaconsejados, a menos que se trate de un índice en un bucle for.
Se prefiere el código explícito, aunque sea más largo, al código más corto.
Evite subclasear nn.Sequential. En su lugar, subclasee nn.Module para que el código pueda depurarse rápidamente con declaraciones de impresión o puntos de interrupción.
Las firmas de las funciones deben estar anotadas con tipos. De lo contrario, usa nombres de variables claros para que sean más comprensibles.
Problema con la adición de un nuevo modelo
Abra un issue de Adición de un nuevo modelo para agregar un modelo específico.
Filtra por la etiqueta New model en GitHub para ver y agregar solicitudes de modelos existentes.
Ahora es un buen momento para familiarizarse con BrandNewLlama. Resulta útil leer el paper de investigación de un modelo para comprender su diseño técnico e implementación. No es necesario preocuparse demasiado por los detalles teóricos. En su lugar, concéntrate en los prácticos. Usa las preguntas de abajo para guiar tu lectura.
- ¿Qué tipo de modelo es BrandNewLlama? ¿Es un modelo de encoder, decoder o encoder-decoder?
- ¿Para qué tareas se puede utilizar BrandNewLlama?
- ¿Qué hace que BrandNewLlama sea diferente de otros modelos?
- ¿Qué modelos en Transformers son más similares a BrandNewLlama?
- Qué tokenizador utiliza BrandNewLlama?
Además de aprender más sobre su modelo, use los consejos a continuación para ayudarle a agregar un modelo más rápido.
Cada colaborador tiene un estilo y un flujo de trabajo únicos para agregar modelos a Transformers. Como ejemplo, echa un vistazo a cómo se agregó Gemma.
- ¡No reinventes la rueda! Tómate el tiempo para explorar modelos y tokenizadores existentes para ver qué puedes copiar y reutilizar. Grep y ripgrep son excelentes herramientas para esto.
- Esto es más un desafío de ingeniería que de ciencia. Céntrate en los aspectos más prácticos (por ejemplo, configurar un entorno de depuración eficiente) en lugar de los aspectos teóricos del modelo.
- ¡No tengas miedo de pedir ayuda! Estamos aquí para apoyarte. 🤗
Entorno de desarrollo
Haz clic en el botón Fork del repositorio Transformers para crear tu propia copia en la que trabajar. Clona el repositorio en tu disco local y añade el repositorio base como remoto.
git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.gitCree un entorno virtual y realice una instalación editable de la biblioteca con las dependencias “dev” o de desarrollo.
python -m venv .env
source .env/bin/activate
pip install -e ".[dev]"Debido al número de dependencias opcionales a medida que Transformers crece, es posible que este comando falle. En ese caso, instala las dependencias de “quality”. Asegúrate también de tener instalado un framework de deep learning.
pip install -e ".[quality]"Vuelva al directorio principal y clone e instale el repositorio original BrandNewLlama.
git clone https://github.com/org_that_created_brand_new_llama_org/brand_new_llama.git
cd brand_new_bert
pip install -e .Vuelve a tu clon de Transformers para comenzar a portar BrandNewLlama.
cd transformersHay dos entornos de depuración posibles para ejecutar el modelo original: un cuaderno (Google Colab o Jupyter) o un script de Python local.
No recomendamos configurar un entorno de GPU para ejecutar el modelo original, ya que puede ser costoso. En su lugar, trabaje primero en un entorno de CPU para verificar que el modelo funcione en Transformers. Una vez que lo haga, puede verificarlo en una GPU.
Los notebooks son excelentes para ejecutar código celda por celda, lo que puede ayudar a separar los componentes lógicos entre sí. También pueden acelerar los ciclos de depuración, ya que los resultados intermedios pueden almacenarse. Además, puedes compartir notebooks al trabajar con otros colaboradores.
La desventaja es que, si no estás acostumbrado a ellos, puede llevar un poco de tiempo adaptarse.
Si la arquitectura del modelo es idéntica a la de un modelo existente, salte a convertir el checkpoint, ya que puede reutilizar la arquitectura del modelo existente.
Ejecuta el comando siguiente para iniciar y completar el cuestionario con información básica sobre el nuevo modelo. Este comando agiliza el proceso generando automáticamente parte del código del modelo que deberás adaptar.
transformers add-new-model-like
Crea una solicitud de extracción
Antes de empezar a adaptar el código, crea una pull request para seguir tu progreso y recibir comentarios del equipo de Transformers. Ponle a tu pull request el título [WIP] Add BrandNewLlama para que quede claro que se trata de un trabajo en curso.
Crea una rama con un nombre descriptivo a partir de tu rama principal.
git checkout -b add_brand_new_bert
Commit the code, y luego realiza fetch y rebase en la rama principal.
git add . git commit git fetch upstream git rebase upstream/main
Envía los cambios a tu rama y haz clic en Compare & pull request para abrir una pull request en GitHub. Abre la pull request como draft para indicar que es un trabajo en curso.
git push -u origin a-descriptive-name-for-my-changes
Incluye a los miembros relevantes del equipo de Hugging Face añadiendo sus nombres de usuario de GitHub en la solicitud de extracción para preguntas, comentarios, observaciones y revisiones. Dirige a los miembros del equipo a partes específicas del código que desees señalando en la pestaña Files changed y, a continuación, haciendo clic en + a la izquierda del número de línea para añadir un comentario. Cuando se resuelve una pregunta o un problema, haz clic en Resolve para indicar que el problema está resuelto. Esto mantiene la conversación organizada y limpia.
Recuerda hacer commit y push de tu trabajo periódicamente, y actualiza tu trabajo con la rama principal actual.
git fetch upstream git merge upstream/main
Punto de control original
Tómate un tiempo para trabajar primero en la implementación original del modelo para entender cómo funciona.
Esto puede ser difícil si el repositorio original del modelo carece de documentación o si la base de código es compleja. Pero debes usar esto como motivación para implementar el modelo en Transformers. Tu contribución lo hace más accesible y fácil de usar para todos.
Orientarse con el repositorio original realizando lo siguiente.
- Localice los pesos preentrenados.
- Determina cómo cargar los pesos preentrenados en el modelo.
- Descubra cómo ejecutar el tokenizador de forma independiente del modelo.
- Tracea una pasada hacia adelante para entender qué clases y funciones son necesarias. Probablemente estas sean las únicas clases y funciones que tengas que implementar.
- Localiza todos los componentes importantes (clase del modelo, subclases del modelo, capa de autoatención, etc.) del modelo.
- Descubra cómo depurar el modelo en el repositorio original. Agregue declaraciones de impresión, utilice depuradores interactivos como ipdb o un entorno de desarrollo integrado (IDE) eficiente como PyCharm.
El último punto es especialmente importante porque necesitarás una comprensión exhaustiva de lo que ocurre dentro del modelo original antes de poder reimplementarlo en Transformers. Si encuentras algún problema, no dudes en abrir issues y pull requests en el repositorio original.
Un buen primer paso es cargar un checkpoint preentrenado pequeño e intentar reproducir una sola pasada hacia adelante con un vector de enteros de ejemplo como entrada. Por ejemplo, en pseudocódigo, esto podría verse así.
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = [0, 4, 5, 2, 3, 7, 9] # vector of input ids
original_output = model.generate(input_ids)Depuración
Si te encuentras con problemas, deberás elegir una de las siguientes estrategias de depuración según la base de código de los modelos originales.
Esta estrategia se basa en dividir el modelo original en subcomponentes más pequeños, como cuando el código se puede ejecutar fácilmente en modo eager. Aunque es más difícil, este enfoque tiene algunas ventajas.
- Es más fácil comparar el modelo original con tu implementación más adelante. Puedes verificar automáticamente que cada componente individual coincide con su componente correspondiente en la implementación de Transformers. Esto es mejor que depender de una comparación visual basada en declaraciones de impresión.
- Es más fácil portar componentes individuales en lugar de todo el modelo.
- Es más fácil entender cómo funciona un modelo si se divide en partes más pequeñas.
- Es más fácil prevenir regresiones en una etapa posterior al modificar el código gracias a las pruebas componente por componente.
Consulte las comprobaciones de integración de ELECTRA para un buen ejemplo de cómo descomponer un modelo en componentes más pequeños.
Esta estrategia es viable cuando la base de código original es demasiado compleja, solo permite ejecutar los componentes intermedios en modo compilado, o si resulta demasiado costoso en tiempo (o incluso imposible) separar el modelo en subcomponentes más pequeños.
Por ejemplo, la implementación de T5 en MeshTensorFlow es demasiado compleja y no ofrece una forma sencilla de descomponer el modelo en sus subcomponentes. En esta situación, tendrás que recurrir a verificar las declaraciones de impresión.
Sea cual sea la estrategia que elijas, se recomienda depurar primero las capas iniciales y las capas finales al final. Recupera la salida, ya sea mediante sentencias print o funciones de subcomponentes, de las siguientes capas en este orden.
- ids de entrada pasados al modelo
- embeddings de palabras
- entrada de la primera capa de Transformer
- salida de la primera capa de Transformer
- salida de las siguientes n-1 capas de Transformer
- salida de todo el modelo
Los ids de entrada deben ser simplemente un array de enteros como input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19].
Las salidas de las capas suelen consistir en matrices de flotantes multidimensionales.
[[
[-0.1465, -0.6501, 0.1993, ..., 0.1451, 0.3430, 0.6024],
[-0.4417, -0.5920, 0.3450, ..., -0.3062, 0.6182, 0.7132],
[-0.5009, -0.7122, 0.4548, ..., -0.3662, 0.6091, 0.7648],
...,
[-0.5613, -0.6332, 0.4324, ..., -0.3792, 0.7372, 0.9288],
[-0.5416, -0.6345, 0.4180, ..., -0.3564, 0.6992, 0.9191],
[-0.5334, -0.6403, 0.4271, ..., -0.3339, 0.6533, 0.8694]]],La salida de cada modelo de Transformers debe tener una precisión o tolerancia de error de 1e-3. Esto tiene en cuenta las diferencias de salida que surgen al utilizar un marco de biblioteca diferente. Compare las salidas intermedias del modelo original con la implementación de Transformers para asegurarse de que sean casi idénticas. Contar con un entorno de depuración eficiente es crucial para este paso.
Aquí tienes algunos consejos para un entorno de depuración eficiente.
Para depurar los resultados intermedios, depende del framework de aprendizaje automático que utilice el repositorio del modelo original. En el caso de PyTorch, debes escribir un script para descomponer el modelo original en subcomponentes más pequeños y así obtener los valores intermedios.
Es más rápido depurar con un checkpoint preentrenado más pequeño que con uno más grande, donde la pasada hacia adelante tarda más de 10 segundos. Si solo están disponibles checkpoints grandes, cree un modelo ficticio con pesos inicializados aleatoriamente y guarde esos pesos para compararlos con la implementación de Transformers.
Encuentra la forma más sencilla de llamar al paso hacia adelante del modelo. Idealmente, esta función (que puede llamarse
predict,evaluate,forwardo__call__) debe llamar al paso hacia adelante una sola vez. Es más difícil depurar una función que llama al paso hacia adelante varias veces.Separe la tokenización de la pasada hacia adelante. Localice el punto en la pasada hacia adelante donde una entrada de cadena se convierte en ids de entrada y comience aquí. Es posible que necesite crear un script pequeño o modificar el código original para introducir directamente los ids de entrada en lugar de una cadena de entrada.
Asegúrate de que el modelo no esté en modo de entrenamiento. Esto puede generar salidas aleatorias debido a las múltiples capas de dropout en un modelo. La pasada hacia adelante en tu entorno de depuración debe ser determinista para que las capas de dropout no se utilicen.
Una vez que puedas ejecutar el punto de control original, estarás listo para comenzar a adaptar el código del modelo para Transformers.
Adaptar el código del modelo
El comando transformers add-new-model-like debería haber generado un archivo de modelo y configuración.
src/transformers/models/brand_new_llama/modeling_brand_new_llama.pysrc/transformers/models/brand_new_llama/configuration_brand_new_llama.py
El código generado automáticamente en el archivo modeling.py tiene la misma arquitectura que Llama si respondiste que es un modelo solo de decodificador, o tendrá la misma arquitectura que BART si respondiste que es un modelo codificador-decodificador. El código generado es solo un punto de partida. Basándote en tu investigación sobre el nuevo modelo, necesitarás implementar esos cambios específicos adaptando el código generado. Esto puede implicar cambios en la capa de autoatención, el orden de la capa de normalización, y así sucesivamente.
Inicialización del modelo
En este punto, tu código no tiene que ser limpio ni siquiera completamente correcto. Es más eficiente crear rápidamente un primer borrador y luego mejorarlo de forma iterativa. Lo más importante es que tu modelo pueda instanciarse desde Transformers. El comando siguiente crea un modelo a partir de la configuración con pesos aleatorios, verificando que el método __init__ funcione.
from transformers import BrandNewLlama, BrandNewLlamaConfig
model = BrandNewLlama(BrandNewLlamaConfig())La inicialización aleatoria se realiza en el método _init_weights de BrandNewLlamaPreTrainedModel. Todos los módulos hoja se inicializan en función de las variables de la configuración. Utilice las funciones auxiliares del módulo transformers.initialization para establecer los valores, en lugar de llamar directamente a operaciones in situ sobre un peso o su .data.
from transformers import initialization as init
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, nn.Linear):
init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
if module.bias is not None:
init.zeros_(module.bias)
elif isinstance(module, nn.Embedding):
init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
if module.padding_idx is not None:
init.zeros_(module.weight[module.padding_idx])
elif isinstance(module, nn.LayerNorm):
init.zeros_(module.bias)
init.ones_(module.weight)Inicie siempre los pesos a través de las utilidades de transformers.initialization. Las operaciones in-place, como module.bias.zero_() o cualquier cosa que toque module.weight.data, omiten _is_hf_initialized, que marca qué parámetros ya están cargados. from_pretrained() ejecuta _init_weights después de cargar el checkpoint, por lo que las operaciones in-place sobrescriben silenciosamente los pesos cargados con valores aleatorios. Esto se aplica a los modelos de Transformers mediante la regla TRF012.
Durante from_pretrained(), los modelos suelen inicializarse en el dispositivo
meta. El cargador recrea los búferes no persistentes como tensores vacíos, por lo que los valores asignados en__init__no se conservan. Inicialice estos búferes en_init_weightspara que tengan los valores correctos después de la carga. Para un ejemplo, consulte cómo BERT inicializa sus IDs de posición y IDs de tipo de token.
El esquema de inicialización puede verse diferente si necesitas adaptarlo a tu modelo. Un submódulo con su propio método reset_parameters puede llamarlo directamente. Por ejemplo, Wav2Vec2ForPreTraining inicializa nn.Linear en sus dos capas lineales finales. La llamada es segura porque from_pretrained() modifica las funciones subyacentes de torch.nn.init para que respeten la bandera _is_hf_initialized mientras ejecuta _init_weights, de modo que los pesos cargados no se sobrescriban.
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, Wav2Vec2ForPreTraining):
module.project_hid.reset_parameters()
module.project_q.reset_parameters()Convertir puntos de control a Transformers
El checkpoint original debe convertirse en un checkpoint compatible con Transformers.
¡Prueba a buscar un script de conversión existente para copiarlo, adaptarlo y reutilizarlo para tu modelo!
- Si estás portando un modelo de TensorFlow a PyTorch, un buen punto de partida puede ser el script de conversión de BERT.
- Si está portando un modelo de PyTorch a PyTorch, un buen punto de partida puede ser el script de conversión de BART.
Asegúrate de que todos los pesos requeridos estén inicializados e imprime todos los pesos del checkpoint que no se utilizaron para la inicialización, a fin de verificar que el modelo se haya convertido correctamente.
Es posible que encuentres declaraciones de forma incorrectas o asignaciones de nombres durante la conversión. Lo más probable es que se deba a parámetros incorrectos en BrandNewLlamaConfig, la arquitectura equivocada, un error en el método init de tu implementación, o a que necesitas transponer uno de los pesos del checkpoint.
Sigue iterando en la sección Adapt the model code hasta que todos los pesos del checkpoint se carguen correctamente. Una vez que puedas cargar un checkpoint en tu modelo, guárdalo en una carpeta. Esta debe contener un archivo model.safetensors y un archivo config.json.
model.save_pretrained("/path/to/converted/checkpoint/folder")Para facilitar la conversión, la siguiente sección describe brevemente cómo los modelos de PyTorch almacenan y definen los pesos y nombres de las capas.
Pesos y nombres de las capas de PyTorch
Es útil crear un modelo básico de PyTorch para comprender cómo se definen los nombres de las capas y cómo se inicializan los pesos.
from torch import nn
class SimpleModel(nn.Module):
def __init__(self):
super().__init__()
self.dense = nn.Linear(10, 10)
self.intermediate = nn.Linear(10, 10)
self.layer_norm = nn.LayerNorm(10)Los nombres de las capas de PyTorch se definen por el nombre del atributo de clase de la capa (dense, intermediate, layer_norm). Crea una instancia de SimpleModel para rellenar todas las capas con pesos aleatorios.
model = SimpleModel()
print(model)
SimpleModel(
(dense): Linear(in_features=10, out_features=10, bias=True)
(intermediate): Linear(in_features=10, out_features=10, bias=True)
(layer_norm): LayerNorm((10,), eps=1e-05, elementwise_affine=True)
)Los valores de los pesos de una capa específica se inicializan aleatoriamente.
print(model.dense.weight.data)
tensor([[-0.0818, 0.2207, -0.0749, -0.0030, 0.0045, -0.1569, -0.1598, 0.0212,
-0.2077, 0.2157],
[ 0.1044, 0.0201, 0.0990, 0.2482, 0.3116, 0.2509, 0.2866, -0.2190,
0.2166, -0.0212],
[-0.2000, 0.1107, -0.1999, -0.3119, 0.1559, 0.0993, 0.1776, -0.1950,
-0.1023, -0.0447],
[-0.0888, -0.1092, 0.2281, 0.0336, 0.1817, -0.0115, 0.2096, 0.1415,
-0.1876, -0.2467],
[ 0.2208, -0.2352, -0.1426, -0.2636, -0.2889, -0.2061, -0.2849, -0.0465,
0.2577, 0.0402],
[ 0.1502, 0.2465, 0.2566, 0.0693, 0.2352, -0.0530, 0.1859, -0.0604,
0.2132, 0.1680],
[ 0.1733, -0.2407, -0.1721, 0.1484, 0.0358, -0.0633, -0.0721, -0.0090,
0.2707, -0.2509],
[-0.1173, 0.1561, 0.2945, 0.0595, -0.1996, 0.2988, -0.0802, 0.0407,
0.1829, -0.1568],
[-0.1164, -0.2228, -0.0403, 0.0428, 0.1339, 0.0047, 0.1967, 0.2923,
0.0333, -0.0536],
[-0.1492, -0.1616, 0.1057, 0.1950, -0.2807, -0.2710, -0.1586, 0.0739,
0.2220, 0.2358]]).En el script de conversión, los pesos aleatorios deben reemplazarse con los pesos exactos de la capa correspondiente en el punto de control original.
# retrieve matching layer weights with recursive algorithm
layer_name = "dense"
pretrained_weight = array_of_dense_layer
model_pointer = getattr(model, "dense")
model_pointer.weight.data = torch.from_numpy(pretrained_weight)Verifique que los pesos inicializados aleatoriamente y los pesos del punto de control preentrenado correspondiente tengan la misma forma y el mismo nombre. Agregue declaraciones assert para la forma e imprima los nombres de los pesos del punto de control.
assert (
model_pointer.weight.shape == pretrained_weight.shape
), f"Pointer shape of random weight {model_pointer.shape} and array shape of checkpoint weight {pretrained_weight.shape} mismatched"
logger.info(f"Initialize PyTorch weight {layer_name} from {pretrained_weight.name}")Cuando la forma o el nombre no coinciden, es posible que hayas asignado el peso de checkpoint incorrecto a una capa inicializada aleatoriamente. Una forma incorrecta puede deberse a que los parámetros de BrandNewLlama no coinciden exactamente con los parámetros de los modelos originales. Pero también puede ser que la implementación de la capa de PyTorch requiera que los pesos se transpongan primero.
Implementar la propagación hacia adelante
A continuación, se debe implementar la pasada hacia adelante si el modelo se carga correctamente. Toma algunas entradas y devuelve la salida del modelo.
model = BrandNewLlamaModel.from_pretrained("/path/to/converted/checkpoint/folder")
input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19]
output = model.generate(input_ids).last_hidden_statesNo te desanimes si tu pasada hacia adelante no es idéntica a la salida del modelo original o si devuelve un error. Comprueba que la pasada hacia adelante no lance ningún error. Esto suele deberse a que las dimensiones son incorrectas o a que se utiliza el tipo de datos equivocado (torch.long en lugar de torch.float32).
La salida debe tener una precisión de 1e-3. Asegúrate de que las formas de la salida y los valores de la salida sean idénticos. Las razones comunes por las que las salidas no son idénticas incluyen:
- Algunas capas no se añadieron (capa de activación o conexión residual).
- La matriz de incrustaciones de palabras no está vinculada.
- Se utilizan los embeddings posicionales incorrectos porque la implementación original incluye un desplazamiento.
- El dropout se aplica durante la pasada hacia adelante. Corrija este error asegurándose de que
model.trainingseaFalsey pasandoself.traininga torch.nn.functional.dropout.
Compare el paso hacia adelante del modelo original con su implementación para verificar si hay diferencias. Lo ideal es depurar e imprimir las salidas intermedias de ambas implementaciones del paso hacia adelante para identificar dónde la implementación original difiere de la suya.
- Asegúrate de que los
input_idscodificados de forma fija en ambas implementaciones sean idénticos. - Verifique que las salidas de la primera transformación de
input_ids(normalmente los embeddings de palabras) sean idénticas y avance hasta la última capa.
Cualquier diferencia entre las dos implementaciones debería señalar el error en tu implementación.
Una de las mejores estrategias es añadir muchas sentencias de impresión en las mismas posiciones en ambas implementaciones y, a continuación, eliminarlas sucesivamente cuando produzcan valores idénticos para las salidas intermedias.
Cuando ambas implementaciones producen la misma salida, verifica que las salidas estén dentro de una precisión de 1e-3.
torch.allclose(original_output, output, atol=1e-3)Esta suele ser la parte más difícil del proceso. ¡Felicidades si has llegado hasta aquí!
Y si te atascas o tienes dificultades con este paso, no dudes en pedir ayuda en tu pull request.
Añadir pruebas de modelos
Mientras el modelo funciona, aún necesitas agregar pruebas para garantizar que sea compatible con Transformers. Las pruebas son importantes porque ayudan a los usuarios a comprender tu trabajo al revisar pruebas específicas, y porque evitan que tu modelo se rompa en el futuro si se realizan cambios.
Cookiecutter debería haber añadido un archivo de pruebas para tu modelo. Ejecuta el archivo de pruebas siguiente para asegurarte de que todas las pruebas comunes se superan.
pytest tests/models/brand_new_llama/test_modeling_brand_new_llama.py
Las pruebas de integración deben añadirse primero, ya que cumplen la misma función que los scripts de depuración que utilizaste anteriormente para implementar el nuevo modelo en Transformers. Una plantilla de esas pruebas de modelo, BrandNewLlamaModelIntegrationTests, fue añadida por Cookiecutter y debe completarse. Para asegurarse de que se superen, ejecuta el siguiente comando.
RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
SET RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
Todas las características exclusivas de BrandNewLlama deben probarse en una prueba separada bajo BrandNewLlamaModelTester/BrandNewLlamaModelTest. Esta prueba suele pasarse por alto, pero es extremadamente importante porque:
- ayuda a transferir el conocimiento adquirido durante el proceso a la comunidad, mostrando cómo funcionan las características novedosas del modelo
- los futuros colaboradores pueden probar rápidamente los cambios en el modelo ejecutando estas pruebas especiales
Implementar el tokenizador
Recomendamos añadir un tokenizador rápido (PreTrainedTokenizerFast) para ofrecer a los usuarios el mejor rendimiento. No dudes en etiquetar a @ArthurZucker o a @itazap en tu PR si necesitas ayuda sobre cómo añadir PreTrainedTokenizerFast.
Con el modelo fuera de la ecuación, es hora de centrarse en el tokenizador. El tokenizador debe ser idéntico o muy similar a un tokenizador existente en Transformers.
Busca y carga el archivo de tokenizador original en tu implementación. Crea un script en el repositorio original que tome una cadena como entrada y devuelva los input_ids. El pseudocódigo debe parecerse al código siguiente.
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = model.tokenize(input_str)Es posible que necesites buscar en el repositorio original para encontrar la función de tokenizador correcta o modificar el tokenizador existente en tu clon del repositorio original para que solo devuelva input_ids. El script de tu tokenizador debería parecerse al siguiente.
from transformers import BrandNewLlamaTokenizer
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
tokenizer = BrandNewLlamaTokenizer.from_pretrained("/path/to/tokenizer/folder/")
input_ids = tokenizer(input_str).input_idsCuando ambas implementaciones tienen el mismo input_ids, añade un archivo de pruebas del tokenizador. Este archivo es análogo a los archivos de pruebas de modelado. Los archivos de pruebas del tokenizador deben contener un par de pruebas de integración con valores codificados.
Implementar un procesador de imágenes
Los procesadores de imágenes ahora utilizan una arquitectura basada en backends. El backend predeterminado es TorchvisionBackend, que utiliza la biblioteca torchvision y puede realizar el procesamiento de imágenes en la GPU. También se proporciona un backend alternativo de PIL/NumPy (PilBackend). Ambos backends se importan desde
image_processing_backends. No dude en etiquetar a @yonigozlan para obtener ayuda.
Aunque este ejemplo no incluye un procesador de imágenes, es posible que necesites implementar uno si tu modelo requiere entradas de imagen. El procesador de imágenes se encarga de convertir las imágenes en un formato adecuado para tu modelo. Antes de implementar uno nuevo, verifica si un procesador de imágenes existente en la biblioteca Transformers puede reutilizarse, ya que muchos modelos comparten técnicas similares de procesamiento de imágenes. Ten en cuenta que también puedes usar modular para procesadores de imágenes y reutilizar componentes existentes.
Si necesitas implementar un nuevo procesador de imágenes, cada modelo tiene dos archivos de procesador:
image_processing_<model>.py: el procesador predeterminado basado en torchvision (<Model>ImageProcessor), que hereda de TorchvisionBackend. Esto reemplaza al antiguo procesador “fast”.image_processing_pil_<model>.py: el procesador alternativo de PIL/NumPy (<Model>ImageProcessorPil), que hereda de PilBackend. Este reemplaza al antiguo procesador “lento”.
El archivo del backend torchvision también define cualquier clase de kwargs personalizada que importe el archivo PIL. Ambos archivos utilizan el decorador @auto_docstring: no añadas docstrings de clase manuales. Consulta IMAGE_PROCESSOR_REFACTORING_GUIDE.md para una guía paso a paso y ejemplos completos.
Añade pruebas para el procesador de imágenes en tests/models/your_model_name/test_image_processing_your_model_name.py. Estas pruebas deben ser similares a las de otros procesadores de imágenes y deben verificar que el procesador de imágenes maneje correctamente las entradas de imagen. Si tu procesador de imágenes incluye funciones o métodos de procesamiento únicos, asegúrate de añadir pruebas específicas para ellos también.
Implementar procesador
Si tu modelo acepta varias modalidades, como texto e imágenes, necesitas añadir un procesador. El procesador centraliza el preprocesamiento de las distintas modalidades antes de pasarlas al modelo.
El procesador debe llamar a los procesadores específicos de cada modalidad dentro de su función __call__ para manejar cada tipo de entrada correctamente. Asegúrese de revisar los procesadores existentes en la biblioteca para comprender su estructura esperada. Transformers utiliza la siguiente convención en la firma de la función __call__.
def __call__(
self,
images: ImageInput = None,
text: Union[TextInput, PreTokenizedInput, list[TextInput], list[PreTokenizedInput]] = None,
audio=None,
videos=None,
**kwargs: Unpack[YourModelProcessorKwargs],
) -> BatchFeature:
...YourModelProcessorKwargs es un TypedDict que incluye todos los argumentos de procesamiento típicos y cualquier argumento adicional que un procesador específico pueda requerir.
Añada pruebas para el procesador en tests/models/your_model_name/test_processor_your_model_name.py. Estas pruebas deben ser similares a las de otros procesadores y deben verificar que el procesador maneja correctamente las distintas modalidades.
Pruebas de integración
Ahora que tienes un modelo y un tokenizador, añade pruebas de integración de extremo a extremo para el modelo y el tokenizador en tests/models/brand_new_llama/test_modeling_brand_new_llama.py.
La prueba debe proporcionar un ejemplo significativo de texto a texto para demostrar que el modelo funciona como se espera. Por ejemplo, puede incluir un par de traducción de origen a destino, un par de artículo a resumen o un par de pregunta a respuesta.
Si el punto de control no se ha ajustado finamente en una tarea descendente, las pruebas del modelo son suficientes.
Por último, intenta asegurarte de que tus pruebas puedan ejecutarse en una GPU añadiendo declaraciones .to(self.device) a los tensores internos de los modelos. Si no tienes acceso a una GPU, podemos encargarnos de eso por ti.
Agregar documentación
Tu modelo solo es útil si los usuarios saben cómo usarlo. Por eso es importante añadir documentación y docstrings. Cookiecutter añadió un archivo de plantilla, docs/source/model_doc/brand_new_llama.md, que puedes completar con información sobre tu modelo.
Esta suele ser la primera interacción de un usuario con un modelo, por lo que la documentación debe ser clara y concisa. A menudo resulta muy útil añadir ejemplos de cómo se debe utilizar el modelo.
Asegúrate de que se añadan docstrings a src/transformers/models/brand_new_llama/modeling_brand_new_llama.py y que incluyan todas las entradas y salidas necesarias. Consulta nuestra guía para escribir documentación y docstrings.
Refactor
Es hora de ordenar las cosas y asegurarse de que el estilo del código sea coherente con el resto de la biblioteca. Ejecute el siguiente comando para corregir automáticamente los estilos incorrectos.
make style
Para verificar que el estilo del código pasa las comprobaciones de calidad, ejecute el siguiente comando.
make check-repo
Es posible que existan otras pruebas o comprobaciones fallidas (falta de docstring o nomenclatura incorrecta) en tu pull request debido a las pruebas de diseño estrictas de Transformers. Podemos ayudarte con estos problemas si te atascas.
Después de asegurarse de que el código se ejecuta correctamente, es posible que desee refactorizarlo para hacerlo más legible o limpio.
Subir al Hub
Convierte y sube todos los puntos de control al Hub. Añade una tarjeta de modelo para ofrecer mayor transparencia y contexto sobre el modelo. La tarjeta de modelo debe destacar características específicas de un punto de control, cómo se entrenó el modelo y ejemplos de código sobre cómo utilizarlo.
En muchos casos, añadir un notebook interactivo que los usuarios puedan ejecutar es una excelente manera de mostrar cómo usar el modelo para inferencia o cómo ajustarlo finamente en una tarea descendente. Aunque no es obligatorio, incluir un notebook puede impulsar una mayor adopción de tu modelo.
También debe consultar con el equipo de Transformers para decidir un nombre apropiado para el modelo y obtener los permisos de acceso necesarios para subir el modelo.
Use el método push_to_hub() para subir el modelo.
brand_new_bert.push_to_hub("brand_new_llama")Consulte la guía de Compartir para obtener más información sobre la carga de modelos en el Hub.
Fusiona tu modelo
Por fin estás listo para fusionar tu pull request y añadir oficialmente el modelo a Transformers. Asegúrate de que todas las pruebas se estén pasando y de que todos los comentarios y la retroalimentación hayan sido atendidos.
¡Felicidades por añadir un nuevo modelo a Transformers! 🥳
Esta es una contribución muy significativa. Tu trabajo hace que Transformers sea más accesible para desarrolladores e investigadores de todo el mundo. ¡Debes sentirte orgulloso/a de tu contribución y compartir tu logro con la comunidad!
Véase también
- Reglas de estructura del modelo — reglas estáticas aplicadas a todos los archivos
modeling_*.pyyconfiguration_*.py. Ejecutamake typingpara verificarlas antes de abrir un PR. - Comprobaciones de la solicitud de extracción — referencia completa sobre las comprobaciones de CI que se ejecutan en tu solicitud de extracción y cómo aprobarlas.