Conjuntos de datos de Hugging Face: Referencia para desarrolladores

Un conjunto de datos de Hugging Face es una colección estructurada y versionada de datos almacenada en el Hugging Face Hub y consumida mediante la biblioteca Python datasets . Cada conjunto de datos expone una o másdivisiones (típicamente entrenamiento, validación y prueba), un esquema tipado que describe cada columna, y metadatos que incluyen licencia, categoría de tarea y etiquetas lingüísticas. La biblioteca se encarga de la descarga, la caché y la conversión de formatos, por lo que casi nunca tiene que trabajar directamente con archivos sin procesar.características esquema que describe cada columna y metadatos que incluyen licencia, categoría de tarea y etiquetas de idioma. La biblioteca se encarga de la descarga, la caché y la conversión de formatos, por lo que casi nunca tienes que trabajar directamente con archivos sin procesar.

Búsqueda de conjuntos de datos en el Hub

La principal superficie de descubrimiento es huggingface.co/datasets. Los filtros disponibles en la interfaz de usuario son:

• Tarea — clasificación de texto, respuesta a preguntas, segmentación de imágenes, traducción, resumen, etc.
• Idioma — códigos ISO 639-1 (en, zh, fr, de, …)
• Licencia — Apache 2.0, MIT, CC-BY, CC0, OpenRAIL, etc.
• Categoría de tamaño — menos de 1 000 filas hasta más de 1 000 000 000 de filas
• Modalidad — texto, imagen, audio, video, tabular, multimodal

También puede buscar mediante programación usando el cliente Python del Hub:

from huggingface_hub import list_datasets

results = list_datasets(filter='task_categories:text-classification', limit=20)
for ds in results:
    print(ds.id, ds.downloads)

La API REST del Servidor de Conjuntos de Datos expone un punto final /valid que enumera todos los conjuntos de datos con exportaciones precalculadas en formato Parquet, lo que permite obtener vistas previas rápidas y muestreo de filas sin necesidad de descargar el conjunto de datos completo.

Instalación

Eldatasets La biblioteca funciona en Python 3.8+ y es independiente de la plataforma.

pip install datasets

Para soporte de imágenes y audio, instale los complementos correspondientes:

pip install datasets[vision]# Pillow
pip install datasets    # librosa, soundfile

Para autenticarse en conjuntos de datos privados o para publicar datos en el Hub:

pip install huggingface_hub
huggingface-cli login          # solicita su token de acceso a HF

Su token se almacena en ~/.cache/huggingface/token en macOS/Linux o en %USERPROFILE%.cachehuggingfacetoken en Windows. Alternativamente, puede establecer directamente la variable de entorno HF_TOKEN .

Carga de un conjunto de datos

El punto de entrada principal es load_dataset(). Sin un argumentosplit devuelve un DatasetDict que contiene todas las divisiones disponibles:

from datasets import load_dataset

ds = load_dataset('stanfordnlp/imdb')
print(ds)
# DatasetDict({
#     train: Dataset({features: ['text', 'label'], num_rows: 25000})
#     test:  Dataset({features: ['text', 'label'], num_rows: 25000})
# })

train = ds['train']
print(train.features)
# {'text': Value(dtype='string'), 'label': ClassLabel(names=['neg', 'pos'])}

print(train[0]['text'][:120])

Cargando una única división

train = load_dataset('stanfordnlp/imdb', split='train')
# Devuelve un Dataset directamente, no un DatasetDict

Cargando una configuración con nombre

Muchos conjuntos de datos definen configuraciones con nombre para variantes lingüísticas, subconjuntos por dominio o versiones del esquema. Pase el nombre de la configuración como segundo argumento posicional:

ds = load_dataset('Helsinki-NLP/opus_books', 'en-fr')

Para enumerar todas las configuraciones disponibles de un conjunto de datos antes de cargarlo:

from datasets import get_dataset_config_names
print(get_dataset_config_names('Helsinki-NLP/opus_books'))

Cargando desde archivos locales

Pase un nombre de formato y una ruta de archivo en lugar de un identificador de conjunto de datos del Hub. Los formatos admitidos incluyen CSV, JSON/JSONL, Parquet, Arrow, texto sin formato, y las convenciones ImageFolder/AudioFolder.

