Hugging Face's logo

LeRobot documentation

프로세서

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

프로세서

Processor는 로봇, 데이터셋, 정책 사이의 데이터 변환 계층입니다. 파이프라인은 ProcessorStep의 체인이며, 각 단계는 데이터와 feature contract를 어떻게 변환하는지 선언합니다.

개념은 Robot Processors 소개를, 단계 작성은 직접 프로세서 구현하기를, 파이프라인이 제대로 작동하지 않을 때는 프로세서 파이프라인 디버깅을 참고하세요.

ProcessorStep

class lerobot.processor.ProcessorStep

< >

( )

데이터 처리 파이프라인의 단일 단계를 위한 추상 베이스 클래스.

각 단계는 데이터 전이에 변환을 수행하기 위해 __call__ 메서드와 데이터 특징의 형태나 타입을 어떻게 변경하는지 설명하기 위해 transform_features 메서드를 구현해야 합니다.

서브클래스는 state_dict와 load_state_dict를 구현하여 선택적으로 상태가 있는(stateful) 방식으로 동작할 수 있습니다.

get_config

< >

( )

직렬화를 위한 단계 구성을 반환합니다.

load_state_dict

< >

( state: dict[str, torch.Tensor] )

매개변수

  • state — 상태 텐서 사전.

state dictionary에서 해당 단계의 상태를 로드합니다.

초기화

< >

( )

처리 단계의 내부 상태를 초기화합니다(해당하는 경우).

save_artifacts

< >

( save_directory: Path )

non-tensor 에셋을 저장하고, map constructor 인수를 상대 경로로 매핑합니다.

state_dict

< >

( )

단계의 상태(예: 학습된 매개변수, 실행 평균)를 반환합니다.

transform_features

< >

