LeRobot documentation

Conjuntos de dados

LeRobot

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.6.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Conjuntos de dados

LeRobotDataset é o formato que todos os scripts do LeRobot leem e gravam. Ele é consciente de episódios, decodifica observações de vídeo sob demanda e faz round-trip para o Hugging Face Hub.

Consulte Usando LeRobotDataset para o formato e as operações comuns, Portando Conjuntos de Dados Grandes para migração e Ferramentas para a CLI.

LeRobotDataset

classe lerobot.datasets.LeRobotDataset

( repo_id: strroot: str | pathlib.Path | None = Noneepisodes: list[int] | None = Noneepisode_filter: collections.abc.Callable[[dict], bool] | None = Noneimage_transforms: collections.abc.Callable | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsedownload_videos: bool = Truevideo_backend: str | None = Nonereturn_uint8: bool = Falsedepth_output_unit: str = 'mm'batch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Noneencoder_threads: int | None = Nonestreaming_encoding: bool = Falseencoder_queue_maxsize: int = 30repo_type: str = 'dataset'token: str | bool | None = Nonevideo_decoder_cache_size: int | None = None )

add_frame

( frame: dict )

Parâmetros

frame — Dicionário que mapeia os nomes dos recursos para seus valores neste frame. Deve incluir uma chave 'task'. Tensors do Torch são convertidos para numpy.

Exceções

RuntimeError

RuntimeError — Se o conjunto de dados for somente leitura (sem escritor).

Adicione um único quadro ao buffer do episódio atual.

Delega para DatasetWriter.add_frame. O dataset deve estar em modo de escrita (criado via create ou resume).

clear_episode_buffer

( delete_images: bool = True )

Parâmetros

delete_images — Se True, também remove os arquivos de imagem temporários gravados no disco para o episódio atual.

Exceções

RuntimeError

RuntimeError — Se o conjunto de dados for somente leitura (sem escritor).

Descarte o buffer do episódio atual sem salvar.

Delega para DatasetWriter.clear_episode_buffer. Útil para descartar um episódio de gravação falho ou interrompido.

clear_image_transforms

( )

Remove a transformação aplicada às observações visuais.

criar

( repo_id: strfps: intfeatures: dictroot: str | pathlib.Path | None = Nonerobot_type: str | None = Noneuse_videos: bool = Truetolerance_s: float = 0.0001image_writer_processes: int = 0image_writer_threads: int = 0video_backend: str | None = Nonebatch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Nonemetadata_buffer_size: int = 10streaming_encoding: bool = Falseencoder_queue_maxsize: int = 30encoder_threads: int | None = Nonevideo_files_size_in_mb: int | None = Nonedata_files_size_in_mb: int | None = None )

Parâmetros

repo_id — Identificador do repositório, tipicamente '{hf_user}/{dataset_name}'.
fps — Quadros por segundo usados durante a coleta de dados.
features — Dicionário de especificação de recursos que mapeia os nomes dos recursos para seus metadados de tipo/formato.
root — Diretório local para armazenamento do conjunto de dados. O padrão é $HF_LEROBOT_HOME/{repo_id}.
robot_type — String opcional do tipo de robô armazenada nos metadados.
use_videos — Se True, as modalidades visuais são armazenadas como vídeos MP4. Se False, são armazenadas como imagens.
tolerance_s — Tolerância de sincronização de timestamp em segundos.
image_writer_processes — Número de subprocessos para escrita assíncrona de imagens. 0 significa usar apenas threads.
image_writer_threads — Número de threads para escrita assíncrona de imagens.
video_backend — Backend de decodificação de vídeo (usado ao ler de volta).
batch_encoding_size — Número de episódios a acumular antes de codificar os vídeos em lote. 1 significa codificar imediatamente.
rgb_encoder — Configurações do codificador de vídeo para câmeras (código, qualidade, etc.). Quando None, rgb_encoder_defaults() é usado.
depth_encoder — Configurações do codificador de vídeo para câmeras de profundidade (código, qualidade, etc.). Quando None, depth_encoder_defaults() é usado.
encoder_threads — Número de threads do codificador (global). None deixa o codec decidir.
metadata_buffer_size — Número de registros de metadados de episódio a serem armazenados em buffer antes de serem gravados no parquet.
streaming_encoding — Se True, codifica os quadros do vídeo em tempo real durante a captura, em vez de gravar as imagens primeiro.
encoder_queue_maxsize — Máximo de quadros em buffer por câmera ao usar codificação em streaming.