ds = load_dataset('csv', data_files='my_data.csv')
ds = load_dataset('json', data_files={'train': 'train.jsonl', 'test': 'test.jsonl'})
ds = load_dataset('imagefolder', data_dir='./photos/')

Estructura de un conjunto de datos: divisiones y características

Compruebe qué divisiones tiene un conjunto de datos antes de cargarlo:

from datasets import get_dataset_split_names
print(get_dataset_split_names('stanfordnlp/imdb'))
# ['train', 'test', 'unsupervised']

Elcaracterísticas El diccionario asigna nombres de columnas a descriptores tipados. Tipos de características comunes:

Streaming de conjuntos de datos grandes

Para conjuntos de datos demasiado grandes para descargar —por ejemplo, Common Crawl, The Pile o LAION-5B— pase streaming=True. Los datos se obtienen y decodifican sobre la marcha sin ocupar espacio en disco:

ds = load_dataset('allenai/c4', 'en', split='train', streaming=True)

for example in ds.take(1000):
    print(example['text'][:80])

El modo de transmisión devuelve unIterableDataset en lugar de un Dataset. Admite.map(), .filter(), .shuffle(buffer_size=N), y .take(N), pero no permite indexación aleatoria ni len(). Para obtener un fragmento fijo sin transmitir todo el conjunto de datos:

ds = load_dataset('allenai/c4', 'en', split='train[:50000]')

La segmentación por división acepta recuentos absolutos de filas ([:50000]), porcentajes ([:10%]) y rangos con paso ([10%:20%]).

Filtrado y procesamiento

Todas las operaciones se ejecutan en Apache Arrow y utilizan multiprocesamiento de forma predeterminada. El resultado se almacena en caché en disco; volver a ejecutar la misma .map() sobre los mismos datos devuelve la caché de inmediato.

# Filtrar filas
short = train.filter(lambda x: len(x['text']) < 500)

# Mapa por lotes —mucho más rápido para la tokenización
def tokenize(batch):
    return tokenizer(batch['text'], truncation=True, padding='max_length')

tokenized = train.map(tokenize, batched=True, batch_size=256, num_proc=4)

# Operaciones sobre columnas
tokenized = tokenized.remove_columns(['text'])
ds = ds.rename_column('label', 'labels')

# Mezclar y seleccionar
ds = ds.shuffle(seed=42).select(range(10000))

Conversión a otros formatos

Publicación de su propio conjunto de datos en el Hub

Tras ejecutar huggingface-cli login, puedes subir cualquierDataset o DatasetDict objeto directamente:

from datasets import Dataset, DatasetDict
import pandas as pd

df = pd.read_csv('my_data.csv')
ds = Dataset.from_pandas(df)

ds.push_to_hub('tu-usuario/mi-conjunto-de-datos', private=False)

Para subir las particiones de entrenamiento y prueba juntas:

split = ds.train_test_split(test_size=0.1)
DatasetDict({'train': split['train'], 'test': split['test']}).push_to_hub('tu-usuario/mi-conjunto-de-datos')

El Hub almacena los conjuntos de datos como archivos Parquet fragmentados y genera automáticamente una vista previa del conjunto de datos. Añade una README.md (Tarjeta de conjunto de datos) con metadatos YAML al inicio para que tu conjunto de datos sea filtrable por tarea, idioma y licencia en la interfaz de búsqueda del Hub.

Notas sobre la plataforma

Rutas de caché

Windows

Windows utiliza el método de iniciospawn para la multiprocesamiento, lo cual requiere que el punto de entrada de tu script esté dentro de una estructura if __name__ == '__main__': protección. Sin esta protección,.map(num_proc=4) se bloqueará indefinidamente o generará un error RuntimeError. Si ejecutas el código en un cuaderno Jupyter, usa bien num_proc=1 o instala el paquetemultiprocess junto con datasets, que la biblioteca prefiere frente al módulo estándar multiprocessing .

Espacio en disco

Los conjuntos de datos grandes (por ejemplo, Common Crawl, RedPajama, LAION) consumen cientos de gigabytes cuando se almacenan completamente en caché. Usa streaming=True para evitar descargas innecesarias. Para ver qué contiene tu caché, ejecuta python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" o explora directamente el directorio de caché. Los conjuntos de datos en caché se almacenan como archivos Arrow organizados por nombre y hash del conjunto de datos; elimina manualmente las subcarpetas correspondientes para recuperar espacio en disco.

