Uso de Xet Storage

Python

Para acceder a una versión de huggingface_hub compatible con Xet, simplemente instale la última versión:

pip install -U huggingface_hub

A partir de huggingface_hub 0.32.0, esto también instalará hf_xet. El paquete hf_xet integra huggingface_hub con xet-core, el cliente de Rust para el backend Xet.

Si usas las bibliotecas transformers o datasets, ya están utilizando huggingface_hub. Mientras la versión de huggingface_hub sea >= 0.32.0, no es necesario realizar ninguna acción adicional.

Cuando las versiones de huggingface_hub >= 0.30.0 y < 0.32.0 están instaladas, hf_xet debe instalarse explícitamente:

pip install -U hf-xet

¡Y eso es todo! Ahora obtienes los beneficios de la deduplicación de Xet tanto para las cargas como para las descargas. Los miembros del equipo que utilicen una versión de huggingface_hub < 0.30.0 aún podrán cargar y descargar repositorios a través de la compatibilidad hacia atrás proporcionada por el puente LFS.

Para ver documentación de uso más detallada, consulte la documentación de huggingface_hub para:

• Subir
• Descargar
• Gestión de la caché de hf_xet

Git

Los usuarios de Git pueden acceder a las ventajas de Xet descargando e instalando la extensión Git Xet. Una vez instalada, basta con utilizar los flujos de trabajo estándar para gestionar repositorios de Hub con Git; no es necesario realizar cambios adicionales.

Prerrequisitos

Instala Git y Git LFS.

Instalación en macOS o Linux (amd64 o aarch64)

Instala mediante un script de instalación con el siguiente comando en tu terminal (requiere curl y unzip):

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh

O bien, instálalo usando Homebrew:

brew install git-xet
git xet install

Para verificar la instalación, ejecuta:

git xet --version

Windows (amd64)

Usando winget:

winget install git-xet

Usando un instalador:

• Descarga git-xet-windows-installer-x86_64.zip (disponible aquí) y descomprímelo.
• Ejecute el archivo de instalador msi y siga las indicaciones.

Instalación manual:

• Descarga git-xet-windows-x86_64.zip (disponible aquí) y descomprímelo.
• Coloque el git-xet.exe extraído en un directorio de PATH.
• Ejecuta git xet install en una terminal.

Para verificar la instalación, ejecuta:

git xet --version

Uso de Git Xet

Una vez instalado en tu plataforma, usar Git Xet es tan sencillo como seguir los flujos de trabajo estándar de Git del Hub.

Asegúrate de que todos los prerrequisitos estén instalados y configurados, sigue las instrucciones de configuración para trabajar con repositorios en el Hub, luego confirma tus cambios y push al Hub:

# Create any files you like! Then...
git add .
git commit -m "Uploading new models"  # You can choose any descriptive message
git push

Por debajo, se invoca el protocolo Xet para subir archivos grandes directamente al almacenamiento de Xet, aumentando las velocidades de subida gracias a la deduplicación a nivel de fragmentos.

Desinstalar en macOS o Linux

Usando Homebrew:

git xet uninstall
brew uninstall git-xet

Si usaste el script de instalación (para MacOS o Linux), ejecuta lo siguiente en tu terminal:

git xet uninstall
sudo rm $(which git-xet)

Desinstalar en Windows

Si usaste winget:

winget uninstall git-xet

Si usó el instalador:

• Vaya a Configuración -> Aplicaciones -> Aplicaciones instaladas
• Busque “Git-Xet”.
• Seleccione la opción “Desinstalar” disponible en el menú contextual.

Si lo instalaste manualmente:

• Ejecuta git xet uninstall en una terminal.
• Elimine el archivo git-xet.exe de la ubicación donde se colocó originalmente.

Recomendaciones

Xet se integra de forma transparente con todos los flujos de trabajo del Hub. Sin embargo, hay algunos pasos que puedes considerar para aprovechar al máximo el almacenamiento de Xet.

Al subir o descargar con Python:

• Asegúrate de que hf_xet esté instalado: Aunque Xet mantiene la compatibilidad hacia atrás con los clientes heredados optimizados para Git LFS, la integración de hf_xet con huggingface_hub ofrece un rendimiento óptimo basado en fragmentos y una iteración más rápida en archivos grandes.
• La concurrencia adaptativa está activada de forma predeterminada: hf_xet ajusta automáticamente el número de flujos de transferencia paralelos en función de las condiciones de red en tiempo real, sin necesidad de configuración. La configuración predeterminada saturará la mayoría de las rutas de red sin ningún ajuste.
• Los búferes de descarga se escalan con la memoria del sistema: A partir de hf_xet 1.7.0, el tamaño de los búferes de descarga se determina en función de la memoria disponible para hf_xet, incluidos los límites de memoria del contenedor. Los contenedores pequeños usan menos memoria para las descargas y las máquinas grandes usan más, sin necesidad de configurar nada. Consulte Búferes de descarga.
• Ajuste avanzado: Para un control de gran granularidad, HF_XET_FIXED_DOWNLOAD_CONCURRENCY y HF_XET_FIXED_UPLOAD_CONCURRENCY permiten fijar la concurrencia a un valor fijo, omitiendo el controlador adaptativo. Consulte las variables de entorno de hf_xet para obtener la lista completa de opciones.

Al subir o descargar en Git o Python:

• Aprovecha los commits incrementales y frecuentes: la deduplicación a nivel de fragmentos de Xet permite realizar actualizaciones incrementales de modelos o conjuntos de datos de forma segura. Solo se suben los fragmentos modificados, por lo que los commits frecuentes son rápidos y eficientes en almacenamiento.
• Sea específico en .gitattributes: al definir patrones para Xet o LFS, use extensiones de archivo precisas (p. ej., *.safetensors, *.bin) para evitar enrutar archivos más pequeños a través del almacenamiento de archivos grandes de forma innecesaria.
• Prioriza el acceso de la comunidad: Xet aumenta de forma sustancial la eficiencia y la escala de las transferencias de archivos grandes. En lugar de estructurar tu repositorio para reducir su tamaño total (o el tamaño de los archivos individuales), organízalo para los colaboradores y los usuarios de la comunidad, de modo que puedan navegar y recuperar fácilmente el contenido que necesitan.

Subida a través de un proxy o un cortafuegos

A partir de hf_xet 1.8.0, las cargas pueden enviar datos directamente a Amazon S3 en lugar de solo a través del servicio de almacenamiento Xet. El Hub decide para cada carga si usar la carga directa, y la está activando gradualmente. Las descargas no cambian.

Si su red restringe el tráfico saliente, permita estos nombres de host (HTTPS, puerto 443) además de los que se enumeran en Descarga detrás de un proxy o firewall:

Estos nombres de host no están bajo hf.co ni huggingface.co, por lo que permitir esos sufijos no los cubre.

Si hf_xet no puede alcanzar S3, reintenta la carga directa y luego envía esos datos a través del servicio de almacenamiento Xet. La carga se completa igualmente, pero puede ser mucho más lenta, porque cada bloque espera a que se agoten los reintentos primero. El registro de hf_xet muestra Upload grant URL unreachable, falling back to legacy xorb upload path (may be slower) cuando ocurre esto. Si no puede permitir los nombres de host de S3, establezca HF_XET_CLIENT_LEGACY_DIRECT_XORB_UPLOAD=1 para desactivar las cargas directas.

Variables de entorno

Tanto hf_xet como Git Xet funcionan con xet-core, que se puede configurar mediante variables de entorno. Las tablas siguientes enumeran las variables individuales para un control detallado. La mayoría de los usuarios no necesitará modificar ninguna de estas: los valores predeterminados están ajustados para saturar automáticamente la mayoría de las rutas de red.

HF_XET_HIGH_PERFORMANCE=1 es una bandera de conveniencia que ajusta varios ajustes a la vez (límites de concurrencia, tamaños de búfer y límites de archivos paralelos). Está destinada a máquinas con ancho de banda alto y disco rápido. A partir de hf_xet 1.7.0, los tamaños de búfer que establece se basan en la memoria disponible para hf_xet (ver Búferes de descarga), por lo que ya no requiere 64 GB de RAM, y cualquier variable que defina usted mismo tiene prioridad sobre esta bandera. Con versiones anteriores, úsela solo en máquinas con al menos 64 GB de RAM.

General

Banderas de alto nivel que la mayoría de los usuarios suelen utilizar primero.

Concurrencia adaptativa

Por defecto, xet-core utiliza concurrencia adaptativa, ajustando dinámicamente el paralelismo en función de las condiciones de red en tiempo real. Estas son configuraciones avanzadas que probablemente no sean necesarias en la mayoría de los casos. Las variables siguientes controlan el comportamiento del controlador adaptativo:

Para fijar la concurrencia en un valor fijo (omitir el controlador adaptativo), use los alias de conveniencia HF_XET_FIXED_UPLOAD_CONCURRENCY y HF_XET_FIXED_DOWNLOAD_CONCURRENCY. Estos establecen la concurrencia inicial, mínima y máxima en el mismo valor.

Red y reintentos

Transferencia de datos

Descargar buffers

Estos controlan el uso de memoria durante las descargas.

A partir de hf_xet 1.7.0, los valores predeterminados de las tres variables DOWNLOAD_BUFFER se basan en la cantidad de memoria que hf_xet puede utilizar. Esto corresponde a la RAM del equipo, o al límite de memoria del contenedor si este es menor. Cada valor predeterminado es una fracción de esa memoria, limitada entre el mínimo y el máximo indicados en la tabla. El modo HP utiliza el doble de la fracción, con el mismo mínimo y máximo. Por ejemplo, un contenedor limitado a 4 GB obtiene un búfer de aproximadamente 256 MB con un límite de 1 GB, y un equipo con 32 GB obtiene aproximadamente el mismo búfer de 2 GB y límite de 8 GB que en versiones anteriores.

Las versiones anteriores, o cualquier versión que no pueda determinar la cantidad de memoria disponible, usan valores predeterminados fijos de 2gb, 512mb y 8gb (16gb, 2gb y 64gb en modo HP). Los valores en uso se escriben en el archivo de registro hf_xet al iniciar (consulte Registro).

Caché de fragmentos

El shard cache almacena en disco, bajo el directorio de caché de Xet, el índice de deduplicación (los “shards” que describen los fragmentos ya subidos). Una caché más grande permite al cliente deduplicar contra más datos vistos previamente, de modo que se vuelven a subir menos bytes.

Caché de fragmentos

hf_xet ya no utiliza una caché local de fragmentos para las descargas. Los archivos descargados se siguen almacenando en la caché basada en archivos de huggingface_hub.

Registro

Telemetría

hf_xet envía un informe breve después de cada carga y descarga. Consulte Telemetría para ver qué contiene. Para desactivarlo, establezca HF_HUB_DISABLE_TELEMETRY=1.

Limitaciones actuales

Aunque Xet aporta deduplicación de granularidad fina y un rendimiento mejorado al almacenamiento basado en Git, algunas funciones y compatibilidades de plataforma aún están en desarrollo. Como resultado, tenga en cuenta las siguientes restricciones al trabajar con un repositorio habilitado para Xet:

• Solo sistemas de 64 bits: Tanto hf_xet como Git Xet requieren actualmente una arquitectura de 64 bits; los sistemas de 32 bits no son compatibles.