Crie um novo LeRobotDataset do zero para gravar dados.

Retorna um dataset em modo de escrita com um DatasetWriter ativo. Use add_frame / save_episode para preenchê-lo e, em seguida, finalize quando terminar.

finalize

( )

Descarte todo o trabalho pendente e feche os escritores.

Deve ser chamado após a coleta/conversão de dados, caso contrário os metadados do rodapé não serão gravados nos arquivos parquet e o conjunto de dados ficará inválido.

Idempotente — seguro para chamar várias vezes. O del do DatasetWriter atua como uma rede de segurança caso isso nunca seja chamado explicitamente.

get_raw_item

( idx )

Obtenha um quadro bruto sem as transformações de imagem aplicadas.

Diferentemente de __getitem__, este retorna a linha bruta do dataset HF no índice fornecido, sem expansão de delta-timestamp, decodificação de vídeo ou transformações de imagem.

has_pending_frames

( )

Verifique se há quadros não salvos no buffer de episódios.

push_to_hub

( branch: str | None = Nonetags: list | None = Nonelicense: str | None = 'apache-2.0'tag_version: bool = Truepush_videos: bool = Trueprivate: bool | None = Noneallow_patterns: list[str] | str | None = Noneupload_large_folder: bool = False**card_kwargs )

Parâmetros

branch — Branch opcional para o push. Criada a partir da revisão atual, caso não exista.
tags — Lista opcional de tags para o cartão do conjunto de dados.
license — Identificador de licença para o cartão do conjunto de dados.
tag_version — Se True, cria uma tag Git para a versão atual da base de código.
push_videos — Se False, ignora o upload do diretório videos/.
private — Se True, cria um repositório privado. Se None (padrão), usa o padrão da organização no Hub (afeta apenas organizações).
allow_patterns — Padrão(s) Glob que restringem quais arquivos serão enviados.
upload_large_folder — Se True, usa upload_large_folder em vez de upload_folder para conjuntos de dados muito grandes.
**card_kwargs — Argumentos de palavra-chave adicionais encaminhados para a criação do card do dataset.

Envie o conjunto de dados para o Hugging Face Hub.

Cria o repositório, caso ele não exista, faz o upload de todos os arquivos do conjunto de dados (com a opção de excluir vídeos), gera um cartão do conjunto de dados e marca a revisão com a versão atual da base de código.

retomar

( repo_id: strroot: str | pathlib.Path | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsevideo_backend: str | None = Nonebatch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Noneencoder_threads: int | None = Noneimage_writer_processes: int = 0image_writer_threads: int = 0streaming_encoding: bool = Falseencoder_queue_maxsize: int = 30token: str | bool | None = None )

Parâmetros

