Baldes de almacenamiento

Los Storage Buckets son un tipo de repositorio en el Hugging Face Hub que ofrece almacenamiento de objetos similar a S3, impulsado por el backend de almacenamiento Xet. A diferencia de los repositorios basados en Git (modelos, conjuntos de datos, Spaces), los buckets son sin versiones y mutables, diseñados para casos de uso donde se necesita un almacenamiento simple y rápido, como puntos de control de entrenamiento, registros, artefactos intermedios o cualquier colección grande de archivos que no requiera control de versiones.

Puedes interactuar con los buckets mediante la interfaz web de Hub, la CLI hf o la API de Python.

Los buckets están disponibles para todos los usuarios y organizaciones. Consulta hf.co/storage para obtener detalles de precios.

Consulte Patrones de acceso para saber cómo acceder a los datos del bucket desde sus herramientas (montaje como sistema de archivos, rutas hf://, montajes de volumen en Jobs/Spaces), la API compatible con S3 para utilizar herramientas S3 existentes (AWS CLI, boto3, s5cmd) y Integraciones de Bucket para fragmentos de código listos para usar en bibliotecas de datos populares como pandas, Dask y Spark.

Buckets vs Repositorios

El Hub ofrece dos tipos de almacenamiento: repositorios basados en Git para trabajo colaborativo con control de versiones y buckets para almacenamiento de objetos mutable y de alta velocidad.

Utilice repositories cuando desee un historial de versiones, funciones de colaboración (PRs, discusiones) e integraciones con bibliotecas. Utilice buckets cuando necesite un almacenamiento rápido y mutable para datos que cambian con frecuencia: los archivos pueden sobrescribirse o eliminarse en su ubicación original.

Creación de un Bucket

Desde la interfaz de usuario del Hub

1. Vaya a huggingface.co/new-bucket:

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

3. Introduce un nombre de bucket.

4. Elija si el bucket debe ser público o privado.

5. Opcionalmente, preselecciona las regiones de precalentamiento de CDN para cachear tus datos más cerca de tu cómputo desde el principio.

Después de crear el bucket, debería ver la página del bucket:

Desde la CLI

# Create a bucket under your namespace
hf buckets create my-bucket

# Create a private bucket
hf buckets create my-bucket --private

# Create a bucket under an organization
hf buckets create my-org/shared-bucket

Desde Python

from huggingface_hub import create_bucket

# Create a bucket under your namespace
create_bucket("my-bucket")

# Create a private bucket
create_bucket("my-bucket", private=True)

# Create a bucket under an organization
create_bucket("my-org/shared-bucket")

Cambiar la visibilidad

Puedes cambiar la visibilidad de un bucket después de su creación:

# Make a bucket private
hf buckets settings username/my-bucket --private

# Make it public again
hf buckets settings username/my-bucket --public

from huggingface_hub import update_bucket_settings

update_bucket_settings("username/my-bucket", private=True)
update_bucket_settings("username/my-bucket", private=False)

Para la referencia completa de la API de Python, incluida la eliminación, el movimiento y la lista de cubos, consulte la guía de Buckets de huggingface_hub.

Explorar cubos en el Hub

Cada bucket tiene una página en el Hub donde puedes explorar su contenido, navegar por los directorios y ver los detalles de los archivos. Las páginas de bucket están disponibles en https://huggingface.co/buckets/<owner>/<bucket-name>.

Renderizado del README

Si un directorio de tu bucket contiene un archivo README.md, el Hub lo muestra debajo de la lista de archivos en la página de ese directorio. Esto funciona tanto en la raíz del bucket como en cualquier subdirectorio, lo cual resulta útil para documentar qué contiene un bucket, cómo se organiza los datos o cómo deben consumirlo las herramientas de niveles inferiores.

Listado desde la CLI

También puede listar el contenido de un bucket desde la CLI:

# List files in a bucket (with human-readable sizes)
hf buckets list julien-c/my-training-bucket -h
                     Feb 17 14:46  art/
                     Feb 17 14:58  arxivqa/
                     Feb 17 15:02  arxivqa2/
                     Feb 17 15:04  arxivqa3/
                     Feb 17 14:47  captcha/
                     Feb 17 14:53  captcha2/
                     Feb 24 17:22  julien/

# Recursive listing
hf buckets list julien-c/my-training-bucket/art -h -R
    423.6 MB         Feb 17 14:29  art/train-00000-of-00011.parquet
    441.0 MB         Feb 17 14:29  art/train-00001-of-00011.parquet
    521.7 MB         Feb 17 14:29  art/train-00002-of-00011.parquet
    481.4 MB         Feb 17 14:29  art/train-00003-of-00011.parquet
    444.6 MB         Feb 17 14:29  art/train-00004-of-00011.parquet
    461.6 MB         Feb 17 14:29  art/train-00005-of-00011.parquet
    466.4 MB         Feb 17 14:29  art/train-00006-of-00011.parquet
    486.3 MB         Feb 17 14:29  art/train-00007-of-00011.parquet
    477.0 MB         Feb 17 14:29  art/train-00008-of-00011.parquet
    454.0 MB         Feb 17 14:29  art/train-00009-of-00011.parquet
    483.1 MB         Feb 17 14:29  art/train-00010-of-00011.parquet

# Tree view
hf buckets list julien-c/my-training-bucket --tree -h -R
                        ├── art/
423.6 MB  Feb 17 14:29  │   ├── train-00000-of-00011.parquet
441.0 MB  Feb 17 14:29  │   ├── train-00001-of-00011.parquet
521.7 MB  Feb 17 14:29  │   ├── train-00002-of-00011.parquet
481.4 MB  Feb 17 14:29  │   ├── train-00003-of-00011.parquet
444.6 MB  Feb 17 14:29  │   ├── train-00004-of-00011.parquet
461.6 MB  Feb 17 14:29  │   ├── train-00005-of-00011.parquet
466.4 MB  Feb 17 14:29  │   ├── train-00006-of-00011.parquet
486.3 MB  Feb 17 14:29  │   ├── train-00007-of-00011.parquet
477.0 MB  Feb 17 14:29  │   ├── train-00008-of-00011.parquet
454.0 MB  Feb 17 14:29  │   ├── train-00009-of-00011.parquet
483.1 MB  Feb 17 14:29  │   └── train-00010-of-00011.parquet
                        ├── arxivqa/
495.9 MB  Feb 17 14:32  │   ├── train-00000-of-00164.parquet
518.3 MB  Feb 17 14:32  │   ├── train-00001-of-00164.parquet
495.5 MB  Feb 17 14:32  │   ├── train-00002-of-00164.parquet
486.6 MB  Feb 17 14:32  │   ├── train-00003-of-00164.parquet
490.4 MB  Feb 17 14:32  │   ├── train-00004-of-00164.parquet
...

Gestión de archivos

Puedes subir y descargar archivos directamente desde la página del bucket en el Hub, o usar la CLI y la API de Python para acceso programático. Los archivos de los buckets se refieren mediante rutas hf://buckets/ (p. ej., hf://buckets/username/my-bucket/path/to/file). El comando hf buckets cp gestiona la transferencia de archivos individuales, mientras que hf buckets sync es más adecuado para directorios. Todos los comandos funcionan en ambas direcciones: de local a remoto y de remoto a local.

Si tus datos ya se encuentran en un repositorio de modelo, dataset o Space (o en otro bucket), puedes copiarlos server-side con hf buckets cp sin necesidad de descargarlos ni volver a subirlos. Consulta Copiar archivos entre repositorios y buckets.

Subir archivos

Para subidas rápidas, puedes arrastrar y soltar archivos directamente en la página del bucket en tu navegador. Para uso programático, hf buckets cp copia archivos individuales en un bucket. La fuente es una ruta local y el destino es una ruta hf://buckets/. También puedes enviar datos desde stdin, lo cual es útil para contenido generado programáticamente.

CLI:

# Upload a single file
hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/models/model.safetensors

# Upload from stdin
cat config.json | hf buckets cp - hf://buckets/username/my-bucket/config.json

En Python, usa batch_bucket_files para subir uno o más archivos en una sola llamada. Cada entrada es una tupla de (local_path, remote_path).

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files(
    "username/my-bucket",
    add=[
        ("./model.safetensors", "models/model.safetensors"),
        ("./config.json", "models/config.json"),
    ],
)

Para más opciones de carga (bytes crudos, carga+eliminación combinada, etc.), consulte la guía de carga de huggingface_hub.

Descarga de archivos

Puedes descargar archivos individuales directamente desde la página del bucket en el Hub haciendo clic en ellos. Para el acceso programático, la descarga refleja la sintaxis de carga: intercambia el origen y el destino en hf buckets cp. También puedes transmitir un archivo a stdout usando - como destino, lo que te permite canalizar el contenido del bucket directamente a otras herramientas.

CLI:

# Download a single file
hf buckets cp hf://buckets/username/my-bucket/models/model.safetensors ./model.safetensors

# Download to stdout and pipe
hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .

En Python, usa download_bucket_files con una lista de tuplas (remote_path, local_path).

Python:

from huggingface_hub import download_bucket_files

download_bucket_files(
    "username/my-bucket",
    files=[
        ("models/model.safetensors", "./local/model.safetensors"),
        ("config.json", "./local/config.json"),
    ],
)

Para descargas más rápidas usando metadatos preobtenidos, consulte la guía de descarga de huggingface_hub.

Sincronización de directorios

El comando sync funciona como rsync o aws s3 sync: compara el origen y el destino y solo transfiere los archivos que han cambiado. Esta es la forma más eficiente de mantener sincronizados un directorio local y un bucket. De forma predeterminada, sync solo añade y actualiza archivos. Pasa --delete para eliminar también los archivos del destino que ya no existen en el origen. Usa --dry-run para previsualizar lo que ocurriría sin transferir nada en realidad.

CLI:

# Upload a local directory to a bucket
hf buckets sync ./data hf://buckets/username/my-bucket/data

# Download from a bucket to a local directory
hf buckets sync hf://buckets/username/my-bucket/data ./data

# Sync with deletion of extraneous files
hf buckets sync ./data hf://buckets/username/my-bucket/data --delete

# Preview what would be synced without executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --dry-run

# Plan and apply: review the sync plan before executing
hf buckets sync ./data hf://buckets/username/my-bucket/data --plan sync-plan.jsonl
# ... review the plan file, then apply it
hf buckets sync --apply sync-plan.jsonl

hf sync es un alias conveniente para hf buckets sync.

Python:

from huggingface_hub import sync_bucket

# Upload a local directory to a bucket
sync_bucket("./data", "hf://buckets/username/my-bucket/data")

# Download from a bucket to a local directory
sync_bucket("hf://buckets/username/my-bucket/data", "./data")

El comando sync admite filtrado (--include, --exclude), modos de comparación (--ignore-times, --existing) y un flujo de trabajo de plan-and-apply para revisar las operaciones antes de ejecutarlas. Para el conjunto completo de opciones, consulte la guía de sincronización de huggingface_hub.

Eliminación de archivos

Dado que los buckets no están versionados, las eliminaciones son inmediatas y permanentes: no hay forma de recuperar un archivo eliminado. Use --dry-run para verificar antes de eliminar archivos, especialmente al usar --recursive.

CLI:

# Remove a single file
hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix
hf buckets rm username/my-bucket/logs/ --recursive

# Preview what would be deleted
hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run

Python:

from huggingface_hub import batch_bucket_files

batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])

