@huggingface/lerobot

Hugging Face Hub üzerinde barındırılan LeRobot robotik veri kümeleri için bir ayrıştırıcı.

Her şey aralıklı HTTP istekleri üzerinden okunur, bu nedenle tarayıcıda ve Node'da değişiklik yapılmadan çalışır ve bir veri seti hakkında soru yanıtlamak için tüm veri setini indirmez.

Neden

LeRobot veri kümeleri iki düzende bulunur. v2.0 / v2.1 sürümlerinde her bölümün kendi video ve parquet dosyası vardır ve bölüm indeksi bir JSON Lines dosyasıdır. v3.0 sürümünde bölümler ortak dosyalarda birleştirilir ve indeks parquet formatındadır; bu nedenle bir bölüm, daha büyük bir dosyanın içindeki bir bayt aralığı ve zaman aralığıdır.

Bu paket, o farkı tek bir LeRobotEpisode biçiminin arkasına gizler.

Yükle

npm install @huggingface/lerobot

hyparquet ile birlikte gelir ve v3.0 bölüm dizini ile kare verilerini okumak için kullanılır. fzstd, hyparquet’in yerleşik SNAPPY’sine ek olarak ZSTD ekler. Her ikisi de gerektiğinde içe aktarılır, bu nedenle yalnızca info() veya v2 bölüm listesi gerektiren çağrıcılar bunları asla yüklemeyebilir.

Kullanım

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, dizindeki konumları sayar ve bu konumlar yalnızca bir veri seti bölümlerini 0, 1, 2, … şeklinde numaralandırdığında bölüm indeksleriyle eşleşir. Bazı veri setleri 10’dan başlar veya silinen bölümleri atlar; bu nedenle belirli bir bölümü açmak için episode(index) kullanın. 0, 1, 2, … şeklinde numaralandırılmış bir veri setinde bu, episodes({ offset: index, limit: 1 }) ile aynı maliyete sahiptir.

videos[].fromSec / toSec, url içindeki bölümün ofsetleridir. v3.0 sürümünde birden fazla bölüm tek bir dosyayı paylaştığı için fromSec konumuna atlayıp toSec konumunda durun; v2.x sürümünde ise her bölümün kendi dosyası vardır ve aralık yalnızca bu dosyanın tamamını kapsar.

data, o epizodun kare satırlarına işaret eder; observation.state veya action değerlerini kendileri çizmek isteyen çağrıcılar için. fromRow dahil, toRow hariçtir; ikisi de veri seti genelindeki indeksler değil, data.url içindeki satır ofsetleridir. v3 için, bir sayfa bir veri dosyasının ortasından başlıyorsa, epizotları listeleme işlemi de o dosyanın parquet altbilgisini okuyarak nerede başladığını bulur. data, o dosya okunamadığında veya epizot meta verisiyle uyuşmadığında bulunmaz.

Bölümleri sayfa sayfa gezerken tek bir LeRobotDataset tutun: info() gibi, gezdiği v3.0 dizin dosyalarını hatırlar, böylece sonraki bir sayfa veya episode() sorgusu doğrudan ilgili dosyaya gider.

Revizyon sabitleme

Sonuç herhangi bir yerde saklanırken veya önbelleğe alınırken, sonraki bir push'un çözdüğünüz içeriği değiştirmesini önlemek için her zaman bir commit sha geçirin:

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

Özel ve kapılı veri setleri

Kimlik bilgileri eklemek için kendi fetch fonksiyonunuzu iletin:

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

huggingface.co adresindeki bir tarayıcıda oturum çerezleri yeterlidir:

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

İndirmeden ayrıştırma

parseInfo saf bir işlevdir; baytlara zaten sahip olan çağrıcılar için:

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

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

Kullanılabilir bir bilgi dosyası olmayan her şeyde, bir LFS işaretçisi, kesilmiş bir okuma veya bu paketin uygulamadığı bir codebase_version dahil olmak üzere, hata fırlatır.