Datasets documentation
비디오 데이터셋 만들기
비디오 데이터셋 만들기
이 가이드에서는 VideoFolder와 일부 메타데이터를 사용하여 비디오 데이터셋을 만드는 방법을 보여줍니다. 수천 개의 비디오로 구성된 비디오 데이터셋을 빠르게 생성하기 위한 무코드(no-code) 솔루션입니다.
사용자가 먼저 연락처 정보를 공유하도록 요구하여 데이터셋에 대한 액세스를 제어할 수 있습니다. Hub에서 이 기능을 활성화하는 방법에 대한 자세한 내용은 Gated datasets 가이드를 참고하세요.
VideoFolder
VideoFolder는 수천 개의 비디오로 구성된 비디오 데이터셋을 코드를 작성하지 않고도 빠르게 로드하도록 설계된 데이터셋 빌더입니다.
💡
VideoFolder가 데이터셋 저장소 구조를 기반으로 데이터셋 분할을 생성하는 방법에 대해 자세히 알아보려면 Split pattern hierarchy를 확인해 보세요.
VideoFolder는 디렉터리 이름을 기반으로 데이터셋의 클래스 라벨을 자동으로 추론합니다. 데이터셋을 다음과 같은 디렉터리 구조로 저장하세요:
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데이터셋이 VideoFolder 구조를 따르는 경우, load_dataset()를 사용하여 직접 로드할 수 있습니다:
>>> from datasets import load_dataset
>>> dataset = load_dataset("path/to/folder")videofolder를 load_dataset()에 수동으로 전달하고 data_dir에 디렉터리를 지정하는 것과 동일합니다:
>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder")videofolder를 사용하여 여러 스플릿을 포함하는 데이터셋을 로드할 수도 있습니다. 이를 위해 데이터셋 디렉토리는 다음 구조를 가져야 합니다:
folder/train/dog/golden_retriever.mp4
folder/train/cat/maine_coon.mp4
folder/test/dog/german_shepherd.mp4
folder/test/cat/bengal.mp4모든 비디오 파일이 단일 디렉터리에 포함되어 있거나 동일한 디렉터리 구조 레벨에 있지 않은 경우,
label열이 자동으로 추가되지 않습니다. 이 열이 필요한 경우drop_labels=False를 명시적으로 설정하세요.
데이터셋에 텍스트 캡션이나 바운딩 박스처럼 포함하고 싶은 추가 정보가 있다면, 폴더에 metadata.csv 파일로 추가하세요. 이를 통해 텍스트 캡션이나 객체 탐지와 같은 다양한 컴퓨터 비전 작업용 데이터셋을 빠르게 만들 수 있습니다. JSONL 파일 metadata.jsonl 또는 Parquet 파일 metadata.parquet도 사용할 수 있습니다.
folder/train/metadata.csv
folder/train/0001.mp4
folder/train/0002.mp4
folder/train/0003.mp4metadata.csv 파일에는 비디오 파일과 메타데이터를 연결하는 file_name 또는 *_file_name 필드가 있어야 합니다:
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또는 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"}여기서 file_name은 메타데이터 파일 옆에 있는 비디오 파일의 이름이어야 합니다. 더 일반적으로, 메타데이터가 포함된 디렉터리에서 비디오 파일까지의 상대 경로여야 합니다.
데이터셋의 각 행에 두 개 이상의 비디오를 지정할 수 있습니다. 예를 들어 입력과 출력 모두 비디오인 경우입니다:
{"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"}비디오 목록도 정의할 수 있습니다. 이 경우 필드 이름을 file_names 또는 *_file_names으로 지정해야 합니다. 예시는 다음과 같습니다:
{"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"}비디오 캡셔닝
Video captioning 데이터셋에는 비디오를 설명하는 텍스트가 포함되어 있습니다. metadata.csv의 예시는 다음과 같습니다:
file_name,text
0001.mp4,This is a golden retriever playing with a ball
0002.mp4,A german shepherd
0003.mp4,One chihuahuaVideoFolder로 데이터셋을 로드하면, 비디오 캡션을 위한 text 열이 생성됩니다:
>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"This is a golden retriever playing with a ball"Hub에 데이터셋 업로드
데이터셋을 생성한 후에는 huggingface_hub 등을 사용하여 공유할 수 있습니다. huggingface_hub 라이브러리가 설치되어 있고 Hugging Face 계정에 로그인되어 있는지 확인하세요(자세한 내용은 Upload with Python tutorial를 참고하세요).
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
WebDataset 형식은 TAR 아카이브를 기반으로 하며 대규모 비디오 데이터셋에 적합합니다. 실제로 비디오를 TAR 아카이브에 묶을 수 있습니다(예: TAR 아카이브당 1GB의 비디오). 그리고 수천 개의 TAR 아카이브를 가질 수 있습니다:
folder/train/00000.tar
folder/train/00001.tar
folder/train/00002.tar
...아카이브에서 각 예제는 동일한 접두사를 공유하는 파일들로 구성됩니다:
e39871fd9fd74f55.mp4
e39871fd9fd74f55.json
f18b91585c4d3f3e.mp4
f18b91585c4d3f3e.json
ede6e66b2fb59aab.mp4
ede6e66b2fb59aab.json
ed600d57fcee4f94.mp4
ed600d57fcee4f94.json
...JSON 또는 텍스트 파일 등을 사용하여 비디오의 라벨/캡션/기능을 지정할 수 있습니다.
WebDataset 형식과 python 라이브러리에 대한 자세한 내용은 WebDataset 문서를 참고하세요.
WebDataset를 로드하면 파일 확장자(여기서는 “mp4”와 “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는 오픈 멀티모달 레이크하우스 테이블 형식입니다. Lance 테이블은 텍스트와 스칼라 값뿐만 아니라 이미지, 오디오, 비디오와 같은 대형 바이너리 객체(blobs)도 테이블 데이터와 함께 네이티브로 저장할 수 있습니다.
Lance는 Lance 데이터셋에서 대용량 blob을 저장하고 검색하는 데 편리한 blob API를 제공합니다. 다음 예제는 무거운 video blob을 로드하지 않고 메타데이터를 효율적으로 탐색한 후, 필요한 video blob을 온디맨드로 가져오는 방법을 보여줍니다.
비디오를 저장하는 Lance 테이블의 대표적인 예시는 다음과 같습니다(video_blob 컬럼은 Lance의 blob 인코딩을 사용합니다):
+------------------------------------------+-----------------+-----+------------------------------------------+
| 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} |
+------------------------------------------+-----------------+-----+------------------------------------------+Write a Lance dataset from raw video files
디스크에 있는 원본 비디오 파일과 관련 메타데이터(예: 캡션 및 점수)를 기반으로, 자체적으로 완결된 Lance 데이터셋을 로컬의 *.lance 디렉터리(Lance 데이터셋은 디스크상의 디렉터리이며, .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",
)videos.lance/ 안에 메타데이터와 비디오 바이트를 함께 저장하므로, 별도의 *.mp4 파일을 동기화할 필요 없이 단일 디렉터리만 이동/복사하면 됩니다.
Lance 테이블에 비디오를 저장할 때의 대표적인 예시를 살펴보겠습니다(video_blob 컬럼에는 Lance 데이터셋 내에서 네이티브로 blob으로 저장되는 데이터가 포함되어 있습니다):
+------------------------------------------+-----------------+-----+------------------------------------------+
| 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} |
+------------------------------------------+-----------------+-----+------------------------------------------+생성된 videos.lance/ 디렉터리를 Hub에 업로드(예: huggingface_hub.HfApi.upload_folder 사용)하고 데이터셋 저장소로 공유할 수 있습니다. 이렇게 하면 메타데이터와 비디오가 단일 아티팩트로 함께 유지됩니다.
Lance 데이터셋은 데이터가 디스크에 컬럼형 형식으로 저장되므로 테라바이트 이상으로 확장할 수 있습니다. Lance에서 대용량 blob을 저장하고 검색하는 데 대한 모범 사례의 최신 정보는 blob API 가이드를 참조하세요.
대용량 데이터셋을 작성할 때는 각 *.lance 파일의 크기를 기가바이트 몇 개로 제한하는 것이 일반적으로 가장 좋습니다.
반복자를 통해 데이터를 수집한 다음, 데이터셋을 작성할 때 max_bytes_per_file 매개변수를 지정하면 됩니다:
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,
)Lance 데이터셋을 다루는 방법에 대한 자세한 내용은 Lance 문서를 참고하세요.
Update on GitHub