Para más opciones de eliminación (filtrado basado en patrones, eliminación recursiva, etc.), consulte la guía de eliminación de huggingface_hub.

Copiar archivos entre repositorios y cubos

Puede copiar archivos controlados por Xet desde cualquier repositorio (modelo, conjunto de datos, Space) o cubo a un cubo de destino sin volver a subir los datos. La copia se realiza en el servidor: solo se migran los hashes de contenido de Xet, por lo que incluso los archivos muy grandes se copian al instante gracias a la deduplicación a nivel de fragmento.

Solo se copian de servidor a servidor los archivos controlados por Xet. Los archivos pequeños que no son de Xet (p. ej., archivos de configuración y README) se descargan y vuelven a subir automáticamente. La copia en el servidor también requiere que el origen y el destino estén en la misma región de almacenamiento.

CLI:

hf buckets cp \
  hf://datasets/HuggingFaceFW/fineweb/data \
  hf://buckets/username/fineweb-data

Python:

from huggingface_hub import HfApi

api = HfApi()

api.copy_files(
    "hf://datasets/HuggingFaceFW/fineweb/data",
    "hf://buckets/username/fineweb-data",
)

Necesitas acceso de lectura al repositorio o bucket de origen y acceso de escritura al bucket de destino.

Tenga en cuenta que la transferencia de datos en la dirección opuesta, de un bucket a un repositorio (modelo, dataset, Space), sin volver a subirlos, aún no está disponible, pero está en la hoja de ruta.

