@huggingface/lerobot

Parser untuk dataset robotika LeRobot yang dihosting di Hugging Face Hub.

Semuanya dibaca melalui permintaan HTTP berjangkauan, sehingga berfungsi tanpa perubahan di browser dan di Node, dan tidak pernah mengunduh seluruh dataset untuk menjawab pertanyaan tentangnya.

Mengapa

Dataset LeRobot hadir dalam dua tata letak. Pada v2.0 / v2.1, setiap episode memiliki file video dan parquet miliknya sendiri, dan indeks episode berupa file JSON Lines. Pada v3.0, episode digabungkan ke dalam file bersama dan indeksnya berupa parquet, sehingga sebuah episode merupakan rentang byte dan rentang waktu di dalam file yang lebih besar.

Paket ini menyembunyikan perbedaan tersebut di balik satu bentuk LeRobotEpisode.

Instal

npm install @huggingface/lerobot

hyparquet disertakan dan digunakan untuk membaca indeks episode v3.0 serta data frame. fzstd menambahkan ZSTD di samping SNAPPY bawaan hyparquet. Keduanya diimpor sesuai kebutuhan, sehingga pemanggil yang hanya memerlukan info() atau daftar episode v2 tidak akan memuatnya.

Penggunaan

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 menghitung posisi dalam indeks, yang hanya cocok dengan indeks episode ketika dataset menomori episodenya 0, 1, 2, … Beberapa dimulai dari 10 atau melompati episode yang dihapus, jadi gunakan episode(index) untuk membuka episode tertentu. Pada dataset yang dinomori 0, 1, 2, … biayanya sama dengan episodes({ offset: index, limit: 1 }).

videos[].fromSec / toSec adalah offset episode di dalam url. Pada v3.0, beberapa episode berbagi satu file, jadi cari ke fromSec dan berhenti di toSec; pada v2.x, setiap episode memiliki file sendiri dan rentang tersebut hanya mencakupnya.

data menunjuk ke baris frame untuk episode tersebut, bagi pemanggil yang ingin memetakan observation.state atau action sendiri. fromRow bersifat inklusif dan toRow bersifat eksklusif; keduanya adalah offset baris di dalam data.url, bukan indeks di seluruh dataset. Untuk v3, ketika halaman dimulai di tengah file data, daftar episode juga membaca footer parquet file tersebut untuk menemukan di mana ia dimulai. data tidak ada ketika file tersebut tidak dapat dibaca atau tidak sesuai dengan metadata episode.

Jaga satu LeRobotDataset saat membalik halaman episode: seperti info(), ia mengingat file indeks v3.0 yang telah dipindai, sehingga halaman berikutnya atau pencarian episode() langsung menuju file yang menyimpannya.

Mencengkeram revisi

Lewati commit sha setiap kali hasil disimpan atau di-cache di mana pun, sehingga push berikutnya tidak dapat mengubah apa yang telah Anda parse:

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

Dataset privat dan bergerbang

Lewati fetch Anda sendiri untuk menambahkan kredensial:

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

Di browser di huggingface.co, cookie sesi sudah cukup:

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

Parsing tanpa mengambil data

parseInfo bersifat murni, untuk pemanggil yang sudah memiliki byte:

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

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

Itu akan melempar kesalahan untuk apa pun yang bukan merupakan file info yang dapat digunakan, termasuk pointer LFS, pembacaan yang terpotong, atau codebase_version yang tidak diimplementasikan oleh paket ini.