repo_id — Identificador do repositório do conjunto de dados existente.
root — Diretório local do conjunto de dados. Quando fornecido, os downloads do Hub são materializados diretamente neste diretório. Quando omitido, os downloads do Hub usam um cache de snapshot seguro por revisão em $HF_LEROBOT_HOME/hub.
tolerance_s — Tolerância de sincronização de timestamp em segundos.
revision — Revisão do Git (branch, tag ou hash de commit). O padrão é a tag da versão atual da base de código.
force_cache_sync — Se True, baixa novamente os metadados do Hub, mesmo que um cache local exista.
video_backend — Backend de decodificação de vídeo para leitura de dados.
batch_encoding_size — Número de episódios a acumular antes de codificar os vídeos em lote.
rgb_encoder — Configurações do codificador de vídeo para câmeras (código, qualidade, etc.). Quando None, rgb_encoder_defaults() é usado.
depth_encoder — Configurações do codificador de vídeo para câmeras de profundidade (código, qualidade, etc.). Quando None, depth_encoder_defaults() é usado.
encoder_threads — Número de threads do codificador (global). None deixa o codec decidir.
image_writer_processes — Subprocessos para escrita assíncrona de imagens.
image_writer_threads — Threads para escrita assíncrona de imagens.
streaming_encoding — Se True, codifica o vídeo em tempo real durante a captura.
encoder_queue_maxsize — Máximo de quadros em buffer por câmera para streaming.
token — Token de autenticação usado quando os metadados precisam ser baixados do Hub. O token não é retido na instância do dataset.

Retomar a gravação em um conjunto de dados existente.

Carrega metadados de um conjunto de dados existente (local ou do Hub) e cria um DatasetWriter para adicionar novos episódios. O conjunto de dados do HF subjacente não é carregado até que finalize seja chamado e os dados sejam lidos em seguida.

save_episode

( episode_data: dict | None = Noneparallel_encoding: bool = True )

Parâmetros

episode_data — Dicionário de episódio pré-construído, opcional. Se None, usa o buffer interno de episódios preenchido por add_frame.
parallel_encoding — Se True e houver múltiplas câmeras, codifica os vídeos em paralelo usando um pool de processos.

Exceções

RuntimeError

RuntimeError — Se o conjunto de dados for somente leitura (sem escritor).

Salve o buffer do episódio atual no disco.

Delega para DatasetWriter.save_episode. Codifica vídeos, grava dados parquet e atualiza metadados. O buffer de episódios é redefinido em seguida.

select_columns

( column_names: str | list[str] )

Selecione colunas específicas do conjunto de dados subjacente.

Útil para extrair sequências de ações durante a reprodução sem carregar todos os recursos. Retorna um datasets.Dataset contendo apenas as colunas solicitadas.

set_image_transforms

( image_transforms: collections.abc.Callable | None )

Substitua a transformação aplicada às observações visuais.

LeRobotDatasetMetadata

classe lerobot.datasets.LeRobotDatasetMetadata

( repo_id: strroot: str | pathlib.Path | None = Nonerevision: str | None = Noneforce_cache_sync: bool = Falsemetadata_buffer_size: int = 10repo_type: typing.Literal['dataset', 'bucket'] = 'dataset'token: str | bool | None = None )

Contêiner de metadados para um dataset LeRobot.

Gerencia os arquivos parquet info.json, stats.json, tasks.parquet e episodes/ que descrevem a estrutura, o conteúdo e as estatísticas de um conjunto de dados.

criar

( repo_id: strfps: intfeatures: dictrobot_type: str | None = Noneroot: str | pathlib.Path | None = Noneuse_videos: bool = Truemetadata_buffer_size: int = 10chunks_size: int | None = Nonedata_files_size_in_mb: int | None = Nonevideo_files_size_in_mb: int | None = None )

Parâmetros

repo_id — Identificador do repositório (por exemplo, 'user/my_dataset').
fps — Quadros por segundo usados durante a coleta de dados.
features — Dicionário de especificação de recursos que mapeia os nomes dos recursos para seus metadados de tipo/formato.
robot_type — String opcional do tipo de robô armazenada nos metadados.
root — Diretório local para o conjunto de dados. O padrão é $HF_LEROBOT_HOME/{repo_id}. Não deve existir previamente.
use_videos — Se True, as modalidades visuais são codificadas como vídeos MP4.
metadata_buffer_size — Número de registros de metadados de episódio a serem armazenados em buffer antes de serem gravados no parquet.
chunks_size — Número máximo de arquivos por diretório de chunk. None usa o padrão.
data_files_size_in_mb — Tamanho máximo do arquivo parquet em MB. None usa o padrão.
video_files_size_in_mb — Tamanho máximo do arquivo de vídeo em MB. None usa o padrão.