Seguimiento de cambios

Los buckets son mutables, por lo que las herramientas que mantienen una vista de un bucket (montajes, capas de sistema de archivos, demonios de sincronización, paneles de control) necesitan saber cuándo cambian los archivos. Hay dos mecanismos disponibles:

• Webhooks: callbacks HTTP a un servidor que controlas, o un Job iniciado en cada cambio; consulta Process new files in a bucket with Jobs.
• Seguimiento en vivo: un flujo de eventos enviados por el servidor al que se suscribe su cliente.

Seguimiento en vivo

GET https://huggingface.co/api/buckets/<owner>/<bucket-name>/events transmite los cambios de archivos de un bucket como server-sent events. La solicitud debe incluir Accept: text/event-stream (de lo contrario devuelve un 400) y requiere el mismo acceso de lectura que la lista del bucket; no se necesita token para un bucket público. Consulte la OpenAPI spec para el esquema completo de parámetros y respuestas.

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/buckets/username/my-bucket/events"

En Python, no necesitas consumir el flujo tú mismo. HfFileSystem lo sigue por ti con live_follow=True, por lo que sus listados en caché se mantienen actualizados cuando otro proceso modifica el bucket:

Copiado

from huggingface_hub import HfFileSystem

hffs = HfFileSystem(live_follow=True)
hffs.ls("buckets/username/my-bucket/data")  # starts following the bucket

Las bibliotecas que aceptan storage_options de fsspec (pandas, PyArrow, …) también lo aceptan.

El flujo emite cuatro tipos de eventos:

Cada entrada en changes tiene un path y un op (add, update o delete). Un add o update también incluye los campos que cambiaron: size, xetHash, uploadedAt, mtime, mtimeNanos. Por lo tanto, un update puede ser tan pequeño como un nuevo uploadedAt cuando un archivo se vuelve a subir de forma idéntica. Los campos que no cambiaron se omiten; mtime/mtimeNanos también pueden ser null si una carga los limpió, por lo que se debe tratar la ausencia y null de la misma manera.

event: ready
data: {"cursor":"..."}

event: changes
data: {"cursor":"...","changes":[{"path":"data/train.txt","op":"add","size":20,"uploadedAt":"2026-09-16T09:21:45.000Z"},{"path":"data/old.txt","op":"delete"}]}

Reanudación. Un nuevo flujo comienza en el momento en que te conectas. Para obtener también los cambios que te perdiste, pasa el último cursor que recibiste (cada evento ready y changes incluye uno) como ?cursor=<cursor>, o una marca de tiempo como ?since=<ISO timestamp> (incluida, p. ej. 2026-09-16T09:21:45Z).

Solo se pueden reproducir los últimos ~15 minutos de cambios. Si tu cursor o since es anterior a eso, recibes reset en lugar de una reproducción: lista el bucket una vez para reconstruir tu vista y luego sigue desde el cursor del evento ready del nuevo stream. Reanudar está diseñado para cubrir brechas cortas, como una conexión perdida o un reinicio; un cliente que ha estado ausente más tiempo debería esperar volver a listar.

Reconectando. Las conexiones de larga duración se reciclan: aproximadamente cada 20 minutos (y durante las implementaciones), el servidor envía reconnect y luego finaliza el flujo. Trate cualquier finalización del flujo de la misma manera: reconecte con el último cursor que haya recibido. Se envía un comentario : ping cada 30 segundos para mantener la conexión activa, por lo que un flujo que se queda completamente en silencio puede considerarse muerto.

Una respuesta 503 significa que el seguimiento en vivo no está disponible temporalmente; reintenta tras el retraso indicado en la cabecera Retry-After.

