@huggingface/lerobot

Um parser para conjuntos de dados de robótica do LeRobot hospedados no Hugging Face Hub.

Tudo é lido por meio de solicitações HTTP com intervalo, portanto funciona sem alterações no navegador e no Node, e nunca baixa um conjunto de dados inteiro para responder a uma pergunta sobre ele.

Por quê

Os conjuntos de dados do LeRobot existem em dois layouts. Em v2.0 / v2.1, cada episódio possui seu próprio arquivo de vídeo e arquivo parquet, e o índice do episódio é um arquivo JSON Lines. Em v3.0, os episódios são concatenados em arquivos compartilhados e o índice é parquet, de modo que um episódio é um intervalo de bytes e um intervalo de tempo dentro de um arquivo maior.

Este pacote oculta essa diferença atrás de uma única forma LeRobotEpisode.

Instalar

npm install @huggingface/lerobot

hyparquet vem com ele e é usado para ler o índice de episódios v3.0 e os dados dos quadros. fzstd adiciona ZSTD ao SNAPPY embutido do hyparquet. Ambos são importados sob demanda, de modo que chamadores que precisam apenas de info() ou de uma listagem de episódios v2 nunca os carregam.

Uso

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 conta posições no índice, que correspondem aos índices dos episódios apenas quando um conjunto de dados numera seus episódios como 0, 1, 2, … Alguns começam em 10 ou pulam episódios excluídos, então use episode(index) para abrir um episódio específico. Em um conjunto de dados numerado como 0, 1, 2, …, o custo é o mesmo de episodes({ offset: index, limit: 1 }).

videos[].fromSec / toSec são os deslocamentos do episódio dentro de url. No v3.0, vários episódios compartilham um único arquivo, então busque até fromSec e pare em toSec; no v2.x, cada episódio tem seu próprio arquivo e o intervalo simplesmente o abrange.

data aponta para as linhas de quadro daquele episódio, para chamadores que desejam plotar observation.state ou action por conta própria. fromRow é inclusivo e toRow é exclusivo; ambos são deslocamentos de linha dentro de data.url, não índices em todo o conjunto de dados. Para o v3, quando uma página começa no meio de um arquivo de dados, a listagem de episódios também lê o rodapé parquet desse arquivo para encontrar onde ele começa. data está ausente quando esse arquivo não pode ser lido ou diverge dos metadados do episódio.

Mantenha um único LeRobotDataset enquanto navega pelos episódios: assim como info(), ele memoriza os arquivos de índice v3.0 que percorreu, de modo que uma consulta posterior de página ou episode() vá direto ao arquivo que o contém.

Fixando uma revisão

Passe um sha de commit sempre que o resultado for armazenado ou em cache em qualquer lugar, para que um push posterior não possa alterar o que você analisou:

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

Conjuntos de dados privados e restritos

Passe o seu próprio fetch para adicionar credenciais:

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

Em um navegador no huggingface.co, os cookies de sessão são suficientes:

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

Análise sem busca

parseInfo é puro, para chamadores que já possuem os bytes:

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

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

Ela lança uma exceção para qualquer coisa que não seja um arquivo de informações utilizável, incluindo um ponteiro LFS, uma leitura truncada ou uma codebase_version que este pacote não implementa.