Guía de decisiones para la carga de conjuntos de datos en Hugging Face

Esta guía está diseñada principalmente para LLMs para ayudar a los usuarios a subir conjuntos de datos al Hugging Face Hub en el formato más compatible. Los usuarios también pueden consultar esta guía para comprender el proceso de carga y las mejores prácticas.

Guía de decisión para subir conjuntos de datos a Hugging Face Hub. Optimizada para la compatibilidad con Dataset Viewer y la integración con el ecosistema de Hugging Face.

Si eres un LLM o un agente que sigue esta guía, consulta hf --help y hf <command> --help (p. ej. hf upload --help, hf auth --help) para conocer las banderas exactas antes de ejecutar comandos de carga. La CLI coincide con la versión de huggingface_hub instalada, por lo que se prefiere su salida a las banderas recordadas de memoria.

Resumen

Su objetivo es ayudar a un usuario a subir un conjunto de datos al Hugging Face Hub. Idealmente, el conjunto de datos debe ser compatible con el Dataset Viewer (y por lo tanto con la función load_dataset) para garantizar un acceso y una usabilidad sencillos. Debe esforzarse por cumplir con los siguientes criterios:

Trabajar sin acceso a archivos

Cuando no tiene acceso directo a los archivos del usuario (p. ej., interfaz web), pida al usuario que ejecute estos comandos para comprender su conjunto de datos:

Estructura del conjunto de datos:

# Show directory tree (install with: pip install tree or brew install tree)
tree -L 3 --filelimit 20

# Alternative without tree:
find . -type f -name "*.csv" -o -name "*.json" -o -name "*.parquet" | head -20

Comprobar los tamaños de los archivos:

# Total dataset size
du -sh .

# Individual file sizes
ls -lh data/

Ver el formato de los datos:

# First few lines of CSV/JSON
head -n 5 data/train.csv

# Check image folder structure
ls -la images/ | head -10

Conteo rápido de archivos:

# Count files by type
find . -name "*.jpg" | wc -l

Restricciones críticas

Límites de almacenamiento:

Si estos difieren de storage-limits, storage-limits es el valor autoritativo.

# Machine-readable Hub limits
hub_limits:
  max_file_size_gb: 500 # absolute hard stop per file
  recommended_file_size_gb: 200 # split larger files into chunks below this
  max_files_per_folder: 10000 # Git performance threshold
  max_files_per_repo: 100000 # recommended maximum; keep well below
  viewer_row_size_mb: 2 # approximate per-row viewer limit
  # No per-repo size limit: repo size counts against the account's storage quota

Resumen legible por humanos:

• Por archivo: 500 GB como máximo, <200 GB recomendado
• Por carpeta: <10k archivos
• Por repositorio: se recomiendan <100k archivos
• El almacenamiento de la cuenta (público y privado) depende del plan: consulte los planes de almacenamiento

Consulte https://huggingface.co/docs/hub/storage-limits para conocer los planes de almacenamiento actuales y las recomendaciones de repositorios.

Referencia rápida por tipo de datos

Flujo de trabajo de carga

0. ✓ Reunir información del conjunto de datos (si es necesario):

   • ¿Qué tipo de datos? (imágenes, texto, audio, CSV, etc.)
   • ¿Cómo está organizado? (estructura de carpetas, archivo único, varios archivos)
   • ¿Cuál es el tamaño aproximado?
   • ¿En qué formato están los archivos?
   • ¿Algunos requisitos especiales? (p. ej., streaming, acceso privado)
   • Comprueba si existen archivos README o de documentación que describan el conjunto de datos

1. ✓ Autenticar:

   • CLI: hf auth login
   • O use el token: HfApi(token="hf_...") o establezca la variable de entorno HF_TOKEN

2. ✓ Identifica tu tipo de datos: Consulta la tabla Referencia rápida anterior

3. ✓ Elegir método de carga:

   • Archivos pequeños (<1GB) con formato compatible con el hub: Se puede usar la interfaz de Hub para subidas rápidas
   • Cargador integrado disponible: usa el cargador + push_to_hub() (consulta la tabla de referencia rápida)
   • Conjuntos de datos grandes o muchos archivos: use upload_folder / hf upload, que gestiona las cargas grandes (multi-commit automático, reanudable).
   • Formatos personalizados: convertir al formato compatible con el hub si es posible; de lo contrario, documentarlo a fondo