( features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

매개변수

  • features — 관찰, 행동 등의 입력 특징을 설명하는 사전

이 단계가 파이프라인 기능의 설명을 어떻게 수정하는지 정의합니다.

이 메서드는 실제 데이터를 처리할 필요 없이 데이터가 파이프라인을 통해 흐르는 동안 데이터의 shape, dtype 또는 modality의 변화를 추적하는 데 사용됩니다.

DataProcessorPipeline

class lerobot.processor.DataProcessorPipeline

< >

( steps: Sequence[ProcessorStep] = <factory>name: str = 'DataProcessorPipeline'to_transition: Callable[[TInput], EnvTransition] = <factory>to_output: Callable[[EnvTransition], TOutput] = <factory>before_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory>after_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory> )

매개변수

  • steps — 파이프라인을 구성하는 ProcessorStep 객체의 시퀀스입니다.
  • name — 파이프라인에 대한 설명 이름.
  • to_transition — 원시 입력 데이터를 표준화된 EnvTransition 형식으로 변환하는 함수입니다.
  • to_output — 최종 EnvTransition을 원하는 출력 형식으로 변환하는 함수입니다.
  • before_step_hooks — 각 단계가 실행되기 전에 호출될 함수 목록입니다.
  • after_step_hooks — 각 단계가 실행된 후 호출될 함수 목록입니다.

Hugging Face Hub와 통합된 데이터 처리를 위한 순차적 파이프라인입니다.

이 클래스는 여러 ProcessorStep 인스턴스를 연결하여 완전한 데이터 처리 워크플로를 형성합니다. 일반적(generic)이며, to_transition 및 to_output 변환기에 의해 처리되는 사용자 정의 입력 및 출력 유형을 허용합니다.

from_config

< >

( config: dict[str, Any]state_dict: dict[str, dict[str, torch.Tensor]] | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None )

매개변수

  • config — 저장된 프로세서 JSON과 동일한 구조를 가진 설정 사전입니다.
  • state_dict — 접미사가 없는 상태 키별로 그룹화된 선택적 인메모리 파이프라인 상태
  • overrides — 레지스트리 이름 또는 클래스 이름으로 키를 지정하는 선택적 생성자 오버라이드입니다.
  • to_transition — 입력 데이터를 EnvTransition으로 변환하는 선택적 변환기입니다.
  • to_output — EnvTransition에서 출력 데이터로 변환하는 선택적 변환기.

메모리 내 구성과 선택적 상태 텐서를 사용하여 파이프라인을 빌드합니다.

from_pretrained

< >

( pretrained_model_name_or_path: str | Pathconfig_filename: strforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict[str, str] | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None**kwargs )

매개변수

  • pretrained_model_name_or_path — Hugging Face Hub의 저장소 식별자, 로컬 디렉터리의 경로, 또는 단일 config 파일의 경로입니다.
  • config_filename — 파이프라인의 JSON 구성 파일 이름. 여러 구성 파일(예: preprocessor와 postprocessor)이 존재할 때 모호성을 방지하기 위해 항상 필요합니다.
  • force_download — 파일을 (재)다운로드할 것을 강제할지 여부.
  • resume_download — 이전에 중단된 다운로드를 재개할지 여부.
  • proxies — 사용할 프록시 서버의 사전입니다.
  • token — 비공개 Hub 저장소에 대한 HTTP bearer 인증으로 사용할 토큰.
  • cache_dir — 다운로드한 파일을 저장할 특정 캐시 폴더의 경로.
  • local_files_only — True인 경우, Hub에서 파일을 다운로드하지 않습니다.
  • revision — 사용할 특정 모델 버전(예: 브랜치 이름, 태그 이름, 커밋 ID).
  • overrides — 특정 단계의 구성을 재정의할 딕셔너리. 키는 해당 단계의 클래스 이름 또는 레지스트리 이름과 일치해야 합니다.
  • to_transition — 입력 데이터를 EnvTransition으로 변환하는 사용자 정의 함수.
  • to_output — 최종 EnvTransition을 출력 형식으로 변환하는 사용자 정의 함수.
  • **kwargs — 추가 인자(사용되지 않음).

다음 예외를 발생시킵니다

FileNotFoundError 또는 ValueError 또는 ImportError 또는 KeyError 또는 ProcessorMigrationError

  • FileNotFoundError — 설정 파일을 찾을 수 없는 경우.
  • ValueError — 구성이 모호하거나 인스턴스화가 실패한 경우.
  • ImportError — 단계의 클래스를 가져올 수 없는 경우.
  • KeyError — 파이프라인의 어떤 단계에도 일치하는 오버라이드 키가 없는 경우.
  • ProcessorMigrationError — 모델이 프로세서 형식으로 마이그레이션해야 하는 경우.

로컬 디렉터리, 단일 파일 또는 Hugging Face Hub 저장소에서 파이프라인을 로드합니다.

이 메서드는 지능형 마이그레이션 감지를 갖춘 단순화된 로딩 파이프라인을 구현합니다:

간소화된 로딩 전략:

  1. 설정 로드 (_load_config):

    • 디렉터리: 디렉터리에서 지정된 config_filename을 로드
    • 단일 파일: 파일을 직접 로드합니다 (config_filename 무시)
    • Hub 저장소: Hub에서 지정된 config_filename을 다운로드

  2. 설정 검증 (_validate_loaded_config):

    • Format validation: config이 유효한 프로세서 형식인지 확인
    • 마이그레이션 감지: 기존 LeRobot 모델 마이그레이션을 위한 사용자 가이드
    • 오류 명확화: 실행 가능한 오류 메시지 제공

  3. 단계 구성 (_build_steps_with_overrides):

    • 클래스 해석: 레지스트리 조회 또는 동적 가져오기
    • 오버라이드 병합: 사용자 매개변수가 저장된 구성을 오버라이드합니다
    • 상태 로드: 상태가 있는 단계에 대해 .safetensors 파일을 로드합니다

  4. 오버라이드 검증 (_validate_overrides_used):

    • 모든 사용자 오버라이드가 적용되었는지 확인합니다(오타 방지)
    • 사용 가능한 키를 포함하여 유용한 오류 메시지를 제공합니다

마이그레이션 감지:

  • 스마트 감지: JSON 파일을 분석하여 오래된 LeRobot 모델을 감지합니다
  • 정밀한 타겟팅: 다른 HuggingFace 모델에 대한 오탐지를 방지합니다
  • 명확한 가이드: 실행할 정확한 마이그레이션 명령을 제공합니다
  • 오류 모드: 명확한 사용자 조치를 위해 항상 ProcessorMigrationError를 발생시킵니다

예제 로드:

# Directory loading
pipeline = DataProcessorPipeline.from_pretrained("/models/my_model", config_filename="processor.json")

# Single file loading
pipeline = DataProcessorPipeline.from_pretrained(
    "/models/my_model/processor.json", config_filename="processor.json"
)

# Hub loading
pipeline = DataProcessorPipeline.from_pretrained("user/repo", config_filename="processor.json")

# Multiple configs (preprocessor/postprocessor)
preprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_preprocessor.json"
)
postprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_postprocessor.json"
)

오버라이드 시스템:

  • 주요 매칭: 레지스트리 이름 또는 클래스 이름을 오버라이드 키로 사용
  • 설정 병합: 사용자 오버라이드가 저장된 설정보다 우선합니다
  • 검증: 모든 오버라이드 키가 실제 단계와 일치하는지 확인합니다(오타 방지)
  • 예시: overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

< >

( )

JSON 직렬화 가능한 파이프라인 구성을 반환합니다.

load_state_dict

< >

( state_dict: dict[str, dict[str, torch.Tensor]] )

매개변수

  • state_dict — 접미사가 없는 상태 키를 단계 상태 사전으로 매핑하는 사전입니다.

다음 예외를 발생시킵니다

KeyError

  • KeyError — 로딩 과정에서 기대하는 상태가 누락되었거나 예상하지 못한 추가 상태가 발견된 경우.

