Migrar datos a cubos de almacenamiento

Esta guía muestra cómo mover conjuntos de datos grandes a un Storage Bucket desde donde se encuentren actualmente: disco local, otra nube o el Hub. Busca tu origen en la tabla siguiente y salta a esa sección.

Donde sea posible, haz que tus datos sean legibles como un sistema de archivos y ejecuta hf sync. Deduplica en el cliente, por lo que subes menos bytes que con una copia directa.

De un vistazo

Por qué hf sync es el predeterminado:

• Subes menos. hf sync sube a través del cliente Xet, que fragmenta y deduplica tus datos primero, de modo que solo se envían los fragmentos que el Hub no ha visto. Una copia en bruto (por ejemplo, rclone a través de la pasarela S3) transfiere cada byte.
• Es al menos tan rápido. En las migraciones que hemos apoyado hasta ahora, hf sync sobre una fuente montada ha igualado o superado a rclone en rendimiento.

Antes de comenzar

Todos los comandos de esta guía utilizan hf, la Hugging Face CLI. Su salida de ayuda es legible por agentes, por lo que un agente de código puede configurar y supervisar una migración por ti (consulta CLI for AI Agents). Revisa los comandos antes de ejecutarlos a gran escala.

1. Instala la CLI. El cliente de Xet se incluye con ella.

   Copiado

   curl -LsSf https://hf.co/cli/install.sh | bash
   hf version

2. Inicia sesión con un token que tenga acceso de escritura (crea uno):

   Copiado

   hf auth login
   hf auth whoami

3. Cree el bucket de destino. <namespace> es su nombre de usuario u organización. Sin --region, el bucket se crea en la región de almacenamiento predeterminada del namespace, que siempre es EE. UU. fuera de los planes Team & Enterprise. En esos planes, pase --region us o --region eu para elegir.

   Copiado

   hf buckets create <namespace>/<bucket> --private

Comience con una ejecución de prueba. Sea cual sea la ruta que utilice, ensáyela en un subconjunto pequeño (una carpeta o un patrón de --include), verifique el resultado con --dry-run y hf buckets ls, y luego inicie la migración completa. Todas las rutas de esta guía se pueden reanudar, por lo que una ejecución de prueba no tiene ningún costo.

Desde el disco local o un sistema de archivos de clúster

Utilice esto cuando sus datos estén en un disco local, un volumen adjunto o el espacio temporal del clúster: cualquier cosa que la máquina pueda leer como archivos. También es el último paso de cada ruta de la nube que se describe a continuación, una vez que la fuente esté montada.

hf sync ./data hf://buckets/<namespace>/<bucket>/data

hf sync compara el origen y el destino y transfiere solo la diferencia, por lo que volver a ejecutar el mismo comando reanuda una migración interrumpida: se omiten los archivos ya subidos. Variantes comunes:

# Mirror exactly: also delete destination files that are gone from the source
hf sync ./data hf://buckets/<namespace>/<bucket>/data --delete

# Preview what would transfer, without uploading
hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run

# Only some files
hf sync ./data hf://buckets/<namespace>/<bucket>/data --include "*.parquet" --exclude "tmp/*"

Para revisar una migración extensa antes de ejecutarla, escriba el plan en un archivo, revíselo y luego aplíquelo. Esto escanea el origen y el destino una sola vez, en lugar de hacerlo una vez para una ejecución de prueba y otra vez para la ejecución real.

hf sync ./data hf://buckets/<namespace>/<bucket>/data --plan plan.jsonl   # scan once, write the plan
hf sync --apply plan.jsonl                                                # run exactly that plan

Ejecuta --apply desde el directorio donde creaste el plan, ya que el plan registra la ruta de origen tal como la escribiste. --apply no comprueba lo que ya se ha subido, por lo que para reanudar una ejecución interrumpida, vuelve a ejecutar el comando hf sync normal.

Para verificarlo, compruebe que una ejecución de prueba no tiene nada más que transferir y revise a simple vista el contenido:

hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run
hf buckets ls hf://buckets/<namespace>/<bucket>/data

Ajuste

