Lance

Lance는 AI를 위한 오픈 멀티모달 레이크하우스 테이블 형식입니다. Hugging Face 경로(hf://)를 사용하여 Hub의 Lance 데이터셋에 액세스할 수 있습니다. 이를 통해 Hugging Face Hub의 대규모 데이터셋을 로컬로 전체를 복사하지 않고도 스캔 및 검색할 수 있습니다.

시작하기

시작하려면 pylance와 pyarrow를 pip로 설치하세요:

pip install pylance pyarrow

왜 Lance인가요?

• ML/AI 워크로드에 최적화: Lance는 스캔 성능을 저해하지 않으면서도 빠른 랜덤 액세스를 지원하는 현대적인 컬럼형 포맷으로, 검색, 분석, 학습, 피처 엔지니어링 등 다양한 사용 사례에 유용합니다.
• 멀티모달 자산은 임베딩과 전통적인 스칼라 데이터와 함께 Lance에서 바이트, 즉 바이너리 객체("파일로 저장된 blob")로 저장됩니다. 이를 통해 Hub를 통해 대규모 데이터셋을 관리하고 공유하며 배포하는 것이 더 쉬워집니다.
• 인덱싱은 1급 시민(포맷 자체에 네이티브)입니다: Lance에는 데이터셋과 함께 Hub에 바로 배치되는 빠르고, 디스크 기반이며, 확장 가능한 벡터 및 FTS 인덱스가 포함되어 있어, 사용자가 다시 계산할 필요 없이 데이터뿐만 아니라 임베딩과 인덱스도 공유할 수 있습니다.
• 유연한 스키마와 데이터 진화를 통해 새로운 기능/열(모더레이션 태그, 임베딩 등)을 전체 테이블을 다시 작성하지 않고도 점진적으로 추가할 수 있습니다.

모든 데이터를 한곳에 저장하세요

Lance에서는 멀티모달 데이터 자산(이미지, 오디오, 비디오)이 스칼라 메타데이터와 임베딩과 함께 원시 바이트로 저장됩니다. 이를 통해 여러 저장 시스템을 통합할 필요 없이 한 곳에서 데이터셋을 스캔하고 필터링할 수 있습니다.

datasets로 Hub에서 스트리밍

load_dataset(..., streaming=True)를 사용하여 데이터를 로컬로 다운로드하지 않고 스캔하고 반복합니다.

from datasets import load_dataset

# Return as a Hugging Face dataset
ds = load_dataset(
    "lance-format/laion-1m",
    split="train",
    streaming=True
)
# Take first three rows
for row in ds.take(3):
    print(row["caption"])

Streaming은 보유 데이터를 파악하기 위해 메타데이터를 샘플링하는 데 유용합니다. 벡터 검색이나 대용량 바이너리 블롭을 다루려면 아래에서 설명하는 Lance dataset API를 사용할 수 있습니다.

Streaming은 단순한 스칼라 메타데이터를 샘플링하는 데는 빠르지만, 임베딩이나 대규모 멀티모달 에셋을 처리하는 데는 상대적으로 느립니다. 대규모 데이터셋을 다루려면 메타데이터를 스캔하여 필요한 부분 집합을 식별한 후, 해당 부분만 로컬로 다운로드하여 Hub의 레이트 리밋 문제를 피하는 것이 좋습니다: hf download lance-format/laion-1m --repo-type dataset --local-dir ./laion

lance.dataset로 Hub에서 스트리밍

Hugging Face Hub에 저장된 Lance 데이터셋을 hf:// 경로 지정자를 사용하여 스캔할 수도 있습니다. 이를 통해 로컬로 다운로드하지 않고 원격 데이터셋을 스캔할 수 있습니다. Lance dataset API를 사용하면 필요한 데이터만 가져오도록 제한, 필터 및 프로젝션을 설정하는 것이 매우 간단합니다.

import lance

# Return as a Lance dataset
ds = lance.dataset("hf://datasets/lance-format/laion-1m/data/train.lance")

scanner = ds.scanner(
    columns=["caption", "url", "similarity"],
    limit=5
)

rows = scanner.to_table().to_pylist()
for row in rows:
    print(row)

바이너리 자산 작업

아래 예시에서는 Lance 데이터셋에서 image 컬럼의 이미지가 원본 JPEG 바이트로 가져와져 하위 단계에서 사용되는 방법을 보여줍니다. ds.take를 사용하여 바이트를 가져와 디스크에 저장하면 다른 곳에서 사용할 수 있습니다.

import lance
from pathlib import Path

ds = lance.dataset("hf://datasets/lance-format/laion-1m/data/train.lance")

dir_name = "laion_samples"
Path(dir_name).mkdir(exist_ok=True)

rows = ds.take([0, 1], columns=["image", "caption"]).to_pylist()
for idx, row in enumerate(rows):
    with open(f"{dir_name}/{idx}.jpg", "wb") as f:
        f.write(row["image"])
        print(f"Wrote image with caption: {row['caption']}")

Write a subset to a new Lance dataset

대용량 데이터셋을 다루고 계신가요? Hub에서 행의 하위 집합을 선택하기 위해 필터링된 스캔을 실행하고 이를 로컬 Lance 데이터셋으로 구현하는 것은 간단합니다.

import lance

ds = lance.dataset("hf://datasets/lance-format/laion-1m/data/train.lance")
scanner = ds.scanner(
    columns=["image", "caption", "width", "height"],
    filter="width >= 200 AND height >= 100",
    limit=10,
)
subset = scanner.to_table()

lance.write_dataset(subset, "./laion_subset")

인덱스 생성

데이터셋에 이미 인덱스가 연결되어 있지 않은 경우, 로컬로 다운로드한 후 인덱스를 생성할 수 있습니다.

# ds is a local Lance dataset
ds.create_index(
    "img_emb",
    index_type="IVF_PQ",
    num_partitions=256,
    num_sub_vectors=96,
    replace=True,
)

벡터 인덱스 생성에 대한 더 자세한 예제는 Lance 문서를 참고하세요. 벡터 인덱스가 생성되면 임베딩을 통해 데이터에서 유사도 검색을 실행할 수 있습니다.

벡터 검색

Lance에서 인덱스는 일급 시민(first-class citizen)이므로, 데이터뿐만 아니라 임베딩과 인덱스도 함께 저장하고 Hub에서 직접 쿼리할 수 있습니다. describe_indices() 메서드를 사용하여 데이터셋의 인덱스 정보를 나열할 수 있습니다. 데이터셋에 인덱스가 없는 경우, lance.write_dataset()를 사용하여 데이터셋의 로컬 버전을 작성하고 LanceDataset.create_index를 사용하여 필요한 인덱스를 생성할 수 있습니다.

아래 예시는 img_emb 필드에 벡터 인덱스가 이미 있는 데이터셋을 보여줍니다:

import lance

ds = lance.dataset("hf://datasets/lance-format/laion-1m/data/train.lance")

print(ds.list_indices())

# Returns
# [
#   IndexDescription(
#       name=img_emb_idx,
#       type_url=/lance.table.VectorIndexDetails,
#       num_rows_indexed=1209588,
#       fields=[15],
#       field_names=["img_emb"],
#       num_segments=1
#.   )
# ]

… 원격 데이터셋을 다운로드하지 않고도 벡터 검색 쿼리를 직접 실행할 수 있습니다(원하는 경우 데이터셋을 로컬로 다운로드하여 새 인덱스를 생성할 수도 있습니다). 아래 예제는 이미지 임베딩을 쿼리 벡터로 사용하여 벡터 인덱스에서 가장 가까운 이웃 검색을 실행하는 방법을 보여줍니다.

import lance
import pyarrow as pa

ds = lance.dataset("hf://datasets/lance-format/laion-1m/data/train.lance")

emb_field = ds.schema.field("img_emb")
ref = ds.take([0], columns=["img_emb"]).to_pylist()[0]["img_emb"]
query = pa.array([ref], type=emb_field.type)

neighbors = ds.scanner(
    nearest={
        "column": emb_field.name,
        "q": query[0],
        "k": 6,
        "nprobes": 16,
        "refine_factor": 30,
    },
    columns=["caption", "url", "similarity"],
).to_table().to_pylist()

큰 k 또는 nprobes 값을 설정하거나, 대량의 쿼리를 한 번에 보내면 Hub의 속도 제한에 도달할 수 있습니다. 대량 사용의 경우, 데이터셋(또는 그 일부)을 로컬로 다운로드한 후 Lance를 로컬 경로로 지정하여 속도 제한을 피하세요.

데이터셋의 진화

Lance의 가장 강력한 기능 중 하나는 유연하고 비용이 들지 않는 데이터 진화입니다. 이는 원본 테이블을 다시 작성하지 않고도 파생된 컬럼을 손쉽게 추가할 수 있음을 의미합니다. 대용량 블롭이 많이 포함된 매우 큰 테이블의 경우, I/O 절감 효과가 상당히 클 수 있습니다. ML/AI 엔지니어링 작업을 위해 데이터를 실험하고, 새로운 특징, 임베딩, 또는 파생된 메타데이터를 자주 추가하는 경우 이 기능이 매우 유용합니다.

아래 예시는 기존 점수 컬럼을 기반으로 이미지를 NSFW로 표시하는 파생 moderation_label 컬럼을 추가하는 방법을 보여줍니다. 이 변경 사항을 적용할 때, 새 컬럼을 백필하면 원본 이미지 블롭이나 다른 컬럼의 데이터에 영향을 주지 않고 새 컬럼 데이터만 기록됩니다. 데이터를 백필하지 않고 새 컬럼 스키마만 추가하는 것도 선택할 수 있습니다.

import lance
import pyarrow as pa

# Assumes you ran the export to Lance example above to store a local subset of the data
local_ds = lance.dataset("./laion_subset")

# schema only (data to be added later)
local_ds.add_columns(pa.field("moderation_label", pa.string()))

# with data backfill
local_ds.add_columns(
    {
        "moderation_label": "case WHEN \"NSFW\" > 0.5 THEN 'review' ELSE 'ok' END"
    }
)

Lance 데이터셋에서 컬럼을 수정하고 삭제하는 방법을 배우려면 데이터 진화에 대한 Lance 문서를 참조하세요.

비디오 blob 작업

Lance 테이블은 대용량 인라인 비디오 블롭도 지원합니다. 이 논문의 OpenVid-1M 데이터셋에는 고품질이고 표현력이 풍부한 비디오와 그에 대한 캡션이 포함되어 있습니다. 비디오 데이터는 Hub의 다음 Lance 데이터셋의 video_blob 컬럼에 저장되어 있습니다.

import lance

lance_ds = lance.dataset("hf://datasets/lance-format/Openvid-1M/data/train.lance")
blob_file = lance_ds.take_blobs("video_blob", ids=[0])[0]
video_bytes = blob_file.read()

다른 데이터 포맷과 달리, 대규모 멀티모달 바이너리 객체(blob)는 Lance에서 일급 시민(first-class citizen)입니다. blob API는 Lance 데이터셋에 대규모 blob을 저장하고 검색하기 위한 고수준 API를 제공합니다. 다음 예제는 무거운 비디오 blob을 로드하지 않고 메타데이터를 효율적으로 탐색한 후, 필요한 비디오 blob을 온디맨드로 가져오는 방법을 보여줍니다.

import lance

ds = lance.dataset("hf://datasets/lance-format/Openvid-1M/data/train.lance")

# 1. Browse metadata without loading video blobs.
metadata = ds.scanner(
    columns=["caption", "aesthetic_score"],
    filter="aesthetic_score >= 4.5",
    limit=2,
).to_table().to_pylist()

# 2. Fetch a single video blob by row index.
selected_index = 0
blob_file = ds.take_blobs("video_blob", ids=[selected_index])[0]
with open("video_0.mp4", "wb") as f:
    f.write(blob_file.read())

학습을 위한 데이터 준비

Training은 Lance의 빠른 랜덤 액세스 및 스캔 성능이 유용하게 활용될 수 있는 또 다른 영역입니다. 학습 데이터를 저장하는 메커니즘으로 Lance 데이터셋을 사용하고, 학습 파이프라인의 일부로 데이터를 셔플링하고 배치로 로드할 수 있습니다.

Lance의 blob API는 torchcodec과 호환되므로, 비디오 blob을 torch 텐서로 쉽게 디코딩할 수 있습니다:

from torchcodec.decoders import VideoDecoder
decoder = VideoDecoder(blob_file)
tensor = decoder[0]  # uint8 tensor of shape [C, H, W]

효율적인 비디오 디코딩을 위한 추가 함수는 torchcodec 문서를 참고하세요.

추가로, 자체 이미지 모델을 학습하기 위해 torchvision에 이미지 데이터를 로드하는 더 많은 예제는 Lance 문서를 참고하세요.

더 많은 Lance 데이터세트 탐색

Lance는 전통적인 테이블 데이터와 함께 멀티모달 블롭에 대한 네이티브 지원을 제공하는 오픈 포맷입니다. Hugging Face Hub 통합을 사용하면 이미지, 오디오, 비디오, 텍스트, 임베딩, 스칼라 메타데이터를 모두 한 곳에서 쉽게 다룰 수 있습니다.

Hugging Face Hub에서 더 많은 Lance 데이터셋을 탐색하고, 커뮤니티의 다른 사용자와 직접 만든 Lance 데이터셋을 공유해 보세요. 더 많은 코드 스니펫과 예제는 lance.org에서 확인해 볼 수 있습니다.