Lance

Lance هو تنسيق جداول مفتوح المصدر متعدد الوسائط لبحيرات البيانات (lakehouse) مخصص للذكاء الاصطناعي. يمكنك استخدام مسارات Hugging Face (hf://) للوصول إلى مجموعات بيانات Lance على Hub. وهذا يتيح لك مسح مجموعات البيانات الكبيرة والبحث فيها على Hugging Face Hub دون الحاجة إلى نسخ المجموعة بأكملها محليًا.

البدء

للبدء، ثبّت pylance وpyarrow باستخدام pip:

pip install pylance pyarrow

لماذا لانس؟

• مُحسَّن لأحمال عمل التعلم الآلي/الذكاء الاصطناعي: Lance هو تنسيق أعمدة حديث مصمَّم للوصول العشوائي السريع دون المساس بأداء المسح، مما يجعله مفيدًا لحالات استخدام عديدة مثل البحث والتحليلات والتدريب وهندسة الميزات وغيرها.
• تُخزَّن الأصول متعددة الوسائط على شكل بايتات، أو كائنات ثنائية (”blobs as files”) في Lance إلى جانب التضمينات، والبيانات القياسية التقليدية — مما يسهّل إدارة مجموعات البيانات الكبيرة الخاصة بك ومشاركتها وتوزيعها عبر Hub.
• تُعدّ الفهرسة مواطناً من الدرجة الأولى (مدمجة في الصيغة ذاتها): يأتي Lance مع فهارس متجهية وفهارس بحث نصي كامل (FTS) سريعة وقابلة للتوسع ومخزّنة على القرص، وتقع مباشرةً إلى جانب مجموعة البيانات على Hub، مما يتيح لك مشاركة بياناتك وكذلك تمثيلاتها (embeddings) وفهارسك دون أن يضطر مستخدموك إلى إعادة حسابها.
• يسمح لك المخطط المرن وتطور البيانات بإضافة ميزات/أعمدة جديدة بشكل تدريجي (وسوم الإشراف، التضمينات، إلخ) دون الحاجة إلى إعادة كتابة الجدول بالكامل.

خزّن جميع بياناتك في مكان واحد

في Lance، تُخزَّن أصول بياناتك متعددة الوسائط (الصور، الصوت، الفيديو) كبيانات خام (raw bytes) إلى جانب بياناتك الوصفية القياسية (scalar metadata) والتضمينات (embeddings). وهذا يجعل من السهل فحص مجموعة بياناتك وتصفيتها في مكان واحد دون الحاجة إلى دمج أنظمة تخزين متعددة.

التدفق من Hub باستخدام datasets

استخدم 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) رائعةً لعينة البيانات الوصفية (Metadata) لفهم ما تملكه. أما للبحث المتجهي أو العمل مع كتل ثنائية كبيرة، فيمكنك استخدام واجهة dataset الخاصة بـ Lance، والمُوضّحة أدناه.

يعتبر البث سريعًا عند أخذ عينات من البيانات الوصفية القياسية البسيطة، لكنه ليس سريعًا بالقدر نفسه عند التعامل مع التضمينات أو الأصول متعددة الوسائط الكبيرة. للعمل مع مجموعات البيانات الكبيرة، يُوصى بمسح البيانات الوصفية، وتحديد المجموعات الفرعية التي تحتاجها، وتنزيل تلك الجزء من مجموعة البيانات محليًا لتجنب مواجهة حدود معدل Hub: hf download lance-format/laion-1m --repo-type dataset --local-dir ./laion

البث من Hub باستخدام lance.dataset

يمكنك أيضًا مسح مجموعة بيانات Lance مخزّنة على Hugging Face Hub باستخدام مُحدِّد المسار hf://. يقوم هذا المسح بمعالجة مجموعة البيانات عن بُعد دون الحاجة إلى تنزيلها محليًا. وباستخدام واجهة برمجة تطبيقات dataset الخاصة بـ Lance، يصبح من السهل جدًا تحديد حدود وفلاتر وإسقاطات لجلب البيانات التي تحتاجها فقط.

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 على شكل بايتات JPEG خام في عمود image، واستخدامها في المراحل اللاحقة. استخدم 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']}")