Uso de conjuntos de datos para ajuste fino y evaluación

La canalización estándar para ajuste fino es: cargar el conjunto de datos → tokenizar con.map(batched=True) → establecer el formato en 'torch' → pasarlo a un objetoTrainer o a un bucle de entrenamiento personalizado. La clase transformers de Hugging Face acepta directamente un objeto Trainer como argumento para sus parámetros Dataset train_dataset y y eval_dataset .

Al evaluar modelos frente a conjuntos de datos de referencia, el Clasificación de modelos de lenguaje grande (LLM) proporciona puntuaciones en conjuntos de evaluación comunes, lo que ofrece un contexto útil al decidir qué conjunto de datos elegir para su propio benchmark. Si está valorando si ajustar finamente y alojar localmente frente a llamar a una API, el calculadora de punto de equilibrio entre alojamiento local y uso de API puede modelar el punto de cruce de costos según el volumen de solicitudes. Para conocer el costo bruto por token de la API entre distintos proveedores, utilice el Calculadora de costos de API. Y si planea ejecutar un modelo ajustado finamente localmente, la VRAM es la restricción física más crítica: el Calculadora de VRAM estima los requisitos de memoria de la GPU a partir del tamaño del modelo y la precisión de la cuantización.

Preguntas frecuentes

¿Cuál es la diferencia entre un Dataset y un DatasetDict?

A Dataset es una división única —una sola tabla con filas y columnas—. Un DatasetDict es un contenedor tipo diccionario que contiene múltiples divisiones y es el tipo de retorno predeterminado de load_dataset() cuando se omite el argumento split . Acceda a divisiones individuales mediante su clave: ds['train'], ds['test'], etc. Si pasasplit='train', obtendrá directamente un Dataset sin envoltura.

¿Cómo cargo un conjunto de datos privado desde el Hub?

Autentíquese primero con huggingface-cli login, o establezca la variable de entorno HF_TOKEN con su token de acceso. Luego, invoque load_dataset('org/private-dataset', token=True). El bloque La bandera se utiliza en entornos CI/CD: defínala como un secreto y omita el paso interactivo de inicio de sesión. HF_TOKEN ¿Por qué load_dataset() tarda tanto en la primera llamada?

La primera llamada descarga los archivos de datos sin procesar, los convierte al formato Apache Arrow y escribe la caché en disco. En conjuntos de datos grandes, esto puede tardar varios minutos o más. Las llamadas posteriores en la misma máquina devuelven los archivos Arrow en caché casi al instante. Si dispone de una conexión lenta o tiene espacio en disco limitado, pase

para procesar los datos sobre la marcha sin almacenarlos localmente en caché. streaming=True ¿Puedo usar conjuntos de datos de Hugging Face sin conexión a Internet?

Sí. Una vez que un conjunto de datos está en caché, establezca la variable de entorno

HF_DATASETS_OFFLINE=1 para que la biblioteca lea exclusivamente desde la caché local sin realizar ninguna solicitud de red. Esto resulta útil en servidores aislados (air-gapped), ejecuciones reproducibles sin conexión o clústeres HPC donde los nodos de trabajo carecen de acceso a Internet pero comparten un sistema de archivos en red con el directorio de caché. yload_dataset() ¿Qué formato de archivo utiliza internamente el Hub?

Los conjuntos de datos almacenados en el Hub se sirven como archivos Apache Parquet divididos en fragmentos (shards). La biblioteca

descarga estos fragmentos y los convierte a archivos Apache Arrow ( datasets .arrow) para su almacenamiento en caché local. Puede omitir por completo la biblioteca y acceder directamente a los fragmentos Parquet mediante el navegador de archivos del Hub o usandohuggingface_hub.hf_hub_download() ¿Qué tamaño puede tener un conjunto de datos de Hugging Face?.

No existe un límite de tamaño impuesto, y en el Hub existen conjuntos de datos de varios terabytes (por ejemplo, los pares imagen-texto de LAION-5B o instantáneas extensas de Common Crawl). Para conjuntos de datos superiores a varios gigabytes, el Hub almacena los datos como múltiples fragmentos Parquet en lugar de un único archivo. Utilice

en la biblioteca streaming=True para trabajar con estos conjuntos de datos sin descargarlos íntegramente, o descargue fragmentos específicos mediante el argumento datasets data_files . argumento.