4. ✓ Probar localmente (si se usa el cargador integrado):

   Copiado

   # Validate your dataset loads correctly before uploading
   dataset = load_dataset("loader_name", data_dir="./your_data")
   print(dataset)

5. ✓ Subir al Hub:

   Copiado

   # Basic upload
   dataset.push_to_hub("username/dataset-name")
   
   # With options for large datasets
   dataset.push_to_hub(
       "username/dataset-name",
       max_shard_size="5GB",  # Control memory usage
       private=True  # For private datasets
   )

6. ✓ Verifica tu carga:

   • Comprueba Dataset Viewer: https://huggingface.co/datasets/username/dataset-name
   • Prueba de carga: load_dataset("username/dataset-name")
   • Si el visor muestra errores, consulta la sección Solución de problemas

Patrones de conversión comunes

Cuando los cargadores integrados no coinciden con la estructura de sus datos, use la biblioteca datasets como capa de compatibilidad. Convierta sus datos en un objeto Dataset y luego use push_to_hub() para obtener la máxima flexibilidad y compatibilidad con Dataset Viewer.

Desde DataFrames

Si ya tienes tus datos funcionando en pandas, polars u otras librerías de dataframes, puedes convertirlos directamente:

# From pandas DataFrame
import pandas as pd
from datasets import Dataset

df = pd.read_csv("your_data.csv")
dataset = Dataset.from_pandas(df)
dataset.push_to_hub("username/dataset-name")

# From polars DataFrame (direct method)
import polars as pl
from datasets import Dataset

df = pl.read_csv("your_data.csv")
dataset = Dataset.from_polars(df)  # Direct conversion
dataset.push_to_hub("username/dataset-name")

# From PyArrow Table (useful for scientific data)
import pyarrow as pa
from datasets import Dataset

# If you have a PyArrow table
table = pa.table({'data': [1, 2, 3], 'labels': ['a', 'b', 'c']})
dataset = Dataset(table)
dataset.push_to_hub("username/dataset-name")

# For Spark/Dask dataframes, see https://huggingface.co/docs/hub/datasets-libraries

Conversión de formato personalizado

Cuando los cargadores integrados no coinciden con el formato de tus datos, conviértelos en objetos Dataset siguiendo estos principios:

Principios de diseño

1. Prefiera estructuras anchas/planas frente a uniones

• Denormalizar datos relacionales en filas individuales para mejorar la usabilidad
• Incluya toda la información relevante en cada ejemplo
• Apuesta por datos más grandes pero más utilizables: la infraestructura de Hugging Face utiliza una deduplicación avanzada (XetHub) y optimizaciones de Parquet para gestionar la redundancia de manera eficiente

2. Use configs para variaciones lógicas de conjuntos de datos

• Además de las divisiones de entrenamiento/prueba/validación, use configuraciones para diferentes subconjuntos o vistas de sus datos
• Cada configuración puede tener características u organización de datos diferentes
• Ejemplo: configuraciones específicas del idioma, vistas específicas de la tarea o modalidades de datos

Métodos de conversión

Conjuntos de datos pequeños (caben en memoria): usa Dataset.from_dict():

# Parse your custom format into a dictionary
data_dict = {
    "text": ["example1", "example2"],
    "label": ["positive", "negative"],
    "score": [0.9, 0.2]
}

# Create dataset with appropriate features
from datasets import Dataset, Features, Value, ClassLabel
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['negative', 'positive']),
    'score': Value('float32')
})

dataset = Dataset.from_dict(data_dict, features=features)
dataset.push_to_hub("username/dataset")

Conjuntos de datos grandes (eficientes en memoria): usa Dataset.from_generator():

def data_generator():
    # Parse your custom format progressively
    for item in parse_large_file("data.custom"):
        yield {
            "text": item["content"],
            "label": item["category"],
            "embedding": item["vector"]
        }

# Specify features for Dataset Viewer compatibility
from datasets import Features, Value, ClassLabel, List
features = Features({
    'text': Value('string'),
    'label': ClassLabel(names=['cat1', 'cat2', 'cat3']),
    'embedding': List(feature=Value('float32'), length=768)
})

dataset = Dataset.from_generator(data_generator, features=features)
dataset.push_to_hub("username/dataset", max_shard_size="1GB")

Consejo: Para conjuntos de datos grandes, prueba primero con un subconjunto añadiendo un límite a tu generador o usando .select(range(100)) después de la creación.