• Mantén la caché en un disco rápido. El cliente de Xet almacena en caché los fragmentos y un índice de deduplicación (la caché de fragmentos) bajo HF_HOME. Si tu directorio de inicio no está en un NVMe, apunta HF_HOME a uno local.
• Activa el modo de alto rendimiento para migraciones masivas en una máquina con recursos abundantes. HF_XET_HIGH_PERFORMANCE=1 aumenta la concurrencia, los tamaños de búfer y el número de archivos ingeridos a la vez, de modo que el cliente pueda usar todos los núcleos de CPU y saturar la red. Está pensado para máquinas con ancho de banda alto y disco rápido; con versiones de hf_xet anteriores a 1.7.0, úsalo solo con al menos 64 GB de RAM (compruébalo con hf env). Consulta Variables de entorno.
• Limitar el tamaño de la caché de fragmentos. Su límite de tamaño es flexible: la caché se poda solo al inicio de una ejecución, por lo que durante una ejecución larga puede crecer mucho más allá del límite. En una migración de gran tamaño, especialmente en modo de alto rendimiento, puede crecer hasta cientos de GB y llenar el disco, interrumpiendo la ejecución. Establezca HF_XET_SHARD_CACHE_SIZE_LIMIT con un margen suficiente por debajo del espacio libre en disco, pero no más bajo de lo necesario: una caché de tamaño X deduplica frente a aproximadamente 1000 × X de datos. Consulte Caché de fragmentos.

Establezca estos valores antes de iniciar la sincronización. Los tamaños aceptan valores legibles por humanos, como 64gb:

export HF_HOME=/mnt/nvme/hf                 # chunk and shard caches on NVMe
export HF_XET_HIGH_PERFORMANCE=1            # use all cores and the full network
export HF_XET_SHARD_CACHE_SIZE_LIMIT=64gb   # keep the shard cache under free disk space

hf sync ./data hf://buckets/<namespace>/<bucket>/data

Dividir por subruta (experimental)

Para conjuntos de datos muy grandes, puedes dividir la fuente en subcaminos y ejecutar varios procesos de hf sync a la vez. Las pruebas iniciales sugieren que el rendimiento escala de forma aproximadamente lineal, pero esto necesita más validación. Dos reglas:

• Divide en datos relacionados, de modo que los archivos de cada worker se dedupliquen bien entre sí.
• Asigne a cada worker su propio HF_HOME para que no compitan por la caché. Cada caché ocupa espacio en disco, así que divida HF_XET_SHARD_CACHE_SIZE_LIMIT entre los workers.

HF_HOME=/mnt/nvme/hf-a hf sync ./data/groupA hf://buckets/<namespace>/<bucket>/groupA &
HF_HOME=/mnt/nvme/hf-b hf sync ./data/groupB hf://buckets/<namespace>/<bucket>/groupB &
wait

Un solo proceso comparte una única caché y deduplica de la mejor manera, por lo que solo debe dividirse cuando un proceso no puede saturar su red.

Solución de problemas

Desde AWS S3 o almacenamiento compatible con S3

hf sync no lee URLs de s3://, por lo que debe montar el bucket de origen como un sistema de archivos con Mountpoint for Amazon S3 y luego sincronizar desde el montaje. Sus datos aún pasan por el cliente Xet, por lo que obtiene deduplicación en el lado del cliente.

mount-s3 my-source-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>
umount /mnt/src

Para almacenes compatibles con S3, como Cloudflare R2 o MinIO, agregue --endpoint-url <url> a mount-s3. Para un bucket público que permite lecturas anónimas, como los del registro de datos abiertos de AWS, agregue --no-sign-request. La verificación, el ajuste y la solución de problemas son los mismos que para datos locales.

Alternativa: rclone a través de la pasarela S3

Usa esto si ya ejecutas rclone y prefieres no montar. La desventaja: rclone envía cada byte a través de la puerta de enlace S3 sin deduplicación en el cliente, por lo que transfiere más que hf sync. Necesitas credenciales de S3 para la puerta de enlace.

Usa rclone 1.70 o una versión más reciente (verifícalo con rclone version y actualízalo desde rclone downloads). Las versiones anteriores pueden agotar la memoria al listar cubos muy grandes. Los consejos antiguos suelen recomendar --fast-list; con una versión reciente de rclone no lo necesitas, y en un listado enorme mantiene todo en memoria y puede provocar el mismo fallo.

Agrega la pasarela como un remoto en ~/.config/rclone/rclone.conf, junto al remoto de tu origen (aws a continuación):

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 256M
chunk_size = 256M

El gateway solo admite ListObjectsV2, por lo que se requiere list_version = 2. Con 256M de partes, los archivos grandes se suben en muchas menos partes que con el valor predeterminado de 5M de rclone. rclone mantiene 4 partes por transferencia en memoria, por lo que --transfers 16 a continuación requiere aproximadamente 16 GB de RAM; redúcelo en una máquina más pequeña. Luego copia y verifica:

rclone copy aws:my-source-bucket hf:<bucket> --transfers 16 --checkers 16 --progress
rclone check aws:my-source-bucket hf:<bucket>

rclone copy transfiere solo los objetos que faltan o que han cambiado, por lo que es seguro volver a ejecutarlo para reanudar. Antes de una importación grande, lea las limitaciones de la pasarela, en particular las reglas de nomenclatura de las claves de objeto.