pipeline 상태 텐서를 기존 단계에 로드합니다.

process_action

< >

( action: PolicyAction | RobotAction | EnvAction )

매개변수

  • action — 액션 데이터.

파이프라인을 통해 트랜지션의 action 부분만 처리합니다.

process_complementary_data

< >

( complementary_data: dict[str, Any] )

매개변수

  • complementary_data — 보완 데이터 사전.

파이프라인을 통해 전환의 보완 데이터 부분만 처리합니다.

process_done

< >

( done: bool | torch.Tensor )

매개변수

  • done — done 플래그.

파이프라인을 통해 트랜지션의 done 플래그만 처리합니다.

process_info

< >

( info: dict[str, Any] )

매개변수

  • info — 정보 사전.

파이프라인을 통해 트랜지션의 info 사전만 처리합니다.

process_observation

< >

( observation: RobotObservation )

매개변수

  • observation — 관찰 딕셔너리.

트랜지션의 관찰(observation) 부분만 파이프라인을 통해 처리합니다.

process_reward

< >

( reward: float | torch.Tensor )

매개변수

  • reward — 보상 값.

파이프라인을 통해 트랜지션의 보상 부분만 처리합니다.

process_truncated

< >

( truncated: bool | torch.Tensor )

매개변수

  • truncated — truncated 플래그.

파이프라인을 통해 트랜지션의 truncated 플래그만 처리합니다.

register_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

매개변수

  • fn — 스텝 인덱스와 현재 트랜지션을 인수로 받는 콜러블(callable)입니다.

각 단계 이후에 호출될 함수를 등록합니다.

register_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

매개변수

  • fn — 스텝 인덱스와 현재 트랜지션을 인수로 받는 콜러블(callable)입니다.

각 단계 전에 호출될 함수를 등록합니다.

초기화

< >

( )

파이프라인의 모든 상태ful 단계의 상태를 초기화합니다.

save_pretrained

< >

( save_directory: str | Path | None = Nonerepo_id: str | None = Nonepush_to_hub: bool = Falsecard_kwargs: dict[str, Any] | None = Noneconfig_filename: str | None = None**push_to_hub_kwargs )

매개변수

  • save_directory — 파이프라인이 저장될 디렉터리입니다. None인 경우 HF_LEROBOT_HOME/processors/{sanitized_pipeline_name}에 저장합니다.
  • repo_id — Hub의 저장소 ID. push_to_hub=true인 경우에만 사용됩니다.
  • push_to_hub — 객체를 저장한 후 Hugging Face Hub에 푸시할지 여부.
  • card_kwargs — 카드를 커스터마이징하기 위해 카드 템플릿으로 전달되는 추가 인자.
  • config_filename — JSON 구성 파일의 이름입니다. None인 경우, 파이프라인의 name 속성에서 이름이 생성됩니다.
  • **push_to_hub_kwargs — Additional key word arguments passed along to the push_to_hub method.

파이프라인의 구성 및 상태를 디렉터리에 저장합니다.

이 메서드는 파이프라인의 구조(이름 및 단계)를 정의하는 JSON 구성 파일을 생성합니다. 각 상태가 있는(stateful) 단계에 대해, 해당 상태 딕셔너리를 포함하는 .safetensors 파일도 저장합니다.

state_dict

< >

( )

상태 키별로 그룹화된 파이프라인 상태 텐서를 반환합니다.

step_through

< >

( data: TInput )

매개변수

  • data — 입력 데이터.

데이터를 단계별로 처리하여 각 단계의 전이를 반환합니다.

이것은 데이터가 파이프라인을 통과하는 동안 중간 상태를 디버깅하고 검사하는 데 유용한 생성기 메서드입니다.

transform_features

< >

( initial_features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

매개변수

  • initial_features — 초기 특징을 설명하는 사전입니다.

모든 단계의 특징 변환을 순차적으로 적용합니다.

이 메서드는 각 단계의 transform_features 메서드를 통해 특징 설명 사전(feature description dictionary)을 전파하여, 실제 데이터를 처리하지 않고도 파이프라인이 출력 특징 사양(output feature specification)을 정적으로 결정할 수 있게 합니다.

unregister_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

매개변수

  • fn — 이전에 등록된 정확한 함수 객체입니다.

다음 예외를 발생시킵니다

ValueError

  • ValueError — 목록에서 훅을 찾을 수 없는 경우.

‘after_step’ 훅을 등록 해제합니다.

unregister_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

매개변수

  • fn — 이전에 등록된 정확한 함수 객체입니다.

다음 예외를 발생시킵니다

ValueError

  • ValueError — 목록에서 훅을 찾을 수 없는 경우.

‘before_step’ 훅을 등록 해제합니다.

PolicyProcessorPipeline

lerobot.processor.DataProcessorPipeline

( *args**kwargs )

Update on GitHub

←정책 환경→