@huggingface/lerobot

Trình phân tích cho các bộ dữ liệu robot LeRobot được lưu trữ trên Hugging Face Hub.

Mọi thứ đều được đọc qua các yêu cầu HTTP có phạm vi, nên hoạt động không đổi cả trong trình duyệt lẫn Node, và không bao giờ tải toàn bộ bộ dữ liệu để trả lời một câu hỏi về nó.

Tại sao

Bộ dữ liệu LeRobot tồn tại ở hai bố cục. Trong v2.0 / v2.1, mỗi episode có tệp video và tệp parquet riêng, và chỉ mục episode là tệp JSON Lines. Trong v3.0, các episode được nối vào các tệp dùng chung và chỉ mục là parquet, do đó một episode là một khoảng byte và một khoảng thời gian bên trong một tệp lớn hơn.

Gói này che giấu sự khác biệt đó phía sau một hình dạng LeRobotEpisode duy nhất.

Cài đặt

npm install @huggingface/lerobot

hyparquet đi kèm và được dùng để đọc chỉ mục tập v3.0 và dữ liệu khung hình. fzstd bổ sung ZSTD bên cạnh SNAPPY có sẵn trong hyparquet. Cả hai đều được nhập theo yêu cầu, nên các trình gọi chỉ cần info() hoặc danh sách tập v2 sẽ không bao giờ nạp chúng.

Cách sử dụng

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 đếm các vị trí trong chỉ mục, chỉ trùng khớp với chỉ mục tập khi bộ dữ liệu đánh số tập của nó là 0, 1, 2, … Một số bắt đầu từ 10 hoặc bỏ qua các tập đã bị xóa, vì vậy hãy dùng episode(index) để mở một tập cụ thể. Trên một bộ dữ liệu được đánh số 0, 1, 2, …, chi phí bằng với episodes({ offset: index, limit: 1 }).

videos[].fromSec / toSec là các offset của tập phim bên trong url. Trên v3.0, nhiều tập phim chia sẻ một tệp, vì vậy hãy seek đến fromSec và dừng tại toSec; trên v2.x, mỗi tập phim có tệp riêng và khoảng đơn giản bao trùm tệp đó.

data trỏ đến các hàng khung hình của tập đó, dành cho các trình gọi muốn tự vẽ biểu đồ observation.state hoặc action. fromRow là bao gồm và toRow là không bao gồm; cả hai đều là độ lệch hàng bên trong data.url, không phải chỉ mục xuyên suốt bộ dữ liệu. Đối với v3, khi một trang bắt đầu ở giữa tệp dữ liệu, việc liệt kê các tập cũng đọc phần chân parquet của tệp đó để tìm nơi nó bắt đầu. data vắng mặt khi tệp đó không thể đọc được hoặc không khớp với siêu dữ liệu của tập.

Giữ một LeRobotDataset trong khi duyệt qua các episode: giống như info(), nó ghi nhớ các tệp chỉ mục v3.0 đã được duyệt, nên việc truy vấn trang sau hoặc episode() sẽ đi thẳng đến tệp chứa thông tin cần thiết.

Cố định một bản sửa

Truyền commit sha bất cứ khi nào kết quả được lưu trữ hoặc cache ở đâu đó, để một lần push sau đó không thể thay đổi những gì bạn đã phân tích:

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

Bộ dữ liệu riêng tư và có kiểm soát

Truyền fetch của riêng bạn để thêm thông tin xác thực:

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

Trình duyệt trên huggingface.co, các cookie phiên là đủ:

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

Phân tích mà không cần tải

parseInfo là thuần túy, dành cho các bên gọi đã có sẵn các byte:

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

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

Nó sẽ gây lỗi với bất kỳ thứ gì không phải là tệp thông tin có thể sử dụng, bao gồm một con trỏ LFS, một lần đọc bị cắt cụt, hoặc một codebase_version mà gói này không hỗ trợ.