اكتب مجموعة فرعية إلى مجموعة بيانات Lance جديدة

هل تعمل مع مجموعات بيانات كبيرة؟ من السهل تشغيل مسح مُصفّى لاختيار مجموعة فرعية من الصفوف من 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، يمكنك تخزين بياناتك ومغلفاتك (embeddings) وفهارسك معًا والاستعلام عنها مباشرةً على 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، إذ تتيح لك إضافة أعمدة مشتقة دون الحاجة إلى إعادة كتابة الجدول الأصلي. وفي حالة الجداول الضخمة التي تحتوي على كميات كبيرة من البيانات الثنائية (blobs)، يمكن أن تكون التوفيرات في عمليات الإدخال/الإخراج كبيرة بشكل ملحوظ. وتكتسب هذه الميزة أهمية كبيرة إذا كنت تجري تجارب على بياناتك لأغراض هندسة التعلم الآلي/الذكاء الاصطناعي، وتجد نفسك تضيف باستمرار ميزات جديدة، أو تمثيلات (embeddings)، أو بيانات وصفية مشتقة.

يُظهر المثال أدناه كيفية إضافة عمود مشتق moderation_label يحدد الصورة على أنها NSFW بناءً على عمود درجات موجود مسبقًا. عند إجراء هذا التغيير، فإن إعادة تعبئة العمود الجديد فقط تكتب بيانات العمود الجديد دون المساس بكتل الصور الأصلية أو البيانات في الأعمدة الأخرى. يمكنك أيضًا اختيار إضافة مخطط العمود الجديد فقط دون إعادة تعبئة أي بيانات.

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.

العمل مع كائنات الفيديو

تدعم جداول Lance أيضًا مقاطع فيديو مضمّنة كبيرة. يحتوي مجموعة البيانات OpenVid-1M (من هذا البحث) على مقاطع فيديو عالية الجودة وتعبيرية مع عناوينها. يتم تخزين بيانات الفيديو في العمود video_blob من مجموعة بيانات Lance التالية على Hub.

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

على عكس صيغ البيانات الأخرى، تُعدّ الكائنات الثنائية متعددة الوسائط الكبيرة (blobs) مواطنين من الدرجة الأولى في Lance. يوفر blob API واجهة برمجية عالية المستوى لتخزين واسترجاع الكائنات الثنائية الكبيرة في مجموعات بيانات Lance. يُظهر المثال التالي كيفية تصفح البيانات الوصفية بكفاءة دون تحميل كائنات الفيديو الأثقل، ثم جلب كائنات الفيديو ذات الصلة عند الطلب.

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

تجهيز البيانات للتدريب

يُعد التدريب مجالاً آخر يمكن أن تكون فيه سرعة الوصول العشوائي وأداء المسح في Lance مفيدة. يمكنك استخدام مجموعات بيانات Lance كآلية تخزين لبيانات التدريب، مع خلطها وتحميلها في دفعات كجزء من خطوط أنابيب التدريب الخاصة بك.

يتوافق واجهة برمجة التطبيقات (API) الخاصة بـ blob في Lance مع torchcodec، مما يتيح لك فك ترميز مقاطع الفيديو المخزنة كـ blob بسهولة إلى متجهات torch:

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

راجع وثائق torchcodec لمزيد من الدوال لفك ترميز الفيديوهات بكفاءة.

بالإضافة إلى ذلك، يمكنك الاطلاع على توثيق Lance لمزيد من الأمثلة حول تحميل بيانات الصور إلى torchvision لتدريب نماذج الصور الخاصة بك.

استكشف المزيد من مجموعات بيانات Lance

Lance هو تنسيق مفتوح يدعم بشكل أصلي الكائنات متعددة الوسائط إلى جانب بياناتك الجدولية التقليدية. مع تكامل Hugging Face Hub، يمكنك العمل بسهولة مع الصور والصوت والفيديو والنصوص والتضمينات والميتاداتا القياسية في مكان واحد.

استكشف المزيد من مجموعات بيانات Lance على مركز Hugging Face، وشارك مجموعات بيانات Lance الخاصة بك مع الآخرين في المجتمع! يمكنك زيارة lance.org لمزيد من مقتطفات الأكواد والأمثلة.