Compartir modelos preentrenados
{#if fw === 'pt'}
{:else}
{/if}
En los siguientes pasos, veremos las formas más sencillas de compartir modelos preentrenados en el 🤗 Hub. Hay herramientas y utilidades disponibles que facilitan compartir y actualizar modelos directamente en el Hub, las cuales exploraremos a continuación.
Animamos a todos los usuarios que entrenan modelos a contribuir compartiéndolos con la comunidad. Compartir modelos, incluso cuando se entrenan con conjuntos de datos muy específicos, ayudará a otros, ahorrándoles tiempo y recursos computacionales y brindándoles acceso a artefactos entrenados útiles. ¡A su vez, tú puedes beneficiarte del trabajo que otros han hecho!
Hay tres maneras de crear nuevos repositorios de modelos:
- Usando la API
push_to_hub - Usando la librería de Python
huggingface_hub - Usando la interfaz web
Una vez que hayas creado un repositorio, puedes subir archivos a él a través de git y git-lfs. Te guiaremos a través de la creación de repositorios de modelos y la subida de archivos a ellos en las siguientes secciones.
Usando la API push_to_hub[[using-the-pushtohub-api]]
{#if fw === 'pt'}
{:else}
{/if}
La forma más sencilla de subir archivos al Hub es aprovechando la API push_to_hub.
Antes de continuar, necesitarás generar un token de autenticación para que la API huggingface_hub sepa quién eres y a qué espacios de nombres tienes acceso de escritura. Asegúrate de estar en un entorno donde tengas transformers instalado (consulta Configuración). Si estás en un notebook, puedes usar la siguiente función para iniciar sesión:
from huggingface_hub import notebook_login
notebook_login()
En una terminal, puedes ejecutar:
huggingface-cli login
En ambos casos, se te pedirá tu nombre de usuario y contraseña, que son los mismos que usas para iniciar sesión en el Hub. Si aún no tienes un perfil en el Hub, debes crear uno aquí.
¡Genial! Ahora tienes tu token de autenticación almacenado en tu carpeta de caché. ¡Vamos a crear algunos repositorios!
{#if fw === 'pt'}
Si has experimentado con la API Trainer para entrenar un modelo, la forma más sencilla de subirlo al Hub es establecer push_to_hub=True cuando defines tu TrainingArguments:
from transformers import TrainingArguments
training_args = TrainingArguments(
"bert-finetuned-mrpc", save_strategy="epoch", push_to_hub=True
)
Cuando llamas a trainer.train(), el Trainer subirá tu modelo al Hub cada vez que se guarde (aquí, en cada época) en un repositorio en tu espacio de nombres. Ese repositorio se llamará como el directorio de salida que elegiste (aquí bert-finetuned-mrpc), pero puedes elegir un nombre diferente con hub_model_id = "a_different_name".
Para subir tu modelo a una organización de la que eres miembro, simplemente pásala con hub_model_id = "my_organization/my_repo_name".
Una vez que tu entrenamiento haya terminado, debes hacer un trainer.push_to_hub() final para subir la última versión de tu modelo. ¡También generará una tarjeta de modelo con todos los metadatos relevantes, informando los hiperparámetros utilizados y los resultados de la evaluación! Aquí tienes un ejemplo del contenido que podrías encontrar en una tarjeta de modelo así:
{:else}
Si estás usando Keras para entrenar tu modelo, la forma más sencilla de subirlo al Hub es pasar un PushToHubCallback cuando llamas a model.fit():
from transformers import PushToHubCallback
callback = PushToHubCallback(
"bert-finetuned-mrpc", save_strategy="epoch", tokenizer=tokenizer
)
Luego debes añadir callbacks=[callback] en tu llamada a model.fit(). El callback subirá tu modelo al Hub cada vez que se guarde (aquí, en cada época) en un repositorio en tu espacio de nombres. Ese repositorio se llamará como el directorio de salida que elegiste (aquí bert-finetuned-mrpc), pero puedes elegir un nombre diferente con hub_model_id = "a_different_name".
Para subir tu modelo a una organización de la que eres miembro, simplemente pásala con hub_model_id = "my_organization/my_repo_name".
{/if}
A un nivel inferior, el acceso al Model Hub se puede realizar directamente en modelos, tokenizers y objetos de configuración a través de su método push_to_hub(). Este método se encarga tanto de la creación del repositorio como de subir los archivos del modelo y del tokenizer directamente al repositorio. No se requiere manejo manual, a diferencia de la API que veremos a continuación.
Para tener una idea de cómo funciona, primero inicialicemos un modelo y un tokenizer:
{#if fw === 'pt'}
from transformers import AutoModelForMaskedLM, AutoTokenizer
checkpoint = "camembert-base"
model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
{:else}
from transformers import TFAutoModelForMaskedLM, AutoTokenizer
checkpoint = "camembert-base"
model = TFAutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
{/if}
Eres libre de hacer lo que quieras con estos: añadir tokens al tokenizer, entrenar el modelo, ajustarlo. Una vez que estés satisfecho con el modelo, los pesos y el tokenizer resultantes, puedes aprovechar el método push_to_hub() directamente disponible en el objeto model:
model.push_to_hub("dummy-model")
Esto creará el nuevo repositorio dummy-model en tu perfil y lo poblará con los archivos de tu modelo.
Haz lo mismo con el tokenizer, para que todos los archivos estén ahora disponibles en este repositorio:
tokenizer.push_to_hub("dummy-model")
Si perteneces a una organización, simplemente especifica el argumento organization para subir al espacio de nombres de esa organización:
tokenizer.push_to_hub("dummy-model", organization="huggingface")
Si deseas usar un token específico de Hugging Face, también puedes especificarlo en el método push_to_hub():
tokenizer.push_to_hub("dummy-model", organization="huggingface", use_auth_token="<TOKEN>")
Ahora dirígete al Model Hub para encontrar tu modelo recién subido: https://huggingface.co/user-or-organization/dummy-model.
Haz clic en la pestaña "Files and versions" (Archivos y versiones), y deberías ver los archivos visibles en la siguiente captura de pantalla:
{#if fw === 'pt'}
[!TIP] ✏️ ¡Pruébalo! Toma el modelo y el tokenizer asociados con el checkpoint
bert-base-casedy súbelos a un repositorio en tu espacio de nombres usando el métodopush_to_hub(). Verifica que el repositorio aparezca correctamente en tu página antes de eliminarlo.
Como has visto, el método push_to_hub() acepta varios argumentos, lo que permite subir a un repositorio o espacio de nombres de una organización específica, o usar un token de API diferente. Te recomendamos que consultes la especificación del método disponible directamente en la documentación de 🤗 Transformers para tener una idea de lo que es posible.
El método push_to_hub() está respaldado por el paquete de Python huggingface_hub, que ofrece una API directa al Hugging Face Hub. Está integrado en 🤗 Transformers y en varias otras librerías de machine learning, como allenlp. Aunque en este capítulo nos centramos en la integración de 🤗 Transformers, integrarlo en tu propio código o librería es sencillo.
¡Ve a la última sección para ver cómo subir archivos a tu repositorio recién creado!
Usando la librería de Python huggingface_hub[[using-the-huggingfacehub-python-library]]
La librería de Python huggingface_hub es un paquete que ofrece un conjunto de herramientas para los hubs de modelos y datasets. Proporciona métodos y clases sencillos para tareas comunes como obtener información sobre repositorios en el hub y gestionarlos. Ofrece APIs sencillas que funcionan sobre git para gestionar el contenido de esos repositorios y para integrar el Hub en tus proyectos y librerías.
De manera similar a usar la API push_to_hub, esto requerirá que tengas tu token de API guardado en tu caché. Para hacer esto, necesitarás usar el comando login desde la CLI, como se mencionó en la sección anterior (de nuevo, asegúrate de anteponer estos comandos con el carácter ! si los ejecutas en Google Colab):
huggingface-cli login
El paquete huggingface_hub ofrece varios métodos y clases que son útiles para nuestro propósito. En primer lugar, hay algunos métodos para gestionar la creación, eliminación y otras operaciones de repositorios:
from huggingface_hub import (
# User management
login,
logout,
whoami,
# Repository creation and management
create_repo,
delete_repo,
update_repo_visibility,
# And some methods to retrieve/change information about the content
list_models,
list_datasets,
list_metrics,
list_repo_files,
upload_file,
delete_file,
)
Además, ofrece la muy potente clase Repository para gestionar un repositorio local. Exploraremos estos métodos y esa clase en las próximas secciones para entender cómo aprovecharlos.
El método create_repo se puede usar para crear un nuevo repositorio en el hub:
from huggingface_hub import create_repo
create_repo("dummy-model")
Esto creará el repositorio dummy-model en tu espacio de nombres. Si lo deseas, puedes especificar a qué organización debe pertenecer el repositorio usando el argumento organization:
from huggingface_hub import create_repo
create_repo("dummy-model", organization="huggingface")
Esto creará el repositorio dummy-model en el espacio de nombres huggingface, asumiendo que perteneces a esa organización.
Otros argumentos que pueden ser útiles son:
private, para especificar si el repositorio debe ser visible para otros o no.token, si deseas sobrescribir el token almacenado en tu caché por un token dado.repo_type, si deseas crear undataseto unspaceen lugar de un modelo. Los valores aceptados son"dataset"y"space".
Una vez creado el repositorio, ¡debemos añadirle archivos! Ve a la siguiente sección para ver las tres formas en que esto se puede manejar.
Usando la interfaz web[[using-the-web-interface]]
La interfaz web ofrece herramientas para gestionar repositorios directamente en el Hub. Usando la interfaz, puedes crear repositorios fácilmente, añadir archivos (¡incluso grandes!), explorar modelos, visualizar diferencias y mucho más.
Para crear un nuevo repositorio, visita huggingface.co/new:
Primero, especifica el propietario del repositorio: puedes ser tú o cualquiera de las organizaciones a las que estés afiliado. Si eliges una organización, el modelo aparecerá en la página de la organización y cada miembro de la organización tendrá la capacidad de contribuir al repositorio.
Luego, ingresa el nombre de tu modelo. Este también será el nombre del repositorio. Finalmente, puedes especificar si quieres que tu modelo sea público o privado. Los modelos privados están ocultos a la vista pública.
Después de crear tu repositorio de modelos, deberías ver una página como esta:
Aquí es donde se alojará tu modelo. Para empezar a poblarlo, puedes añadir un archivo README directamente desde la interfaz web.
El archivo README está en Markdown, ¡siéntete libre de usarlo a tu antojo! La tercera parte de este capítulo está dedicada a construir una tarjeta de modelo. Estas son de suma importancia para agregar valor a tu modelo, ya que son donde les dices a los demás lo que puede hacer.
Si miras la pestaña "Files and versions" (Archivos y versiones), verás que aún no hay muchos archivos allí, solo el README.md que acabas de crear y el archivo .gitattributes que rastrea archivos grandes.
A continuación, veremos cómo añadir algunos archivos nuevos.
Subiendo los archivos del modelo[[uploading-the-model-files]]
El sistema para gestionar archivos en el Hugging Face Hub se basa en git para archivos regulares y git-lfs (que significa Git Large File Storage) para archivos más grandes.
En la siguiente sección, repasaremos tres formas diferentes de subir archivos al Hub: a través de huggingface_hub y a través de comandos de git.
El enfoque upload_file[[the-uploadfile-approach]]
Usar upload_file no requiere que git y git-lfs estén instalados en tu sistema. Sube archivos directamente al 🤗 Hub usando solicitudes HTTP POST. Una limitación de este enfoque es que no maneja archivos de más de 5 GB de tamaño.
Si tus archivos son más grandes de 5 GB, sigue los otros dos métodos detallados a continuación.
La API se puede usar de la siguiente manera:
from huggingface_hub import upload_file
upload_file(
"<path_to_file>/config.json",
path_in_repo="config.json",
repo_id="<namespace>/dummy-model",
)
Esto subirá el archivo config.json disponible en <path_to_file> a la raíz del repositorio como config.json, al repositorio dummy-model.
Otros argumentos que pueden ser útiles son:
token, si deseas sobrescribir el token almacenado en tu caché por un token dado.repo_type, si deseas subir a undataseto unspaceen lugar de un modelo. Los valores aceptados son"dataset"y"space".
La clase Repository[[the-repository-class]]
La clase Repository gestiona un repositorio local de forma similar a git. Abstrae la mayoría de los puntos problemáticos que uno puede tener con git para proporcionar todas las características que necesitamos.
El uso de esta clase requiere tener git y git-lfs instalados, así que asegúrate de tener git-lfs instalado (consulta aquí para obtener instrucciones de instalación) y configurado antes de comenzar.
Para empezar a jugar con el repositorio que acabamos de crear, podemos empezar inicializándolo en una carpeta local clonando el repositorio remoto:
from huggingface_hub import Repository
repo = Repository("<path_to_dummy_folder>", clone_from="<namespace>/dummy-model")
Esto creó la carpeta <path_to_dummy_folder> en nuestro directorio de trabajo. Esta carpeta solo contiene el archivo .gitattributes, ya que es el único archivo creado al instanciar el repositorio a través de create_repo.
A partir de este punto, podemos aprovechar varios de los métodos tradicionales de git:
repo.git_pull()
repo.git_add()
repo.git_commit()
repo.git_push()
repo.git_tag()
¡Y otros! Te recomendamos que consultes la documentación de Repository disponible aquí para obtener una descripción general de todos los métodos disponibles.
Actualmente, tenemos un modelo y un tokenizer que nos gustaría subir al hub. Hemos clonado el repositorio con éxito, por lo que podemos guardar los archivos dentro de ese repositorio.
Primero nos aseguramos de que nuestro clon local esté actualizado extrayendo los últimos cambios:
repo.git_pull()
Una vez hecho esto, guardamos los archivos del modelo y del tokenizer:
model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")
El <path_to_dummy_folder> ahora contiene todos los archivos del modelo y del tokenizer. Seguimos el flujo de trabajo habitual de git añadiendo archivos al área de preparación, confirmándolos y subiéndolos al hub:
repo.git_add()
repo.git_commit("Add model and tokenizer files")
repo.git_push()
¡Felicidades! Acabas de subir tus primeros archivos al hub.
El enfoque basado en git[[the-git-based-approach]]
Este es el enfoque más básico para subir archivos: lo haremos directamente con git y git-lfs. La mayor parte de la dificultad se abstrae con los enfoques anteriores, pero hay algunas advertencias con el siguiente método, por lo que seguiremos un caso de uso más complejo.
El uso de esta clase requiere tener git y git-lfs instalados, así que asegúrate de tener git-lfs instalado (consulta aquí las instrucciones de instalación) y configurado antes de comenzar.
Primero, comienza inicializando git-lfs:
git lfs install
Updated git hooks.
Git LFS initialized.
Una vez hecho esto, el primer paso es clonar tu repositorio de modelos:
git clone https://huggingface.co/<namespace>/<your-model-id>
Mi nombre de usuario es lysandre y he usado el nombre de modelo dummy, así que para mí el comando termina viéndose así:
git clone https://huggingface.co/lysandre/dummy
Ahora tengo una carpeta llamada dummy en mi directorio de trabajo. Puedo cd en la carpeta y echar un vistazo a los contenidos:
cd dummy && ls
README.md
Si acabas de crear tu repositorio usando el método create_repo de Hugging Face Hub, esta carpeta solo debería contener un archivo oculto .gitattributes. Si seguiste las instrucciones de la sección anterior para crear un repositorio usando la interfaz web, la carpeta debería contener un único archivo README.md junto con el archivo oculto .gitattributes, como se muestra aquí.
Añadir un archivo de tamaño regular, como un archivo de configuración, un archivo de vocabulario o, básicamente, cualquier archivo de menos de unos pocos megabytes, se hace exactamente como se haría en cualquier sistema basado en git. Sin embargo, los archivos más grandes deben registrarse a través de git-lfs para poder subirlos a huggingface.co.
Volvamos a Python por un momento para generar un modelo y un tokenizer que nos gustaría enviar a nuestro repositorio dummy:
{#if fw === 'pt'}
from transformers import AutoModelForMaskedLM, AutoTokenizer
checkpoint = "camembert-base"
model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
# Do whatever with the model, train it, fine-tune it...
model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")
{:else}
from transformers import TFAutoModelForMaskedLM, AutoTokenizer
checkpoint = "camembert-base"
model = TFAutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
# Do whatever with the model, train it, fine-tune it...
model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")
{/if}
Ahora que hemos guardado algunos artefactos del modelo y del tokenizer, echemos otro vistazo a la carpeta dummy:
ls
{#if fw === 'pt'}
config.json pytorch_model.bin README.md sentencepiece.bpe.model special_tokens_map.json tokenizer_config.json tokenizer.json
Si miras los tamaños de los archivos (por ejemplo, con ls -lh), deberías ver que el archivo de estado del modelo (pytorch_model.bin) es el único atípico, con más de 400 MB.
{:else}
config.json README.md sentencepiece.bpe.model special_tokens_map.json tf_model.h5 tokenizer_config.json tokenizer.json
Si miras los tamaños de los archivos (por ejemplo, con ls -lh), deberías ver que el archivo de estado del modelo (t5_model.h5) es el único atípico, con más de 400 MB.
{/if}
[!TIP] ✏️ Al crear el repositorio desde la interfaz web, el archivo .gitattributes se configura automáticamente para considerar archivos con ciertas extensiones, como .bin y .h5, como archivos grandes, y git-lfs los rastreará sin necesidad de configuración por tu parte.
Ahora podemos seguir adelante y proceder como lo haríamos normalmente con los repositorios tradicionales de Git. Podemos añadir todos los archivos al entorno de preparación de Git usando el comando git add:
git add .
Luego podemos echar un vistazo a los archivos que están actualmente en preparación:
git status
{#if fw === 'pt'}
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: .gitattributes
new file: config.json
new file: pytorch_model.bin
new file: sentencepiece.bpe.model
new file: special_tokens_map.json
new file: tokenizer.json
new file: tokenizer_config.json
{:else}
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: .gitattributes
new file: config.json
new file: sentencepiece.bpe.model
new file: special_tokens_map.json
new file: tf_model.h5
new file: tokenizer.json
new file: tokenizer_config.json
{/if}
De manera similar, podemos asegurarnos de que git-lfs esté rastreando los archivos correctos usando su comando status:
git lfs status
{#if fw === 'pt'}
On branch main
Objects to be pushed to origin/main:
Objects to be committed:
config.json (Git: bc20ff2)
pytorch_model.bin (LFS: 35686c2)
sentencepiece.bpe.model (LFS: 988bc5a)
special_tokens_map.json (Git: cb23931)
tokenizer.json (Git: 851ff3e)
tokenizer_config.json (Git: f0f7783)
Objects not staged for commit:
Podemos ver que todos los archivos tienen Git como manejador, excepto pytorch_model.bin y sentencepiece.bpe.model, que tienen LFS. ¡Genial!
{:else}
On branch main
Objects to be pushed to origin/main:
Objects to be committed:
config.json (Git: bc20ff2)
sentencepiece.bpe.model (LFS: 988bc5a)
special_tokens_map.json (Git: cb23931)
tf_model.h5 (LFS: 86fce29)
tokenizer.json (Git: 851ff3e)
tokenizer_config.json (Git: f0f7783)
Objects not staged for commit:
Podemos ver que todos los archivos tienen Git como manejador, excepto t5_model.h5, que tiene LFS. ¡Genial!
{/if}
Procedamos a los pasos finales, confirmando y subiendo al repositorio remoto huggingface.co:
git commit -m "First model version"
{#if fw === 'pt'}
[main b08aab1] First model version
7 files changed, 29027 insertions(+)
6 files changed, 36 insertions(+)
create mode 100644 config.json
create mode 100644 pytorch_model.bin
create mode 100644 sentencepiece.bpe.model
create mode 100644 special_tokens_map.json
create mode 100644 tokenizer.json
create mode 100644 tokenizer_config.json
{:else}
[main b08aab1] First model version
6 files changed, 36 insertions(+)
create mode 100644 config.json
create mode 100644 sentencepiece.bpe.model
create mode 100644 special_tokens_map.json
create mode 100644 tf_model.h5
create mode 100644 tokenizer.json
create mode 100644 tokenizer_config.json
{/if}
Subir puede tomar un poco de tiempo, dependiendo de la velocidad de tu conexión a internet y el tamaño de tus archivos:
git push
Uploading LFS objects: 100% (1/1), 433 MB | 1.3 MB/s, done.
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 12 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 288.27 KiB | 6.27 MiB/s, done.
Total 9 (delta 1), reused 0 (delta 0), pack-reused 0
To https://huggingface.co/lysandre/dummy
891b41d..b08aab1 main -> main
{#if fw === 'pt'} Si echamos un vistazo al repositorio del modelo cuando esto termine, podemos ver todos los archivos añadidos recientemente:
La interfaz de usuario te permite explorar los archivos del modelo y los commits, y ver las diferencias introducidas por cada commit:
La interfaz de usuario te permite explorar los archivos del modelo y los commits, y ver las diferencias introducidas por cada commit:
