Crear un conjunto de datos de video

Esta guía le mostrará cómo crear un conjunto de datos de video con VideoFolder y algunos metadatos. Esta es una solución sin código para crear rápidamente un conjunto de datos de video con varios miles de videos.

Puedes controlar el acceso a tu conjunto de datos requiriendo que los usuarios compartan primero su información de contacto. Consulta la guía de Conjuntos de datos con acceso restringido para obtener más información sobre cómo habilitar esta función en el Hub.

VideoFolder

El VideoFolder es un constructor de conjuntos de datos diseñado para cargar rápidamente un conjunto de datos de video con varios miles de videos sin que tengas que escribir ningún código.

💡 Echa un vistazo a la Jerarquía del patrón Split para aprender más sobre cómo VideoFolder crea divisiones de datos basadas en la estructura de tu repositorio de datos.

VideoFolder infiere automáticamente las etiquetas de clase de tu conjunto de datos en función del nombre del directorio. Guarda tu conjunto de datos en una estructura de directorios como la siguiente:

folder/train/dog/golden_retriever.mp4
folder/train/dog/german_shepherd.mp4
folder/train/dog/chihuahua.mp4

folder/train/cat/maine_coon.mp4
folder/train/cat/bengal.mp4
folder/train/cat/birman.mp4

Si el conjunto de datos sigue la estructura VideoFolder, puede cargarlo directamente con load_dataset():

>>> from datasets import load_dataset

>>> dataset = load_dataset("path/to/folder")

Esto es equivalente a pasar videofolder manualmente en load_dataset() y el directorio en data_dir:

>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder")

También puede usar videofolder para cargar conjuntos de datos que implican múltiples divisiones. Para ello, el directorio de su conjunto de datos debe tener la siguiente estructura:

folder/train/dog/golden_retriever.mp4
folder/train/cat/maine_coon.mp4
folder/test/dog/german_shepherd.mp4
folder/test/cat/bengal.mp4

Si todos los archivos de video están contenidos en un solo directorio o si no están en el mismo nivel de la estructura de directorios, la columna label no se agregará automáticamente. Si la necesitas, establece drop_labels=False explícitamente.

Si hay información adicional que desees incluir sobre tu conjunto de datos, como descripciones de texto o cajas delimitadoras, añádela como un archivo metadata.csv en tu carpeta. Esto te permite crear rápidamente conjuntos de datos para diferentes tareas de visión por computadora, como la descripción de texto o la detección de objetos. También puedes usar un archivo JSONL metadata.jsonl o un archivo Parquet metadata.parquet.

folder/train/metadata.csv
folder/train/0001.mp4
folder/train/0002.mp4
folder/train/0003.mp4

El archivo metadata.csv debe tener un campo file_name o *_file_name que vincule los archivos de video con sus metadatos:

file_name,additional_feature
0001.mp4,This is a first value of a text feature you added to your videos
0002.mp4,This is a second value of a text feature you added to your videos
0003.mp4,This is a third value of a text feature you added to your videos

o usando metadata.jsonl:

{"file_name": "0001.mp4", "additional_feature": "This is a first value of a text feature you added to your videos"}
{"file_name": "0002.mp4", "additional_feature": "This is a second value of a text feature you added to your videos"}
{"file_name": "0003.mp4", "additional_feature": "This is a third value of a text feature you added to your videos"}

Aquí, file_name debe ser el nombre del archivo de video situado junto al archivo de metadatos. De forma más general, debe ser la ruta relativa desde el directorio que contiene los metadatos hasta el archivo de video.

Es posible apuntar a más de un video en cada fila de su conjunto de datos, por ejemplo, si tanto su entrada como su salida son videos:

{"input_file_name": "0001.mp4", "output_file_name": "0001_output.mp4"}
{"input_file_name": "0002.mp4", "output_file_name": "0002_output.mp4"}
{"input_file_name": "0003.mp4", "output_file_name": "0003_output.mp4"}

También puede definir listas de videos. En ese caso, debe nombrar el campo file_names o *_file_names. Aquí hay un ejemplo:

{"videos_file_names": ["0001_left.mp4", "0001_right.mp4"], "label": "moving_up"}
{"videos_file_names": ["0002_left.mp4", "0002_right.mp4"], "label": "moving_down"}
{"videos_file_names": ["0003_left.mp4", "0003_right.mp4"], "label": "moving_right"}

Descripción de videos

Los conjuntos de datos de descripción de videos tienen texto que describe un video. Un ejemplo de metadata.csv puede verse así:

file_name,text
0001.mp4,This is a golden retriever playing with a ball
0002.mp4,A german shepherd
0003.mp4,One chihuahua

Cargue el conjunto de datos con VideoFolder y creará una columna text para las descripciones de los videos:

>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"This is a golden retriever playing with a ball"

Subir el conjunto de datos al Hub

Una vez que hayas creado un conjunto de datos, puedes compartirlo en la plataforma, por ejemplo, usando huggingface_hub. Asegúrate de tener instalada la biblioteca huggingface_hub y de haber iniciado sesión en tu cuenta de Hugging Face (consulta el tutorial de carga con Python para más detalles).

Sube tu conjunto de datos con huggingface_hub.HfApi.upload_folder:

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/path/to/local/dataset",
    repo_id="username/my-cool-dataset",
    repo_type="dataset",
)

WebDataset

El formato WebDataset se basa en archivos TAR y es adecuado para grandes conjuntos de datos de video. De hecho, puede agrupar sus videos en archivos TAR (por ejemplo, 1 GB de videos por archivo TAR) y tener miles de archivos TAR:

folder/train/00000.tar
folder/train/00001.tar
folder/train/00002.tar
...