Crie metadados para um novo dataset LeRobot do zero.

Inicializa o arquivo info.json no disco com o esquema de recursos e as configurações do conjunto de dados fornecidos. Nenhum dado de episódio é gravado ainda.

ensure_readable

( )

Garanta que os metadados sejam totalmente carregados para operações de leitura.

Idempotente — quando os metadados já estão na memória, isso é apenas uma verificação de is None. Chame isso antes de transicionar do modo de escrita para o modo de leitura na mesma instância.

filter_episodes

( predicate: Callablecandidates: list[int] | None = None )

Parâmetros

predicate — Predicado sobre as linhas de metadados por episódio usado para selecionar episódios.
candidates — Lista opcional de índices de episódios para restringir a avaliação.

Filtre episódios cujo metadados satisfazem um predicado dado.

finalize

( )

Descarregue o buffer de metadados e feche o escritor parquet.

Idempotente — seguro para chamar várias vezes.

get_chunk_settings

( )

Obtenha as configurações atuais de tamanho de bloco e de arquivo.

get_data_file_path

( ep_index: int )

Parâmetros

ep_index — Índice de episódio com base zero.

Exceções

IndexError

IndexError — Se ep_index estiver fora do intervalo.

Retorna o caminho relativo do arquivo parquet para o índice de episódio fornecido.

get_task_index

( task: str )

Dada uma tarefa em linguagem natural, retorna seu task_index se a tarefa já existir no conjunto de dados, caso contrário retorna None.

get_video_file_path

( ep_index: intvid_key: str )

Parâmetros

ep_index — Índice de episódio com base zero.
vid_key — Chave de recurso que identifica o fluxo de vídeo (por exemplo, 'observation.images.laptop').

Exceções

IndexError ou ValueError

IndexError — Se ep_index estiver fora do intervalo.
ValueError — Se o conjunto de dados não armazenar vídeos (sem o modelo video_path).

Retorna o caminho relativo do arquivo de vídeo para o episódio e a chave de vídeo fornecidos.

rescale_depth_stats

( output_unit: str )

Redimensione as estatísticas do recurso de profundidade no local, de sua unidade registrada para output_unit.

As estatísticas de profundidade são armazenadas na unidade em que os quadros foram gravados (features[key]["info"]["depth_unit"]), enquanto os quadros são retornados em output_unit na leitura. Isso converte as entradas de estatísticas com unidade para que as estatísticas correspondam aos quadros vistos pelos consumidores.

save_episode

( episode_index: intepisode_length: intepisode_tasks: listepisode_stats: dictepisode_metadata: dict )

Parâmetros

episode_index — Índice base zero do episódio sendo salvo.
episode_length — Número de quadros neste episódio.
episode_tasks — Lista de descrições de tarefas para este episódio.
episode_stats — Estatísticas por recurso para este episódio.
episode_metadata — Metadados adicionais (índices de chunk/arquivo, intervalos de quadros, timestamps de vídeo, etc.).

Persista os metadados do episódio, atualize as informações do conjunto de dados e agregue as estatísticas.

Escreve os metadados do episódio no escritor parquet em buffer, incrementa os contadores totais de episódios/quadros em info.json e mescla as estatísticas do episódio nas estatísticas acumuladas do conjunto de dados.

save_episode_tasks

( tasks: list )

Parâmetros

tasks — Lista de descrições de tarefas únicas em linguagem natural.

Exceções

ValueError

ValueError — Se tasks contiver duplicados.

Registre as tarefas para o episódio atual e persista no disco.

Novas tarefas que ainda não existem no conjunto de dados recebem índices de tarefa sequenciais e são adicionadas ao arquivo parquet de tarefas.

update_chunk_settings

