Crear y gestionar un repositorio

El Hugging Face Hub es una colección de repositorios git. Git es una herramienta ampliamente utilizada en el desarrollo de software para versionar proyectos con facilidad al trabajar de forma colaborativa. Esta guía te mostrará cómo interactuar con los repositorios del Hub, en especial:

• Crear y eliminar un repositorio.
• Gestionar ramas y etiquetas.
• Renombra tu repositorio.
• Actualiza la visibilidad de tu repositorio.
• Gestiona una copia local de tu repositorio.

Si estás acostumbrado a trabajar con plataformas como GitLab/GitHub/Bitbucket, tu primer instinto podría ser usar la CLI de git para clonar tu repositorio (git clone), confirmar los cambios (git add, git commit) y enviarlos (git push). Esto es válido al usar Hugging Face Hub. Sin embargo, la ingeniería de software y el aprendizaje automático no comparten los mismos requisitos ni flujos de trabajo. Los repositorios de modelos pueden mantener archivos de pesos de modelos grandes para diferentes marcos y herramientas, por lo que clonar el repositorio puede llevarte a mantener carpetas locales grandes con tamaños masivos. Como resultado, puede ser más eficiente usar nuestros métodos HTTP personalizados. Puedes leer nuestra página de explicación Paradigma Git vs HTTP para más detalles.

Si deseas crear y gestionar un repositorio en el Hub, tu máquina debe estar iniciada sesión. Si no es así, consulta esta sección. En el resto de esta guía, asumiremos que tu máquina tiene la sesión iniciada.

Listar tus repositorios

Puedes listar todos los repositorios (modelos, conjuntos de datos, espacios y cubos) de tu cuenta u organización usando list_user_repos(). Los resultados incluyen información de almacenamiento y están ordenados por uso de almacenamiento.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

O mediante la CLI (muestra 30 repositorios por defecto, usa --limit 0 para listar todos):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

Creación y eliminación de repositorios

El primer paso es saber cómo crear y eliminar repositorios. Solo puedes gestionar los repositorios que te pertenecen (bajo el espacio de nombres de tu nombre de usuario) o los de organizaciones en las que tienes permisos de escritura.

Crear un repositorio

Cree un repositorio vacío con create_repo() y asígnale un nombre con el parámetro repo_id. El repo_id es su espacio de nombres seguido del nombre del repositorio: username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

O mediante la CLI:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

Por defecto, create_repo() crea un repositorio de modelos. Pero puedes usar el parámetro repo_type para especificar otro tipo de repositorio. Por ejemplo, si quieres crear un repositorio de datos:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

O mediante la CLI:

>>> hf repos create lysandre/test-dataset --repo-type dataset

Al crear un repositorio, puedes establecer la visibilidad de tu repositorio con el parámetro visibility:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

O mediante la CLI:

>>> hf repos create lysandre/test-private --private

Si deseas cambiar la visibilidad del repositorio en un momento posterior, puedes usar la función update_repo_settings().