Desde Google Cloud Storage o Azure Blob Storage

Mismo enfoque que con S3: monta la fuente con el propio controlador de su nube y luego ejecuta hf sync.

Google Cloud Storage: montar con gcsfuse.

gcsfuse my-gcs-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Azure Blob Storage: monta con blobfuse2. El archivo de configuración especifica tu cuenta de almacenamiento y tu contenedor.

blobfuse2 mount /mnt/src --config-file=./blobfuse2.yaml
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Sin un montaje, puedes usar rclone (lee GCS y Azure de forma nativa; reutiliza el remoto hf anterior, con el mismo compromiso de no deduplicación), o ejecutar la migración como un Job.

Ejecuta la migración en segundo plano con Jobs

Jobs ejecuta un script en la infraestructura de cómputo de Hugging Face: eliges el hardware, lo lanzas desde la CLI y pagas por minuto. Úsalo cuando quieras que una migración larga, de varios TB, se ejecute de forma autónoma en lugar de en tu portátil o en una sesión que tengas que mantener abierta.

1. Escribir el script de migración (migrate.py). Este ejemplo copia cada objeto de un prefijo de S3 a un bucket a través del cliente Xet, de modo que las escrituras se deduplican. Es adecuado para una copia puntual de un prefijo de tamaño moderado; para prefijos muy grandes, consulte hf-s3ream. Ajuste la configuración en la parte superior:

# /// script
# dependencies = ["huggingface_hub", "boto3", "tqdm"]
# ///
import boto3
from botocore import UNSIGNED
from botocore.config import Config
from huggingface_hub import HfFileSystem
from tqdm.contrib.concurrent import thread_map

# --- adapt these ---
SRC_BUCKET = "my-source-bucket"
SRC_PREFIX = "some/prefix/"
DST = "buckets/<namespace>/<bucket>"
WORKERS = 8   # files copied in parallel
# -------------------

s3 = boto3.client("s3")   # AWS credentials come from the Job's secrets
# For a public bucket (for example from the AWS Open Data registry), read anonymously
# instead, and drop the AWS secrets from the launch command:
# s3 = boto3.client("s3", config=Config(signature_version=UNSIGNED))
fs = HfFileSystem()       # HF token comes from the Job's HF_TOKEN secret

# List the destination once: {path: size} of the files already copied
done = {path: info["size"] for path, info in fs.find(DST, detail=True).items()}

# List the source and keep the objects not copied yet
todo = []
pages = s3.get_paginator("list_objects_v2").paginate(Bucket=SRC_BUCKET, Prefix=SRC_PREFIX)
for page in pages:
    for obj in page.get("Contents", []):
        key = obj["Key"]
        if key.endswith("/"):
            continue  # folder marker: bucket keys can't end with "/"
        if done.get(f"{DST}/{key}") != obj["Size"]:
            todo.append(key)

def copy(key):
    body = s3.get_object(Bucket=SRC_BUCKET, Key=key)["Body"]
    with fs.open(f"{DST}/{key}", "wb") as out:
        for chunk in iter(lambda: body.read(64 << 20), b""):
            out.write(chunk)

# Copy WORKERS files at a time, with a progress bar
thread_map(copy, todo, max_workers=WORKERS)

• Cada objeto se almacena en el disco del Job y se sube cuando se cierra, por lo que el disco debe poder contener WORKERS de tus objetos más grandes a la vez. Aumenta WORKERS para acelerar la subida de muchos objetos pequeños; redúcelo para objetos muy grandes.
• Los archivos que ya están en el bucket con el mismo tamaño se omiten, por lo que volver a ejecutar el script reanuda una copia interrumpida. No volverá a copiar un archivo de origen que cambió pero mantuvo su tamaño: para mantener un bucket al día con un origen que cambia, monta el origen y ejecuta hf sync en su lugar.

Para GCS o Azure, sustituya boto3 por el SDK de esa nube (google-cloud-storage, azure-storage-blob) y ajuste las llamadas de listado y lectura. La mitad de destino permanece igual.

2. Inícialo como un trabajo en segundo plano, pasando tus credenciales como secretos:

hf jobs uv run --detach --flavor cpu-performance --timeout 24h \
  --secrets HF_TOKEN \
  --secrets AWS_ACCESS_KEY_ID \
  --secrets AWS_SECRET_ACCESS_KEY \
  migrate.py

Cada --secrets NAME pasa el valor de esa variable desde su entorno (para HF_TOKEN, se usa su token de sesión si no está definido). Los Jobs se detienen por defecto después de 30 minutos, así que configure --timeout lo suficientemente largo para toda la transferencia; si un Job se detiene antes, inícielo de nuevo y omitirá los archivos ya copiados.

