Criar um conjunto de dados de vídeo

Este guia mostrará como criar um conjunto de dados de vídeo com VideoFolder e alguns metadados. Esta é uma solução sem código para criar rapidamente um conjunto de dados de vídeo com vários milhares de vídeos.

Você pode controlar o acesso ao seu conjunto de dados exigindo que os usuários compartilhem primeiro suas informações de contato. Consulte o guia Conjuntos de dados com controle de acesso para mais informações sobre como habilitar esse recurso no Hub.

VideoFolder

O VideoFolder é um construtor de dataset projetado para carregar rapidamente um conjunto de dados de vídeo com vários milhares de vídeos, sem exigir que você escreva qualquer código.

💡 Dê uma olhada na hierarquia de padrões de divisão para saber mais sobre como o VideoFolder cria as divisões do conjunto de dados com base na estrutura do repositório do seu conjunto de dados.

VideoFolder infere automaticamente os rótulos de classe do seu dataset com base no nome do diretório. Armazene seu dataset em uma estrutura de diretórios como:

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

Se o conjunto de dados seguir a estrutura VideoFolder, você pode carregá-lo diretamente com load_dataset():

>>> from datasets import load_dataset

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

Isso é equivalente a passar videofolder manualmente em load_dataset() e o diretório em data_dir:

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

Você também pode usar videofolder para carregar conjuntos de dados que envolvem múltiplos splits. Para isso, o diretório do seu conjunto de dados deve ter a seguinte estrutura:

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

Se todos os arquivos de vídeo estiverem em um único diretório ou se não estiverem no mesmo nível da estrutura de diretórios, a coluna label não será adicionada automaticamente. Se você precisar dela, defina drop_labels=False explicitamente.

Se houver informações adicionais que você deseja incluir sobre seu conjunto de dados, como legendas de texto ou caixas delimitadoras, adicione-as como um arquivo metadata.csv na sua pasta. Isso permite criar rapidamente conjuntos de dados para diferentes tarefas de visão computacional, como legendagem de texto ou detecção de objetos. Você também pode usar um arquivo JSONL metadata.jsonl ou um arquivo Parquet metadata.parquet.

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

O arquivo metadata.csv deve ter um campo file_name ou *_file_name que vincule os arquivos de vídeo aos seus metadados:

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

ou 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"}

Aqui, o file_name deve ser o nome do arquivo de vídeo ao lado do arquivo de metadados. Mais geralmente, deve ser o caminho relativo do diretório que contém os metadados até o arquivo de vídeo.

É possível apontar para mais de um vídeo em cada linha do seu conjunto de dados, por exemplo, se tanto a sua entrada quanto a sua saída forem vídeos:

{"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"}

Você também pode definir listas de vídeos. Nesse caso, é necessário nomear o campo file_names ou *_file_names. Aqui está um exemplo:

{"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"}

Legendação de vídeo

Os conjuntos de dados de legendas de vídeo possuem texto descrevendo um vídeo. Um exemplo de metadata.csv pode ser:

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

Carregue o conjunto de dados com VideoFolder e ele criará uma coluna text para as legendas dos vídeos:

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

Enviar o conjunto de dados para o Hub

Depois de criar um conjunto de dados, você pode compartilhá-lo usando, por exemplo, o huggingface_hub. Certifique-se de que a biblioteca huggingface_hub está instalada e de que você está conectado à sua conta do Hugging Face (veja o tutorial de upload com Python para mais detalhes).

Envie seu conjunto de dados com 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

O formato WebDataset é baseado em arquivos TAR e é adequado para grandes conjuntos de dados de vídeo. De fato, você pode agrupar seus vídeos em arquivos TAR (por exemplo, 1 GB de vídeos por arquivo TAR) e ter milhares de arquivos TAR:

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

Nos arquivos, cada exemplo é composto por arquivos que compartilham o mesmo prefixo:

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

Você pode usar arquivos JSON ou de texto, por exemplo, para armazenar os rótulos/legendas/recursos dos seus vídeos.

Para mais detalhes sobre o formato WebDataset e a biblioteca python, consulte a documentação do WebDataset.

Carregue seu WebDataset e ele criará uma coluna para cada sufixo de arquivo (aqui, “mp4” e “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 é um formato de tabela de lakehouse multimodal aberto. As tabelas Lance podem armazenar nativamente não apenas texto e valores escalares, mas também objetos binários grandes (blobs), como imagens, áudio e vídeo, junto com seus dados tabulares.

O Lance oferece uma API de blobs que facilita o armazenamento e a recuperação de blobs grandes em datasets Lance. O exemplo a seguir mostra como navegar eficientemente pelos metadados sem carregar os blobs de vídeo mais pesados e, em seguida, buscar os blobs de vídeo relevantes sob demanda.

Aqui está uma visão representativa de como seria uma tabela Lance que armazena vídeos (a coluna video_blob usa a codificação de blob do 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}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

Escreva um dataset Lance a partir de arquivos de vídeo brutos

A partir de arquivos de vídeo brutos em disco e dos metadados associados (por exemplo, legendas e pontuações), você pode gravar um dataset Lance autossuficiente em um diretório local *.lance (um dataset Lance é um diretório em disco, e é comum nomeá-lo com o sufixo .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",
)

Isso armazena seus metadados e bytes de vídeo juntos dentro de videos.lance/, permitindo mover/copiar um único diretório sem precisar manter arquivos *.mp4 separados sincronizados.

Aqui está uma visão representativa de como seria uma tabela Lance que armazena vídeos (a coluna video_blob contém dados que são armazenados nativamente como blobs dentro do dataset 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}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

Você pode enviar o diretório videos.lance/ resultante para o Hub (por exemplo, com huggingface_hub.HfApi.upload_folder) e compartilhá-lo como um repositório de dataset, mantendo os metadados e os vídeos juntos como um único artefato.

Os datasets Lance escalam para tamanhos muito grandes (terabytes e além), pois os dados são armazenados em um formato colunar no disco. Consulte o guia da API de blobs para as informações mais recentes sobre as melhores práticas para armazenar e recuperar blobs grandes no Lance.

Ao gravar grandes conjuntos de dados, é geralmente melhor limitar o tamanho de cada arquivo individual *.lance a alguns gigabytes no máximo. Basta coletar os dados por meio de um iterador e especificar o parâmetro max_bytes_per_file ao gravar o conjunto de dados:

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 mais detalhes sobre o trabalho com conjuntos de dados Lance, consulte a documentação do Lance.