Si formas parte de una organización con un plan Enterprise, puedes crear un repositorio en un grupo de recursos específico pasando resource_group_id como parámetro a create_repo(). Los grupos de recursos son una función de seguridad para controlar qué miembros de tu organización pueden acceder a un recurso dado. Puedes obtener el ID del grupo de recursos copiándolo de la URL de la página de configuración de tu organización en el Hub (p. ej. "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Para más detalles sobre los grupos de recursos, consulta esta guía.

También puedes crear un repositorio en una región de nube específica pasando region como parámetro:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

Eliminar un repositorio

Elimina un repositorio con delete_repo(). Asegúrate de que quieres eliminar un repositorio porque este es un proceso irreversible.

Especifique el repo_id del repositorio que desea eliminar:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

Pasa missing_ok=True para ignorar silenciosamente la llamada si el repositorio no existe:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

O mediante la CLI:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

Duplicar un repositorio

En algunos casos, es posible que desees copiar el repositorio de otra persona para adaptarlo a tu caso de uso. Esto es posible usando el método duplicate_repo(). Duplicará todo el repositorio, preservando el historial completo de git. Esto funciona para modelos, conjuntos de datos y Spaces. Para Spaces, aún necesitarás configurar tus propios ajustes (hardware, tiempo de inactividad, almacenamiento, variables y secretos). Consulta nuestra guía Manage your Space para más detalles.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

Al igual que create_repo(), duplicate_repo() acepta un resource_group_id para crear la copia directamente dentro de un grupo de recursos de su organización Enterprise (--resource-group-id con hf repos duplicate).

El historial de git se copia de inmediato, pero los archivos LFS/Xet pueden seguir copiándose en segundo plano una vez que duplicate_repo() devuelve un valor. Hasta que la copia esté completa, la descarga de estos archivos desde el nuevo repositorio puede fallar. Comprueba files_copy_pending en el valor devuelto para saber si la copia sigue en curso:

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Buscar en Spaces

El Hub ofrece una API de búsqueda semántica para descubrir Spaces. Puedes buscar con consultas en lenguaje natural mediante search_spaces():

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

Para más detalles y opciones de filtrado, consulte la guía Gestionar sus Spaces.

Subir y descargar archivos

Ahora que has creado tu repositorio, te interesa enviar cambios a él y descargar archivos de él.

Estos 2 temas merecen sus propias guías. Consulta las guías de upload y download para aprender a usar tu repositorio.

Copiar archivos

Use copy_files() para copiar archivos que ya están alojados en el Hub de un repositorio a otro (o incluso dentro del mismo repositorio) sin descargarlos ni volver a subirlos. Se admiten tanto archivos individuales como carpetas completas, y los archivos rastreados con Xet o LFS se copian en el servidor mediante su hash.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

O mediante la CLI, con el comando unificado hf cp (también disponible como hf repos cp):

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files (y hf cp) también pueden copiar archivos de un repositorio a un Bucket. No se admite la copia desde un bucket hacia un repositorio. Consulte la guía de Buckets para obtener más detalles.

Las copias del lado del servidor solo funcionan dentro de la misma región de almacenamiento.

Ramas y etiquetas

Los repositorios de Git suelen utilizar ramas para almacenar diferentes versiones de un mismo repositorio. Las etiquetas también se pueden usar para marcar un estado específico de su repositorio, por ejemplo, al publicar una versión. De manera más general, a las ramas y etiquetas se les denomina referencias de git.

Crear ramas y etiquetas

Puedes crear nuevas ramas y etiquetas usando create_branch() y create_tag():

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

O mediante la CLI:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

Puede usar las funciones delete_branch() y delete_tag() de la misma manera para eliminar una rama o una etiqueta, o bien hf repos branch delete y hf repos tag delete respectivamente en la CLI.

Listar todas las ramas y etiquetas

También puede listar las referencias git existentes de un repositorio usando list_repo_refs():

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

Cambiar la configuración del repositorio

Los repositorios incluyen algunas configuraciones que puedes personalizar. En la mayoría de los casos, querrás hacerlo manualmente en la página de configuración del repositorio en tu navegador. Debes tener acceso de escritura a un repositorio para configurarlo (ya sea que seas su propietario o que formes parte de una organización). En esta sección, veremos las configuraciones que también puedes establecer de forma programática mediante huggingface_hub.

Algunas configuraciones son específicas de Spaces (hardware, variables de entorno, …). Para configurarlas, consulta nuestra guía Manage your Spaces.

Actualizar visibilidad

Un repositorio puede ser público o privado. Un repositorio privado solo es visible para ti o para los miembros de la organización en la que se encuentra el repositorio. Cambia un repositorio a privado como se muestra a continuación:

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

O mediante la CLI:

>>> hf repos settings lysandre/test-private --private true

Configurar el acceso restringido

Para ofrecer un mayor control sobre el uso de los repositorios, el Hub permite a los autores habilitar solicitudes de acceso para sus repositorios. Cuando esta opción está activada, el usuario debe aceptar compartir su información de contacto (nombre de usuario y dirección de correo electrónico) con los autores del repositorio para acceder a los archivos. Un repositorio con solicitudes de acceso habilitadas se denomina repositorio con control de acceso.

Puedes configurar un repositorio como de acceso restringido usando update_repo_settings():

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

O mediante la CLI:

>>> hf repos settings lysandre/test-private --gated auto

Cambiar el nombre de tu repositorio

Puedes cambiar el nombre de tu repositorio en el Hub usando move_repo(). Con este método también puedes mover el repositorio de un usuario a una organización. Al hacerlo, hay algunas limitaciones de las que debes ser consciente. Por ejemplo, no puedes transferir tu repositorio a otro usuario.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

O mediante la CLI:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

Repositorios de kernels

El Hub admite un tipo de repositorio "kernel" para alojar kernels de cómputo. Este no es un tipo de repositorio totalmente compatible. Solo se han probado y se admiten oficialmente un conjunto limitado de métodos:

• kernel_info()
• hf_hub_download()
• snapshot_download()
• list_repo_refs()
• list_repo_files()
• list_repo_tree()

Tenga en cuenta que create_repo() y delete_repo() también son compatibles, pero están restringidos a un pequeño subconjunto de usuarios y organizaciones permitidos en el Hub.

For building, publishing, and using kernel repos, please use the dedicated kernels package instead. Refer to the Kernels documentation for more details.