--detach devuelve de inmediato un ID de trabajo. Sigue el progreso con hf jobs logs -f <job_id>, lista las ejecuciones con hf jobs ls y consulta las opciones de hardware con hf jobs hardware.

Desde un repositorio de Hub u otro bucket

Si los datos ya están en el Hub, en un repositorio de modelo o de conjunto de datos o en otro bucket, cópielos en el lado del servidor. Para los archivos con seguimiento de Xet, solo se mueven los hashes de contenido, por lo que la copia es casi instantánea y no se vuelve a subir nada.

# From a dataset repository into a bucket
hf buckets cp hf://datasets/<org>/<dataset>/<path> hf://buckets/<namespace>/<bucket>/<path>

# From one bucket to another
hf buckets cp hf://buckets/<namespace>/<bucket-a>/<path> hf://buckets/<namespace>/<bucket-b>/<path>

• La fuente y el destino deben estar en la misma región de almacenamiento.
• Necesitas acceso de lectura a la fuente y acceso de escritura al destino.
• Los archivos pequeños que no están bajo el control de Xet (configuraciones, READMEs) se descargan y vuelven a subir automáticamente.
• Copiar desde un bucket de vuelta a un repositorio aún no está disponible; está en la hoja de ruta.

Vea Copiar archivos entre repositorios y cubos para el equivalente en Python.

Prefijos S3 muy grandes con hf-s3ream

hf-s3ream es una herramienta comunitaria en una etapa temprana (alfa) y no es un producto de Hugging Face con soporte oficial. Pruébela con un prefijo pequeño antes de usarla para una migración a gran escala.

hf-s3ream (fuente en GitHub, Apache-2.0) ejecuta una copia de S3 a bucket de gran tamaño desde una interfaz web:

1. Inicia sesión con Hugging Face.
2. Introduce el prefijo de origen de S3, el bucket de destino y tus credenciales de AWS. Para un bucket público que permite lecturas anónimas, activa Public bucket: no se necesitan credenciales de AWS y los Jobs leen S3 sin firmar.
3. Analyze ejecuta una ejecución de prueba de bajo costo que verifica el acceso, detecta la región de origen y recomienda una configuración. Crea el bucket de destino (privado) si no existe.
4. Run inicia un trabajo de planificador. El planificador crea un plan de copia basado en rangos, inicia los trabajos de copiado y muestra el progreso en un gráfico en vivo. La copia continúa si cierras la pestaña, pero la página no se volverá a conectar a ella. Para detener una copia, haz clic en Stop copy o cancela el trabajo del planificador (hf jobs cancel <planner-job-id>): el planificador cancela sus copias.

hf-s3ream se ejecuta en Jobs bajo tu cuenta, por lo que los Jobs se facturan a ti. Los buckets de S3 que solo permiten el acceso desde una red privada (VPC) no pueden ser alcanzados desde Jobs.

Dónde ejecutar una migración a gran escala

Para una migración de varios TB, normalmente se ejecuta la transferencia en una VM en la nube en lugar de en un portátil. Si prefiere no gestionar una VM, ejecútela como un Job.

• Ejecútelo en la misma nube y región que su origen. Leer el origen a través de la red local es la opción más rápida y económica, y la salida de datos desde la nube de origen suele ser el mayor costo. Las cargas se realizan luego a través de internet hacia Hugging Face (la región de EE. UU. está en AWS us-east-1).
• Use un proceso con muchos hilos. Un único hf sync en modo de alto rendimiento comparte una única caché de deduplicación. Divide por subruta solo cuando un proceso no pueda saturar tu red.
• Mantén las ejecuciones largas activas. Por SSH, inicia la migración dentro de tmux (o screen, o nohup) para que sobreviva a una sesión interrumpida: tmux new -s migrate, desconéctate con Ctrl-b y luego d, y vuelve a conectarte más tarde con tmux attach -t migrate.

Puntos de partida para el dimensionado, para validar en una ejecución de prueba:

Próximos pasos

• Usa los datos en su ubicación original. Monta el bucket como un sistema de archivos local con hf-mount, o como un volumen en Jobs y Spaces.
• Léelo desde tus herramientas. pandas, Dask, PyArrow, Daft, DuckDB, 🤗 Datasets y Spark leen las rutas hf://buckets/... directamente. Consulta Integraciones de Bucket.

No realices una ingesta masiva a través de un montaje. hf-mount almacena las escrituras en una caché en disco (/tmp/hf-mount-cache de forma predeterminada) y una migración grande a través de él puede llenar ese disco. Usa una de las rutas anteriores para cargar datos en un bucket. Si debes escribir mucho a través de un montaje, apunta la caché a un disco con mucho espacio libre: hf-mount start --cache-dir /mnt/big bucket <namespace>/<bucket> /mnt/data (el flag va antes de bucket).