( chunks_size: int | None = Nonedata_files_size_in_mb: int | None = Nonevideo_files_size_in_mb: int | None = None )

Parâmetros

chunks_size — Número máximo de arquivos por diretório de chunk. Se for None, mantém o valor atual.
data_files_size_in_mb — Tamanho máximo para arquivos parquet de dados em MB. Se for None, mantém o valor atual.
video_files_size_in_mb — Tamanho máximo para arquivos de vídeo em MB. Se for None, mantém o valor atual.

Atualize as configurações de tamanho de chunk e de arquivo após a criação do conjunto de dados.

Isso permite que os usuários personalizem a organização do armazenamento sem modificar o construtor. Essas configurações controlam como os episódios são divididos em blocos e o tamanho máximo que os arquivos podem atingir antes de criar novos.

update_video_info

( video_key: str | None = Nonevideo_encoder: lerobot.configs.video.VideoEncoderConfig | None = Nonepreserve_keys: collections.abc.Iterable[str] | None = None )

Parâmetros

video_key — Se fornecido, atualiza apenas esta chave de vídeo. Caso contrário, atualiza todas as chaves de vídeo no conjunto de dados.
video_encoder — Configuração do encoder usada para produzir os vídeos. Quando fornecida, seus campos são registrados como entradas video.<field> junto com as entradas video.* derivadas do stream (veja get_video_info).
preserve_keys — Chaves cujos valores existentes são mantidos em vez de serem recalculados. None (padrão) recalcula todas as chaves.

Preencha ou atualize as informações de vídeo por recurso em info.json.

Aviso: esta função grava informações dos vídeos do primeiro episódio, assumindo implicitamente que todos os vídeos foram codificados da mesma forma. Além disso, isso significa que ela assume que o primeiro episódio existe.

Sempre reanalisar os vídeos e sobrescrever as informações existentes para cada chave recalculada. preserve_keys lista as chaves cujos valores existentes devem ser mantidos (por exemplo, entradas intrínsecas aos dados como is_depth_map e parâmetros de quantização de profundidade) em vez de serem recalculadas.

MultiLeRobotDataset

classe lerobot.datasets.MultiLeRobotDataset

( repo_ids: listroot: str | pathlib.Path | None = Noneepisodes: dict | None = Noneimage_transforms: collections.abc.Callable | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerances_s: dict | None = Nonedownload_videos: bool = Truevideo_backend: str | None = Nonetoken: str | bool | None = None )

Um conjunto de dados composto por múltiplos LeRobotDataset subjacentes.

Os LeRobotDataset subjacentes são efetivamente concatenados, e esta classe adota grande parte da estrutura de API do LeRobotDataset.

clear_image_transforms

( )

Remova a transformação deste conjunto de dados e de seus filhos.

set_image_transforms

( image_transforms: collections.abc.Callable | None )

Substitua a transformação para este conjunto de dados e seus descendentes.

StreamingLeRobotDataset

classe lerobot.datasets.StreamingLeRobotDataset

( repo_id: strroot: str | pathlib.Path | None = Noneepisodes: list[int] | None = Noneimage_transforms: collections.abc.Callable[[torch.Tensor], torch.Tensor] | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsestreaming: bool | None = Nonebuffer_size: int = 1000max_num_shards: int = 16seed: int = 42rng: numpy.random._generator.Generator | None = Noneshuffle: bool = Truereturn_uint8: bool = Falsedepth_output_unit: str = 'mm'video_backend: str | None = Nonedata_root: str | pathlib.Path | None = Noneepisode_pool_size: int | None = Noneprefetch_episodes: int = 8byte_budget_gb: float = 8.0repeat: bool = Falserepo_type: typing.Literal['dataset', 'bucket'] = 'dataset'token: str | bool | None = Nonedecode_threads: int = 2decoded_queue_size: int = 8video_decoder_cache_size: int | None = Nonenative_http_connections: int | None = Nonenative_http_subranges: int = 1sidecar_lock_timeout_s: float = 1800sampling_strategy: lerobot.streaming.episode_pool.StreamingSamplingStrategy | str = <StreamingSamplingStrategy.REMAINING: 'remaining'> )

