Introducción a los repositorios

Esta guía, pensada para principiantes, te ayudará a adquirir las habilidades básicas que necesitas para crear y gestionar tu repositorio en el Hub. Cada sección se apoya en la anterior, así que elige libremente por dónde empezar.

Requisitos

Este documento muestra cómo gestionar repositorios a través de la interfaz web y a través de la terminal. No hay requisitos si se trabaja con la interfaz de usuario. Si desea trabajar con la terminal, siga estas instrucciones de instalación.

Si aún no tienes git disponible como comando de CLI, necesitarás instalar Git para tu plataforma. También necesitarás instalar Git-Xet, que se utilizará para manejar archivos grandes, como imágenes y pesos de modelos.

Para poder descargar y subir archivos grandes desde Git, es necesario instalar la extensión Git Xet.

Para poder subir tu código al Hub, deberás autenticarte de alguna manera. La forma más sencilla de hacerlo es instalar la hf CLI y ejecutar el comando de inicio de sesión:

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

¡El contenido de la sección Getting Started de este documento también está disponible en formato de video!

Creación de un repositorio

Con la interfaz web del Hub puedes crear repositorios fácilmente, añadir archivos (¡incluso de gran tamaño!), explorar modelos, visualizar diferencias y mucho más. En el Hub existen tres tipos de repositorios y, en esta guía, crearás un repositorio de modelo con fines de demostración. Para obtener información sobre la creación y gestión de modelos, conjuntos de datos y Spaces, consulta su documentación respectiva.

1. Para crear un nuevo repositorio, visita huggingface.co/new:

2. Especifica el propietario del repositorio: puede ser tú o cualquiera de las organizaciones a las que pertenezcas.

3. Introduce el nombre de tu modelo. Este también será el nombre del repositorio.

4. Especifica si quieres que tu modelo sea público o privado.

5. Especifica la licencia. Puedes dejar el campo License en blanco por ahora. Para conocer más sobre las licencias, visita la documentación de Licenses.

Después de crear tu repositorio de modelos, deberías ver una página como esta:

Ten en cuenta que el Hub te pide que crees una Model Card, sobre la cual puedes informarte en la documentación de Model Cards. Incluir una Model Card en el repositorio de tu modelo es una buena práctica, pero como por ahora solo estamos creando un repositorio de prueba, podemos omitir este paso.

Agregar archivos a un repositorio (interfaz web)

Para añadir archivos a tu repositorio a través de la interfaz web, comienza seleccionando la pestaña Files, navega hasta el directorio deseado y luego haz clic en Add file. Se te dará la opción de crear un archivo nuevo o subir un archivo directamente desde tu computadora.

Creación de un nuevo archivo

Elegir crear un nuevo archivo te llevará a la siguiente pantalla del editor, donde puedes elegir un nombre para tu archivo, añadir contenido y guardar tu archivo con un mensaje que resuma tus cambios. En lugar de confirmar directamente el nuevo archivo en la rama main de tu repositorio, puedes seleccionar Open as a pull request para crear un Pull Request.

Subir un archivo

Si eliges Upload file, podrás seleccionar un archivo local para subirlo, junto con un mensaje que resuma tus cambios en el repositorio.

Al igual que al crear nuevos archivos, puedes seleccionar Open as a pull request para crear un Pull Request en lugar de añadir tus cambios directamente a la rama main de tu repositorio.

Agregar archivos a un repositorio (CLI)

Puedes subir archivos a tu repositorio directamente desde la terminal usando la CLI hf. Usa el comando hf upload para enviar archivos locales o carpetas completas:

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

La CLI hf maneja los archivos grandes automáticamente: no se requiere configuración adicional.

Agregar archivos a un repositorio (git)

Clonar repositorios

Descargar repositorios a su máquina local se denomina clonado. Puede usar los siguientes comandos para cargar su repositorio y navegar en él:

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

O para un repositorio de datos:

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

Puedes clonar mediante SSH con el siguiente comando:

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

Deberás añadir tu clave pública SSH a tu configuración de usuario para enviar cambios o acceder a repositorios privados.

Configuración

Ahora es el momento, ¡puedes añadir cualquier archivo que quieras al repositorio! 🔥

¿Tienes archivos de más de 10 MB? Debes hacer seguimiento de esos archivos con git-xet, que puedes inicializar con:

git xet install

Cuando usas Hugging Face para crear un repositorio, Hugging Face proporciona automáticamente una lista de extensiones de archivo comunes para los archivos grandes de Machine Learning en el archivo .gitattributes, que git-xet utiliza para rastrear de manera eficiente los cambios en tus archivos grandes. Sin embargo, es posible que necesites agregar nuevas extensiones si tus tipos de archivo no se manejan ya. Puedes hacerlo con git xet track "*.your_extension".

Subir archivos

Puedes usar Git para guardar nuevos archivos y cualquier cambio en archivos existentes como un conjunto de cambios llamado commit, que puede considerarse una “revisión” de tu proyecto. Para crear un commit, debes add los archivos para que Git sepa que planeamos guardar los cambios y luego commit esos cambios. Para sincronizar el nuevo commit con el Hugging Face Hub, a continuación push el commit al Hub.

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

¡Y ya está listo! Puedes revisar tu repositorio en Hugging Face con todos los archivos añadidos recientemente. Por ejemplo, en la captura de pantalla siguiente, el usuario añadió una serie de archivos. Ten en cuenta que algunos archivos en este ejemplo tienen un tamaño de 1.04 GB, por lo que el repositorio usa Xet para hacer seguimiento de ellos.

Si clonaste el repositorio con HTTP, es posible que se te pida ingresar tu nombre de usuario y contraseña en cada operación de push. La forma más sencilla de evitar la repetición es cambiar a SSH en lugar de HTTP. Alternativamente, si debes usar HTTP, puede resultarte útil configurar un git credential helper para autocompletar tu nombre de usuario y contraseña.

Ver el historial de un repositorio

Cada vez que recorres el ciclo add-commit-push, el repositorio mantiene un registro de cada cambio que hayas realizado en tus archivos. La interfaz de usuario te permite explorar los archivos del modelo y los commits, y ver la diferencia (también conocida como diff) introducida por cada commit. Para ver el historial, puedes hacer clic en el enlace History: X commits.

Puedes hacer clic en un commit individual para ver qué cambios introdujo ese commit: