Lance

Lance, yapay zeka için açık kaynaklı çok modlu bir lakehouse tablo biçimidir. Hub üzerindeki Lance veri kümelerine erişmek için Hugging Face yollarını (hf://) kullanabilirsiniz. Bu sayede, tüm veri kümesini yerel olarak kopyalamak zorunda kalmadan Hugging Face Hub üzerindeki büyük veri kümelerini tarayabilir ve aratabilirsiniz.

Başlangıç

Başlamak için pylance ve pyarrow paketlerini pip ile yükleyin:

pip install pylance pyarrow

Neden Lance?

• ML/AI iş yükleri için optimize edilmiştir: Lance, tarama performansından ödün vermeden hızlı rastgele erişim için tasarlanmış modern bir sütun tabanlı biçimdir; bu da onu arama, analitik, eğitim, özellik mühendisliği ve daha birçok kullanım senaryosu için faydalı kılar.
• Çok modlu varlıklar, gömme (embedding) ve geleneksel skaler verilerin yanı sıra Lance içinde bayt olarak veya ikili nesneler (”dosya olarak bloblar”) biçiminde saklanır; bu da büyük veri setlerinizi Hub üzerinden yönetmeyi, paylaşmayı ve dağıtmayı kolaylaştırır.
• Dizinleme birinci sınıf bir vatandaşdır (biçimin kendisine yerleşiktir): Lance, Hub'daki veri setinin hemen yanında duran, hızlı, disk üzerinde çalışan ve ölçeklenebilir vektör ve FTS dizinleriyle birlikte gelir; böylece kullanıcılarınızın yeniden hesaplamasına gerek kalmadan yalnızca verilerinizi değil, gömme ve dizinlerinizi de paylaşabilirsiniz.
• Esnek şema ve veri evrimi, yeni özellik/sütunları (moderasyon etiketleri, gömlemeler vb.) tüm tabloyu yeniden yazma gerekmeden kademeli olarak eklemenizi sağlar.

Tüm verilerinizi tek bir yerde saklayın

Lance'da çok modlu veri varlıklarınız (görseller, ses, video), skaler meta verileriniz ve gömme (embedding) değerlerinizle birlikte ham baytlar olarak saklanır. Bu sayede birden fazla depolama sistemini bir araya getirme ihtiyacı duymadan veri setinizi tek bir yerden taramak ve filtrelemek kolaylaşır.

Hub'dan veri setleriyle akış

Verileri yerel olarak indirmeden taramak ve üzerinde gezinmek için load_dataset(..., streaming=True) kullanın.

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, sahip olduğunuzu anlamak için metadata örneklemesi almak için harikadır. Vektör araması veya büyük ikili blob'larla çalışmak için, aşağıda açıklanan Lance dataset API'sini kullanabilirsiniz.

Streaming, basit skaler metadata örneklemesi için hızlıdır ancak gömceler veya büyük çok modlu varlıklar için o kadar hızlı değildir. Büyük veri setleriyle çalışmak için metadata’yi taramak, ihtiyacınız olan alt kümeleri belirlemek ve Hub hız sınırlarıyla karşılaşmamak için veri setinin o kısmını yerel olarak indirmek önerilir: hf download lance-format/laion-1m --repo-type dataset --local-dir ./laion

Hub'dan lance.dataset ile akış

Hugging Face Hub üzerinde depolanan bir Lance veri setini hf:// yol belirteci kullanarak da tarayabilirsiniz. Bu işlem, veri setini yerel olarak indirmeden uzakta taramanıza olanak tanır. Lance dataset API'si ile yalnızca ihtiyacınız olan verileri almak için sınırlar, filtreler ve projeksiyonlar belirlemek çok basittir.

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)

İkili varlıklarla çalışın

Aşağıdaki örnek, görüntülerin bir Lance veri setinden image sütununda ham JPEG baytları olarak nasıl alındığını ve aşağı akışta nasıl kullanıldığını gösterir. Baytları almak için ds.take kullanın ve bunları başka yerlerde kullanabilmek için diske yazın.

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']}")

Bir alt küme yeni bir Lance veri setine yazın

Büyük veri setleriyle mi çalışıyorsunuz? Hub'dan satır alt kümesi seçmek için filtreli bir tarama çalıştırmak ve bunları yerel bir Lance veri setine dönüştürmek oldukça basittir.

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")

Dizin oluştur

Veri setinizle ilişkili bir indeks yoksa, yerel olarak indirdikten sonra bir tane oluşturabilirsiniz.

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

Daha ayrıntılı bir örnek için vektör indeksi oluşturma hakkında Lance belgelerini inceleyin. Bir vektör indeksi oluşturduktan sonra, gömme (embedding) aracılığıyla veriler üzerinde benzerlik araması çalıştırabilirsiniz.

Vektör araması

Lance'da indeksler birinci sınıf vatandaşlar olduğu için yalnızca verilerinizi değil, gömlemlerinizi ve indekslerinizi de birlikte saklayabilir ve bunlara doğrudan Hub üzerinde sorgu yapabilirsiniz. Veri seti için indeks bilgilerini listelemek için describe_indices() yöntemini kullanmanız yeterlidir. Veri setinde bir indeks yoksa, veri setinin yerel bir sürümünü yazmak için lance.write_dataset() kullanabilir ve ihtiyaçlarınıza uygun bir indeks oluşturmak için LanceDataset.create_index kullanabilirsiniz.

Aşağıdaki örnek, img_emb alanı üzerinde zaten bir vektör dizinine sahip olduğumuz bir veri setini göstermektedir:

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
#.   )
# ]

Vektör arama sorgularını, veriyi indirmeden doğrudan uzak veri setinde çalıştırabilirsiniz (veya tercih ederseniz, veri setini yerel olarak indirip yeni bir indeks oluşturabilirsiniz). Aşağıdaki örnek, bir görüntü gömme (embedding) sorgu vektörü olarak kullanılarak vektör indeksinde en yakın komşu araması nasıl çalıştırılacağını göstermektedir.

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()

Büyük bir k veya nprobes değeri ayarlamak ya da büyük bir sorgu grubunu tek seferde göndermek Hub hız sınırlarına takılabilir. Yoğun kullanım için veri setini (veya bir alt kümesini) yerel olarak indirin ve Lance'i yerel yola yönlendirerek kısıtlamadan kaçının.

Veri kümesi evrimi

Lance’ın en güçlü özelliklerinden biri esnek ve sıfır maliyetli veri evrimidir; bu sayede orijinal tabloyu yeniden yazmadan türetilmiş sütunları kolayca ekleyebilirsiniz. Çok büyük ve büyük miktarda blob içeren tablolar için I/O tasarrufu oldukça önemli olabilir. Verileriniz üzerinde ML/AI mühendisliği görevleri için deneyler yapıyor ve sık sık yeni özellikler, gömlemeler veya türetilmiş meta veriler ekliyorsanız bu özellik son derece ilgili bir konudur.

Aşağıdaki örnek, mevcut bir puan sütununa dayanarak bir görüntüyü NSFW olarak işaretleyen türetilmiş bir moderation_label sütunu eklemenin nasıl yapılacağını gösterir. Bu değişikliği yaptığınızda, yeni sütunu geriye dönük olarak doldurmak sadece yeni sütun verilerini yazar; orijinal görüntü bloblarını veya diğer sütunlardaki verilere dokunmaz. Ayrıca, herhangi bir veriyi geriye dönük olarak doldurmadan yalnızca yeni sütun şemasını eklemeyi de seçebilirsiniz.

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 veri kümelerinde sütunları değiştirme ve silme yöntemlerini öğrenmek için veri evrimi hakkında Lance belgelerine göz atın.

Video blob'larıyla çalışın

Lance tabloları büyük satır içi video blob'larını da destekler. OpenVid-1M veri seti (bu makale'den) yüksek kaliteli, ifade gücü yüksek videoları ve açıklamalarını içerir. Video verileri, Hub'daki aşağıdaki Lance veri setinin video_blob sütununda saklanır.

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()

Diğer veri biçimlerinin aksine, büyük çok modlu ikili nesneler (blob) Lance'da birinci sınıf vatandaşlardır. blob API'si, Lance veri kümelerinde büyük blob'ları depolamak ve almak için yüksek düzey bir API sağlar. Aşağıdaki örnek, daha ağır video blob'larını yüklemeye gerek kalmadan verimlilikle meta verileri nasıl görüntüleyeceğinizi ve ardından ilgili video blob'larını talep üzerine nasıl alacağınızı göstermektedir.

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())

Eğitim için veri hazırlama

Eğitim, Lance’ın hızlı rastgele erişim ve tarama performansının faydalı olabileceği bir diğer alandır. Eğitim verileriniz için depolama mekanizması olarak Lance veri kümelerini kullanabilir, eğitim hatlarınızın bir parçası olarak bunları karıştırıp partilere yükleyebilirsiniz.

Lance'daki blob API'si torchcodec ile uyumludur, bu sayede video bloblarını torch tensörleri olarak kolayca çözebilirsiniz:

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

Videoları verimli bir şekilde çözmek için daha fazla işlev hakkında bilgi için torchcodec belgelerini inceleyin.

Ayrıca, kendi görüntü modellerinizi eğitmek için torchvision içine görüntü verisi yükleme konusunda daha fazla örnek için Lance belgelerini de inceleyebilirsiniz.

Daha fazla Lance veri setini keşfedin

Lance, geleneksel tablo verilerinizin yanı sıra çok modlu blob'lar için yerel destek sunan açık bir biçimdir. Hugging Face Hub entegrasyonu sayesinde görüntüler, ses, video, metin, gömceler ve skaler meta verilerle tek bir yerde kolayca çalışabilirsiniz.

Hugging Face Hub'da daha fazla Lance veri setini keşfedin ve kendi Lance veri setlerinizi toplulukla paylaşın! Daha fazla kod parçası ve örnek için lance.org adresini ziyaret edebilirsiniz.