Leitor de streaming com escopo de episódio para conjuntos de dados LeRobot.

Os metadados são armazenados em cache localmente, enquanto cada rank lê apenas as linhas Parquet e os intervalos de bytes MP4 necessários para os episódios completos que ele possui. Com N workers do DataLoader, cada worker possui uma parte disjunta e equilibrada por quadro dos episódios do rank, com seu próprio pool de episódios e 1/N do orçamento de bytes. Cada processo tem seu próprio GIL do Python, portanto N workers decodificam e montam amostras em paralelo. A posse dos episódios é disjunta e cada quadro selecionado é retornado exatamente uma vez por iteração. Os sidecars MP4 são resolvidos automaticamente e construídos em um cache local com chave de revisão quando ausentes.

Exemplo:

Uso básico:

from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset

# Create a streaming dataset with delta timestamps
delta_timestamps = {
    "observation.image": [-1.0, -0.5, 0.0],  # 1 sec ago, 0.5 sec ago, current
    "action": [0.0, 0.1, 0.2],  # current, 0.1 sec future, 0.2 sec future
}

dataset = StreamingLeRobotDataset(
    repo_id="your-dataset-repo-id",
    delta_timestamps=delta_timestamps,
)

# Iterate over the dataset
for i, item in enumerate(dataset):
    print(f"Sample {i}: Episode {item['episode_index']} Frame {item['frame_index']}")
    # item will contain stacked frames according to delta_timestamps
    if i >= 10:
        break

load_state_dict

( state: dict )

Parâmetros

state (dict[str, int]) — Época local do rank, deslocamento de amostra e tamanho do lote. Chaves ausentes têm valores padrão de 0, 0 e 1.

Exceções

ValueError

ValueError — Se a época ou o deslocamento for negativo, ou o tamanho do lote não for positivo.

Restaure a posição de âncora do próximo iterador sem buscar as amostras ignoradas.

Nota: Reproduzir a ordem das âncoras requer o mesmo conjunto de dados, semente, amostrador, configurações de pool, topologia distribuída e número de workers do DataLoader. Com vários workers, o deslocamento é o deslocamento do rank em lotes inteiros de batch_size; cada worker deriva sua própria parte, porque o DataLoader pega lotes de seus workers em turnos. Transformações aleatórias de imagem não são restauradas por este método.

num_episodes_for_rank

( rank: intworld_size: int )

Retorna o número de episódios inteiros que um rank de treinamento possui.

num_frames_for_rank

( rank: intworld_size: intnum_workers: int )

Retorne os quadros pertencentes a um único rank de treinamento sob sharding balanceado de episódios inteiros.

set_data_parallel_shard

( rank: intworld_size: int )

Fixe o rank e o tamanho do mundo da paralelização de dados, antes de torch.distributed e do ambiente.

Um worker do DataLoader iniciado não possui torch.distributed inicializado; os valores chegam até ele por meio de pickling.

set_epoch

( epoch: int )

Parâmetros

epoch (int) — Época de cobertura usada para semear o próximo plano de amostragem quando o embaralhamento está habilitado.

Exceções

ValueError

ValueError — Se epoch for negativo.

Selecione um epoch não negativo e redefina o offset de retomada local da rank.

state_dict

( ) → dict[str, int]

Retorna

dict[str, int]

Época, deslocamento da amostra gerada e tamanho do lote de retomada.

Retorna a posição local atual do iterador.

Nota: Com o prefetch do DataLoader, as amostras geradas podem ainda não ter sido consumidas pelo treinamento. O pipeline de treinamento restaura sua posição a partir das etapas concluídas. Com vários trabalhadores do DataLoader, cada processo de trabalhador mantém apenas sua própria posição.

Update on GitHub

←Motores Políticas→