@huggingface/lerobot

محلل لمجموعات بيانات روبوتات LeRobot المستضافة على Hugging Face Hub.

تتم قراءة كل شيء عبر طلبات HTTP النطاقية، لذا يعمل دون تغيير في المتصفح وفي Node، ولا يقوم أبدًا بتنزيل مجموعة بيانات كاملة للإجابة عن سؤال بشأنها.

لماذا

توجد مجموعات بيانات LeRobot بتنسيقين. في v2.0 / v2.1 يمتلك كل حلقة ملف فيديو وملف parquet خاصًا بها، ويكون فهرس الحلقات ملف JSON Lines. أما في v3.0 فتُدمج الحلقات في ملفات مشتركة ويكون الفهرس من نوع parquet، بحيث تكون الحلقة نطاقًا من البايتات ونطاقًا زمنيًا داخل ملف أكبر.

تُخفي هذه الحزمة ذلك الاختلاف خلف شكل LeRobotEpisode واحد.

التثبيت

npm install @huggingface/lerobot

يأتي hyparquet مدمجًا به، ويُستخدم لقراءة فهرس الحلقات v3.0 وبيانات الإطارات. يضيف fzstd ضغط ZSTD إلى جانب ضغط SNAPPY المدمج في hyparquet. يتم استيراد كلاهما عند الطلب، لذا فإن المستدعين الذين يحتاجون فقط إلى info() أو قائمة حلقات v2 لا يقومون بتحميلهما أبدًا.

الاستخدام

import { LeRobotDataset } from "@huggingface/lerobot";

const dataset = new LeRobotDataset("lerobot/svla_so101_pickplace");

const info = await dataset.info();
// {
//   codebaseVersion: "v3.0",
//   robotType: "so100_follower",
//   fps: 30,
//   totalEpisodes: 50,
//   totalFrames: 11939,
//   cameras: [{ key: "observation.images.up", width: 640, height: 480, codec: "av1" }, ...],
//   joints: { "observation.state": ["shoulder_pan.pos", "shoulder_lift.pos", ...] },
//   ...
// }

const episodes = await dataset.episodes({ limit: 10 });
// [
//   {
//     index: 0,
//     length: 303,
//     durationSec: 10.1,
//     tasks: ["pink lego brick into the transparent box"],
//     videos: [{ cameraKey: "observation.images.up", url: "https://...", fromSec: 0, toSec: 10.1 }, ...],
//     data: { url: "https://.../data/chunk-000/file-000.parquet", fromRow: 0, toRow: 303 },
//   },
//   ...
// ]

const episode = await dataset.episode(42);
// The episode whose `index` is 42, or undefined when there is none

offset يعدّ المواضع في الفهرس، والتي تتطابق مع فهارس الحلقات فقط عندما ترقم مجموعة البيانات حلقاتها 0، 1، 2، … بعض المجموعات تبدأ من 10 أو تتخطى الحلقات المحذوفة، لذا استخدم episode(index) لفتح حلقة محددة. في مجموعة بيانات مرقمة 0، 1، 2، … يكلف الأمر نفس تكلفة episodes({ offset: index, limit: 1 }).

videos[].fromSec / toSec هما إزاحات الحلقة داخل url. في v3.0 تتشارك عدة حلقات ملفًا واحدًا، لذا انتقل إلى fromSec وتوقف عند toSec؛ أما في v2.x فلكل حلقة ملفها الخاص ويمتد النطاق ببساطة على كامل الملف.

نقاط data في صفوف الإطار لذلك الحلقة، للمندّعين الذين يرغبون في رسم observation.state أو action بأنفسهم. fromRow شاملة وtoRow غير شاملة؛ كلاهما إزاحة صف داخل data.url، وليسا فهارس عبر مجموعة البيانات. بالنسبة إلى الإصدار v3، عندما تبدأ الصفحة في منتصف ملف بيانات، فإن سرد الحلقات يقرأ أيضًا تذييل parquet لذلك الملف للعثور على مكان بدايته. data غير موجودة عندما لا يمكن قراءة ذلك الملف أو عندما لا يتوافق مع بيانات وصف الحلقة.

احتفظ بـ LeRobotDataset واحد أثناء التنقل بين الحلقات: فمثل info()، يتذكر ملفات فهرس v3.0 التي تم فحصها، لذا فإن طلب الصفحة التالية أو البحث عن episode() يذهب مباشرة إلى الملف الذي يحتوي عليها.

تثبيت إصدار

مرّر معرف commit sha في كل مرة يُخزَّن فيها الناتج أو يُخزَّن مؤقتًا في أي مكان، بحيث لا يمكن لدفع (push) لاحق أن يغيّر ما قمت بتحليله:

const dataset = new LeRobotDataset("lerobot/svla_so101_pickplace", {
	revision: "f641879e22172be7e8161d5e6c1503c2d2feb657",
});

المجموعات الخاصة والمقيّدة

مرّر fetch خاصًا بك لإضافة بيانات الاعتماد:

const dataset = new LeRobotDataset("my-org/private-dataset", {
	additionalFetchHeaders: { Authorization: `Bearer ${accessToken}` },
});

في متصفح على huggingface.co، تكون ملفات تعريف الارتباط الخاصة بالجلسة كافية:

const dataset = new LeRobotDataset(repoId, {
	fetch: (url, init) => fetch(url, { ...init, credentials: "same-origin" }),
});

التحليل دون الجلب

parseInfo دالة نقية، مخصصة للمستدعين الذين يمتلكون بالفعل البايتات:

import { parseInfo } from "@huggingface/lerobot";

const info = parseInfo(await readFile("meta/info.json", "utf8"));

يُطلق استثناءً عند مواجهة أي شيء ليس ملف معلومات قابلًا للاستخدام، بما في ذلك مؤشر LFS، أو قراءة مبتورة، أو codebase_version لا يدعمه هذا الحزمة.