En los archivos, cada ejemplo está compuesto por archivos que comparten el mismo prefijo:

e39871fd9fd74f55.mp4
e39871fd9fd74f55.json
f18b91585c4d3f3e.mp4
f18b91585c4d3f3e.json
ede6e66b2fb59aab.mp4
ede6e66b2fb59aab.json
ed600d57fcee4f94.mp4
ed600d57fcee4f94.json
...

Puedes colocar las etiquetas/leyendas/características de tus videos usando, por ejemplo, archivos JSON o de texto.

Para más detalles sobre el formato WebDataset y la biblioteca de python, consulte la documentación de WebDataset.

Carga tu WebDataset y creará una columna por cada sufijo de archivo (aquí, “mp4” y “json”):

>>> from datasets import load_dataset

>>> dataset = load_dataset("webdataset", data_dir="/path/to/folder", split="train")
>>> dataset[0]["json"]
{"bbox": [[302.0, 109.0, 73.0, 52.0]], "categories": [0]}

Lance

Lance es un formato de tabla de lakehouse multimodal abierto. Las tablas Lance pueden almacenar de forma nativa no solo texto y valores escalares, sino también objetos binarios grandes (blobs) como imágenes, audio y video junto a sus datos tabulares.

Lance ofrece una API de blobs que facilita el almacenamiento y la recuperación de blobs grandes en conjuntos de datos de Lance. El siguiente ejemplo muestra cómo explorar de forma eficiente los metadatos sin cargar los blobs de video más pesados y, a continuación, obtener los blobs de video relevantes bajo demanda.

A continuación se muestra una vista representativa de cómo podría ser una tabla Lance que almacena videos (la columna video_blob utiliza la codificación de blobs de Lance):

+------------------------------------------+-----------------+-----+------------------------------------------+
| caption                                  | aesthetic_score | ... | video_blob                               |
+------------------------------------------+-----------------+-----+------------------------------------------+
| "a breathtaking view of a mounta..."     | 5.2401          | ... | {position: 0, size: 4873879}             |
| "a captivating view of the sun, b..."    | 5.2401          | ... | {position: 4873920, size: 3370571}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

Escribir un conjunto de datos Lance desde archivos de video sin procesar

A partir de archivos de video en bruto en el disco y los metadatos asociados (por ejemplo, descripciones y puntuaciones), puede escribir un conjunto de datos Lance autónomo en un directorio local *.lance (un conjunto de datos Lance es un directorio en el disco, y es común nombrarlo con el sufijo .lance):

import lance
import pyarrow as pa

import urllib.request

schema = pa.schema(
    [
        pa.field("caption", pa.utf8()),
        pa.field("aesthetic_score", pa.float64()),
        pa.field(
            "video_blob",
            pa.large_binary(),
            metadata={"lance-encoding:blob": "true"},
        ),
    ]
)

# Provide video files alongside metadata
rows = [
    {
        "video_path": "/path/to/videos/0001.mp4",
        "caption": "a breathtaking view of a mountainous landscape ...",
        "aesthetic_score": 5.240138053894043,
    },
    {
        "video_path": "0002.mp4",
        "caption": "a captivating view of the sun, bathed in hues ...",
        "aesthetic_score": 5.240137100219727,
    },
]

video_bytes = []
for r in rows:
    with open(r["video_path"], "rb") as f:
        video_bytes.append(f.read())

table = pa.table(
    {
        "caption": [r["caption"] for r in rows],
        "aesthetic_score": [r["aesthetic_score"] for r in rows],
        "video_blob": video_bytes,
    },
    schema=schema,
)

ds = lance.write_dataset(
    table,
    "./videos.lance",
    schema=schema,
    mode="create",
)

Esto guarda tus metadatos y los bytes del video juntos dentro de videos.lance/, por lo que puedes mover o copiar un solo directorio sin tener que mantener sincronizados archivos *.mp4 separados.

A continuación se muestra una vista representativa de cómo podría ser una tabla de Lance que almacena videos (la columna video_blob contiene datos que se almacenan de forma nativa como blobs dentro del conjunto de datos de Lance):

+------------------------------------------+-----------------+-----+------------------------------------------+
| caption                                  | aesthetic_score | ... | video_blob                               |
+------------------------------------------+-----------------+-----+------------------------------------------+
| "a breathtaking view of a mounta..."     | 5.2401          | ... | {position: 0, size: 4873879}             |
| "a captivating view of the sun, b..."    | 5.2401          | ... | {position: 4873920, size: 3370571}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

Puedes subir el directorio videos.lance/ resultante al Hub (por ejemplo, con huggingface_hub.HfApi.upload_folder) y compartirlo como un repositorio de datos, manteniendo los metadatos y los videos juntos como un único artefacto.

Los conjuntos de datos de Lance escalan a tamaños muy grandes (terabytes y más) ya que los datos se almacenan en un formato columnar en el disco. Consulte la guía de la API de blobs para obtener la información más reciente sobre las mejores prácticas para almacenar y recuperar blobs grandes en Lance.

Al escribir conjuntos de datos grandes, lo ideal es limitar el tamaño de cada archivo *.lance individual a unos pocos gigabytes como máximo. Basta con recopilar los datos mediante un iterador y especificar el parámetro max_bytes_per_file al escribir el conjunto de datos:

MAX_BYTES_PER_FILE = 5 * 1024 * 1024 * 1024  # ~5 GB per file

# Write as Lance dataset with file size limits for each *.lance file
ds = lance.write_dataset(
    table,
    "./videos.lance",
    schema=schema,
    mode="create",
    max_bytes_per_file=MAX_BYTES_PER_FILE,
)

Para más detalles sobre el trabajo con conjuntos de datos Lance, consulte la documentación de Lance.