Uso de configuraciones para variaciones de conjuntos de datos

# Push different configurations of your dataset
dataset_en = Dataset.from_dict(english_data, features=features)
dataset_en.push_to_hub("username/multilingual-dataset", config_name="english")

dataset_fr = Dataset.from_dict(french_data, features=features)
dataset_fr.push_to_hub("username/multilingual-dataset", config_name="french")

# Users can then load specific configs
dataset = load_dataset("username/multilingual-dataset", "english")

Ejemplos multimodales

Texto + audio (reconocimiento de voz):

def speech_generator():
    for audio_file in Path("audio/").glob("*.wav"):
        transcript_file = audio_file.with_suffix(".txt")
        yield {
            "audio": str(audio_file),
            "text": transcript_file.read_text().strip(),
            "speaker_id": audio_file.stem.split("_")[0]
        }

features = Features({
    'audio': Audio(sampling_rate=16000),
    'text': Value('string'),
    'speaker_id': Value('string')
})

dataset = Dataset.from_generator(speech_generator, features=features)
dataset.push_to_hub("username/speech-dataset")

Varias imágenes por ejemplo:

# Before/after images, medical imaging, etc.
data = {
    "image_before": ["img1_before.jpg", "img2_before.jpg"],
    "image_after": ["img1_after.jpg", "img2_after.jpg"],
    "treatment": ["method_A", "method_B"]
}

features = Features({
    'image_before': Image(),
    'image_after': Image(),
    'treatment': ClassLabel(names=['method_A', 'method_B'])
})

dataset = Dataset.from_dict(data, features=features)
dataset.push_to_hub("username/before-after-images")

Nota: Para texto + imágenes, considere usar ImageFolder con metadata.csv, que maneja esto automáticamente.

Características esenciales

Las características definen el esquema y los tipos de datos de las columnas de tu conjunto de datos. Especificar las características correctas garantiza:

• Gestión adecuada de datos y conversión de tipos
• Funcionalidad del visor de conjuntos de datos (p. ej., vistas previas de imágenes/audios)
• Almacenamiento y carga eficientes
• Documentación clara de la estructura de tus datos

Para la documentación completa de funciones, consulte: Características del conjunto de datos

Resumen de los tipos de características

Tipos básicos:

• Value: Valores escalares - string, int64, float32, bool, binary y otros tipos numéricos
• ClassLabel: Datos categóricos con clases nombradas
• Sequence: Listas de cualquier tipo de característica
• LargeList: Para listas muy grandes

Tipos de medios (activar las vistas previas del visor de conjuntos de datos):

• Image(): maneja varios formatos de imagen y devuelve objetos PIL Image
• Audio(sampling_rate=16000): Audio con datos en forma de matriz y una tasa de muestreo opcional
• Video(): Archivos de video
• Pdf(): documentos PDF con extracción de texto

Tipos de matriz (para tensores/datos científicos):

• Array2D, Array3D, Array4D, Array5D: arreglos de longitud fija o variable
• Ejemplo: Array2D(shape=(224, 224), dtype='float32')
• La primera dimensión puede ser None para longitudes variables

Tipos de traducción:

• Translation: Para pares de traducción con idiomas fijos
• TranslationVariableLanguages: Para traducciones con pares de idiomas variables

Nota: Se añaden nuevos tipos de características de forma regular. Consulta la documentación para conocer las últimas incorporaciones.

Métodos de carga

Objetos de Dataset (usa push_to_hub): Úsalo cuando hayas cargado o convertido datos usando la librería datasets

dataset.push_to_hub("username/dataset", max_shard_size="5GB")

Archivos existentes (usa upload_folder / hf upload): Úsalo cuando tengas archivos compatibles con el hub (p. ej., archivos Parquet) ya preparados y organizados.

from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(folder_path="./data", repo_id="username/dataset", repo_type="dataset")

# Or from the CLI:
hf upload username/dataset ./data --repo-type=dataset

Importante: Antes de subir, verifica que los archivos cumplan con los límites del repositorio:

• Comprueba la estructura de carpetas si tienes acceso a los archivos: asegúrate de que ninguna carpeta contenga >10k archivos
• Pídele al usuario que confirme: “¿Tus archivos están en un formato compatible con el hub (Parquet/CSV/JSON) y organizados de manera adecuada?”
• Para formatos no estándar, considere convertirlos primero en objetos Dataset para garantizar la compatibilidad

