@huggingface/lerobot

Hugging Face Hub에 호스팅된 LeRobot 로봇 데이터셋을 위한 파서입니다.

모든 데이터는 ranged HTTP 요청을 통해 읽히므로, 브라우저와 Node에서 모두 변경 없이 작동하며, 데이터셋에 대한 질문에 답하기 위해 전체 데이터셋을 다운로드하지 않습니다.

왜

LeRobot 데이터셋은 두 가지 레이아웃으로 존재합니다. v2.0 / v2.1에서는 각 에피소드가 자체 비디오와 parquet 파일을 가지며, 에피소드 인덱스는 JSON Lines 파일입니다. v3.0에서는 에피소드가 공유 파일로 연결되고 인덱스가 parquet이므로, 에피소드는 더 큰 파일 안의 바이트 범위와 시간 범위를 의미합니다.

이 패키지는 그 차이를 하나의 LeRobotEpisode 형식 뒤에 숨깁니다.

설치

npm install @huggingface/lerobot

hyparquet이 함께 제공되며, v3.0 에피소드 인덱스와 프레임 데이터를 읽는 데 사용됩니다. fzstd는 hyparquet의 내장 SNAPPY와 함께 ZSTD를 추가합니다. 둘 다 필요할 때만 가져오므로, 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() 조회는 해당 데이터를 포함하는 파일로 바로 이동합니다.

리비전 고정

결과가 어디에 저장되거나 캐시되는 경우, 나중에 push를 통해 파싱한 내용이 변경되지 않도록 항상 commit sha를 전달하세요:

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" }),
});

fetching 없이 파싱

parseInfo는 순수 함수로, 이미 바이트를 가진 호출자에게 적합합니다:

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

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

사용할 수 있는 info 파일이 아닌 모든 항목에서 예외를 발생시키며, 여기에는 LFS 포인터, 잘린 읽기, 이 패키지가 구현하지 않은 codebase_version이 포함됩니다.