Precaentamiento y CDN

Los buckets se almacenan de forma predeterminada en el almacenamiento global del Hub. Para cargas de trabajo en las que la ubicación del almacenamiento afecta directamente el rendimiento, puedes precalentar los datos del bucket para acercarlos a tu cómputo.

El precalentamiento almacena archivos en ubicaciones de borde cerca de proveedores de nube y regiones específicas, de modo que tus trabajos lean los datos de forma local en lugar de obtenerlos entre regiones. Esto resulta especialmente útil para:

• Clústeres de entrenamiento que requieren acceso rápido a grandes conjuntos de datos o puntos de control
• Configuraciones multi-región en las que diferentes partes de un pipeline se ejecutan en distintas nubes
• Distribución de artefactos grandes a muchos consumidores en todo el mundo

Consulte hf.co/storage para ver las regiones disponibles y los detalles sobre cómo habilitar el pre-warming.

Casos de uso

Puntos de control y registros de entrenamiento

Al ejecutar trabajos de entrenamiento (por ejemplo, a través de Jobs), guarda los puntos de control y los registros en un bucket. A diferencia de un repositorio de Git, puedes sobrescribir el punto de control más reciente sin acumular historial de versiones, y sync garantiza que solo se transfieran los datos modificados.

# After each evaluation step, sync checkpoints to a bucket
hf sync ./checkpoints hf://buckets/my-org/training-run-42/checkpoints

Dado que los buckets se construyen sobre Xet, los puntos de control sucesivos en los que grandes partes del modelo están congeladas se benefician de la deduplicación a nivel de fragmento. Solo se suben los fragmentos modificados.

Pipelines de procesamiento de datos

Los buckets funcionan como áreas de preparación para los flujos de trabajo de procesamiento de datos. Procesa los datos crudos, escribe las salidas intermedias en un bucket y, cuando el pipeline se completa, promociona el artefacto final a un repositorio de Dataset versionado. Esto mantiene tu repositorio versionado limpio y le proporciona a tu pipeline un almacenamiento mutable rápido.

Tenga en cuenta que la transferencia de datos desde un Bucket a un repositorio sin volver a subirlos aún no está disponible, pero está en la hoja de ruta.

Almacenamiento agéntico

Los agentes de IA necesitan almacenamiento temporal para resultados intermedios, salidas de herramientas, trazas y memoria de trabajo. Los buckets ofrecen un lugar nativo del Hub para estos datos: acceso mutable rápido sin la sobrecarga de Git, permisos estándar de Hugging Face y direccionables mediante rutas hf://buckets/ en todo el ecosistema del Hub.

Copias de seguridad rotativas

Los buckets son adecuados para mantener copias de seguridad rotativas. Con un repositorio de Dataset basado en Git, eliminar archivos obsoletos no libera almacenamiento: el historial de Git conserva todas las versiones anteriores, por lo que sería necesario comprimir los commits o reescribir el historial para recuperar espacio de forma real. Con los buckets, los archivos antiguos desaparecen por completo al eliminarlos y solo se paga por lo que se almacena actualmente.

# Sync today's backup, removing files that no longer exist locally
hf sync ./daily-backup hf://buckets/my-user/backups/latest --delete

Vincular modelos a cubos

Puede crear un enlace bidireccional entre un modelo y un bucket añadiendo el campo buckets a los metadatos de la tarjeta del modelo. Los modelos vinculados aparecerán entonces en la página del bucket, y el bucket aparecerá como una etiqueta en la página del modelo.

# In the model card YAML frontmatter
buckets:
- my-org/my-bucket

Consulte Especificar un bucket en la documentación de las tarjetas de modelo para obtener más detalles.

Precios

Los Storage Buckets se facturan en función de la cantidad de datos almacenados, con un precio simple por TB. Los planes Enterprise se benefician de una facturación basada en deduplicación, donde los fragmentos compartidos entre archivos reducen directamente la huella facturada.

En cuanto a otros repositorios, los buckets se pueden crear de forma gratuita y tienen un límite de almacenamiento gratuito. Para el uso que exceda el plan gratuito, consulte hf.co/storage. Para información general sobre facturación, consulte la documentación de Facturación.