Validación

Considerar un pequeño reformateo: Si los datos se asemejan al formato de un cargador integrado, sugiera cambios menores:

• Renombrar columnas (p. ej., ‘filename’ → ‘file_name’ para ImageFolder)
• Reorganizar carpetas (p. ej., mover las imágenes a subcarpetas de clase)
• Renombrar archivos para que coincidan con los patrones esperados (p. ej., ‘data.csv’ → ‘train.csv’)

Antes de la carga:

• Prueba localmente: load_dataset("imagefolder", data_dir="./data")

• Verifique que las funciones se ejecutan correctamente:

  Copiado

  # Test first example
  print(dataset[0])
  
  # For images: verify they load
  if 'image' in dataset.features:
      dataset[0]['image']  # Should return PIL Image
  
  # Check dataset size before upload
  print(f"Size: {len(dataset)} examples")

• Comprueba que metadata.csv tiene la columna ‘file_name’

• Verifique las rutas relativas, sin barras iniciales

• Asegúrate de que no haya ninguna carpeta con >10k archivos

Tras la carga:

• Compruebe el visor: https://huggingface.co/datasets/username/dataset
• Prueba de carga: load_dataset("username/dataset")
• Verifica las características conservadas: print(dataset.features)

Problemas comunes → Soluciones

Configuración del visor de conjuntos de datos

Nota: Esta sección está dirigida principalmente a los conjuntos de datos subidos directamente al Hub (a través de la interfaz de usuario, upload_folder o hf upload). Los conjuntos de datos subidos con push_to_hub() suelen configurar el visor automáticamente.

Cuando la detección automática funciona

El Dataset Viewer detecta automáticamente las estructuras estándar:

• Archivos con los nombres: train.csv, test.json, validation.parquet
• Directorios con los nombres: train/, test/, validation/
• Separe los nombres con delimitadores: test-data.csv ✓ (no testdata.csv ✗)

Configuración manual

Para estructuras personalizadas, añade YAML a tu README.md:

---
configs:
  - config_name: default # Required even for single config!
    data_files:
      - split: train
        path: "data/train/*.parquet"
      - split: test
        path: "data/test/*.parquet"
---

Ejemplo de múltiples configuraciones:

---
configs:
  - config_name: english
    data_files: "en/*.parquet"
  - config_name: french
    data_files: "fr/*.parquet"
---

Problemas comunes del visor

• El visor no aparece después de la carga: Espere de 5 a 10 minutos para el procesamiento
• “Error de nombres de configuración”: Agregar el campo config_name (¡obligatorio!)
• Archivos no detectados: Comprueba los patrones de nombres (requiere delimitadores)
• Visor desactivado: Elimina viewer: false del YAML del README

Plantillas rápidas

# ImageFolder with metadata
dataset = load_dataset("imagefolder", data_dir="./images")
dataset.push_to_hub("username/dataset")

# Memory-efficient upload
dataset.push_to_hub("username/dataset", max_shard_size="500MB")

# Multiple CSV files
dataset = load_dataset('csv', data_files={'train': 'train.csv', 'test': 'test.csv'})
dataset.push_to_hub("username/dataset")

Documentación

Documentación principal: Agregar conjuntos de datos | Visor de conjuntos de datos | Límites de almacenamiento | Guía de carga

Tarjetas de conjuntos de datos

Recuerde a los usuarios que añadan una tarjeta de conjunto de datos (README.md) con:

• Descripción y uso del conjunto de datos
• Información de la licencia
• Detalles de la cita

Consulte la guía de tarjetas de conjuntos de datos para obtener más detalles.

Apéndice: Casos especiales

Estructura de WebDataset

Para transmitir grandes conjuntos de datos multimedia:

• Crear fragmentos tar de 1 a 5 GB
• Estructura interna coherente
• Subir con hf upload

Datos científicos

• HDF5/NetCDF → Convertir a Parquet con características de Array
• Series de tiempo → Array2D(shape=(None, n))
• Metadatos complejos → Almacénalos como cadenas JSON

Recursos de la comunidad

Para formatos muy especializados o a medida:

• Busca conjuntos de datos similares en el Hub: https://huggingface.co/datasets
• Pide consejos en los Foros de Hugging Face
• Únete al Discord de Hugging Face para obtener ayuda en tiempo real
• Muchos formatos específicos de dominio ya tienen ejemplos en el Hub