# 프로세서

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

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

## ProcessorStep[[lerobot.processor.ProcessorStep]]

#### lerobot.processor.ProcessorStep[[lerobot.processor.ProcessorStep]]

```python
lerobot.processor.ProcessorStep()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L150)

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

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

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

#### get_config[[lerobot.processor.ProcessorStep.get_config]]

```python
get_config()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L193)

**반환값:**

JSON 직렬화 가능한 구성 매개변수 사전.

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

#### load_state_dict[[lerobot.processor.ProcessorStep.load_state_dict]]

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

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L209)

**매개변수:**

state : 상태 텐서 사전.

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

#### 초기화[[lerobot.processor.ProcessorStep.reset]]

```python
reset()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L221)

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

#### save_artifacts[[lerobot.processor.ProcessorStep.save_artifacts]]

```python
save_artifacts(save_directory: Path)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L217)

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

#### state_dict[[lerobot.processor.ProcessorStep.state_dict]]

```python
state_dict()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L201)

**반환값:**

상태 이름과 텐서를 매핑하는 사전입니다.

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

#### transform_features[[lerobot.processor.ProcessorStep.transform_features]]

```python
transform_features(features: dict[PipelineFeatureType, dict[str, PolicyFeature]])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L225)

**매개변수:**

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

**반환값:**

이 단계의 변환 이후 출력 특징을 설명하는 사전입니다.

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

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

## DataProcessorPipeline[[lerobot.processor.DataProcessorPipeline]]

#### lerobot.processor.DataProcessorPipeline[[lerobot.processor.DataProcessorPipeline]]

```python
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>)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L273)

**매개변수:**

steps : 파이프라인을 구성하는 `ProcessorStep` 객체의 시퀀스입니다.

name : 파이프라인에 대한 설명적인 이름.

to_transition : 원시 입력 데이터를 표준화된 `EnvTransition` 형식으로 변환하는 함수입니다.

to_output : 최종 `EnvTransition`을 원하는 출력 형식으로 변환하는 함수입니다.

before_step_hooks : 각 단계가 실행되기 전에 호출될 함수 목록.

after_step_hooks : 각 단계가 실행된 후 호출될 함수 목록.

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

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

#### from_config[[lerobot.processor.DataProcessorPipeline.from_config]]

```python
from_config(config: dict[str, Any], state_dict: dict[str, dict[str, torch.Tensor]] | None = None, overrides: dict[str, Any] | None = None, to_transition: Callable[[TInput], EnvTransition] | None = None, to_output: Callable[[EnvTransition], TOutput] | None = None)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L792)

**매개변수:**

config : 저장된 프로세서 JSON과 동일한 구조를 가진 설정 사전입니다.

state_dict : 접미사가 없는 상태 키로 그룹화된 선택적 인메모리 파이프라인 상태.

overrides : 레지스트리 이름 또는 클래스 이름으로 구분되는 선택적 생성자 오버라이드.

to_transition : 입력 데이터를 `EnvTransition`으로 변환하는 선택적 변환기입니다.

to_output : `EnvTransition`에서 출력 데이터로 변환하는 선택적 변환기.

**반환값:**

config와 선택적 state로 구성된 프로세서 파이프라인입니다.

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

#### from_pretrained[[lerobot.processor.DataProcessorPipeline.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | Path, config_filename: str, force_download: bool = False, resume_download: bool | None = None, proxies: dict[str, str] | None = None, token: str | bool | None = None, cache_dir: str | Path | None = None, local_files_only: bool = False, revision: str | None = None, overrides: dict[str, Any] | None = None, to_transition: Callable[[TInput], EnvTransition] | None = None, to_output: Callable[[EnvTransition], TOutput] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L647)

**매개변수:**

pretrained_model_name_or_path : Hugging Face Hub의 저장소 식별자, 로컬 디렉터리의 경로, 또는 단일 config 파일의 경로.

config_filename : 파이프라인의 JSON 구성 파일 이름. 여러 구성(예: preprocessor와 postprocessor)이 존재할 때 모호성을 방지하기 위해 항상 필요합니다.

force_download : 파일을 (재)다운로드하도록 강제할지 여부.

resume_download : 하위 호환성을 위해 유지되며 무시됩니다. 다운로드가 자동으로 재개됩니다.

proxies : 하위 호환성을 위해 유지되며 무시됩니다. 대신 HTTP_PROXY와 HTTPS_PROXY를 사용하세요.

token : 비공개 Hub 저장소에 대한 HTTP bearer 인증에 사용할 토큰.

cache_dir : 다운로드한 파일을 저장할 특정 캐시 폴더의 경로.

local_files_only : True인 경우, Hub에서 파일을 다운로드하지 않습니다.

revision : 사용할 특정 모델 버전(예: 브랜치 이름, 태그 이름 또는 커밋 ID).

overrides : 특정 단계의 구성을 재정의하기 위한 사전. 키는 해당 단계의 클래스 이름 또는 레지스트리 이름과 일치해야 합니다.

to_transition : 입력 데이터를 `EnvTransition`으로 변환하는 사용자 정의 함수입니다.

to_output : 최종 `EnvTransition`을 출력 형식으로 변환하는 사용자 정의 함수입니다.

- ****kwargs** : 추가 인자(사용되지 않음).

**반환값:**

지정된 구성과 상태로 로드된 `DataProcessorPipeline` 인스턴스.

**예외:** ``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를 발생시킵니다

**예제 로드**:
```python
# 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[[lerobot.processor.DataProcessorPipeline.get_config]]

```python
get_config()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L451)

**반환값:**

`save_pretrained()`가 JSON으로 작성하는 것과 동일한 내용을 가진 딕셔너리.

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

#### load_state_dict[[lerobot.processor.DataProcessorPipeline.load_state_dict]]

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

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L515)

**매개변수:**

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

**예외:** ``KeyError``

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

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

#### process_action[[lerobot.processor.DataProcessorPipeline.process_action]]

```python
process_action(action: PolicyAction | RobotAction | EnvAction)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1786)

**매개변수:**

action : 액션 데이터.

**반환값:**

처리된 액션.

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

#### process_complementary_data[[lerobot.processor.DataProcessorPipeline.process_complementary_data]]

```python
process_complementary_data(complementary_data: dict[str, Any])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1853)

**매개변수:**

complementary_data : 보완 데이터 사전.

**반환값:**

처리된 보완 데이터 딕셔너리.

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

#### process_done[[lerobot.processor.DataProcessorPipeline.process_done]]

```python
process_done(done: bool | torch.Tensor)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1814)

**매개변수:**

done : 완료 플래그.

**반환값:**

처리된 완료 플래그.

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

#### process_info[[lerobot.processor.DataProcessorPipeline.process_info]]

```python
process_info(info: dict[str, Any])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1840)

**매개변수:**

info : 정보 사전.

**반환값:**

처리된 정보 사전.

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

#### process_observation[[lerobot.processor.DataProcessorPipeline.process_observation]]

```python
process_observation(observation: RobotObservation)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1773)

**매개변수:**

observation : 관찰 딕셔너리.

**반환값:**

처리된 관찰 딕셔너리.

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

#### process_reward[[lerobot.processor.DataProcessorPipeline.process_reward]]

```python
process_reward(reward: float | torch.Tensor)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1801)

**매개변수:**

reward : 보상 값.

**반환값:**

처리된 보상.

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

#### process_truncated[[lerobot.processor.DataProcessorPipeline.process_truncated]]

```python
process_truncated(truncated: bool | torch.Tensor)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1827)

**매개변수:**

truncated : 잘림 플래그.

**반환값:**

처리된 잘림 플래그.

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

#### register_after_step_hook[[lerobot.processor.DataProcessorPipeline.register_after_step_hook]]

```python
register_after_step_hook(fn: Callable[[int, EnvTransition], None])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1697)

**매개변수:**

fn : 단계 인덱스와 현재 전환을 받는 콜러블(callable)입니다.

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

#### register_before_step_hook[[lerobot.processor.DataProcessorPipeline.register_before_step_hook]]

```python
register_before_step_hook(fn: Callable[[int, EnvTransition], None])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1673)

**매개변수:**

fn : 단계 인덱스와 현재 전환을 받는 콜러블(callable)입니다.

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

#### 초기화[[lerobot.processor.DataProcessorPipeline.reset]]

```python
reset()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1721)

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

#### save_pretrained[[lerobot.processor.DataProcessorPipeline.save_pretrained]]

```python
save_pretrained(save_directory: str | Path | None = None, repo_id: str | None = None, push_to_hub: bool = False, card_kwargs: dict[str, Any] | None = None, config_filename: str | None = None, **push_to_hub_kwargs)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L595)

**매개변수:**

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[[lerobot.processor.DataProcessorPipeline.state_dict]]

```python
state_dict()
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L488)

**반환값:**

접미사가 없는 상태 키를 복제된 스텝 상태 사전으로 매핑하는 사전입니다.

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

#### step_through[[lerobot.processor.DataProcessorPipeline.step_through]]

```python
step_through(data: TInput)
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L343)

**매개변수:**

data : 입력 데이터.

**반환 값:**

초기 상태부터 각 처리 단계 이후까지의 `EnvTransition` 객체.

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

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

#### transform_features[[lerobot.processor.DataProcessorPipeline.transform_features]]

```python
transform_features(initial_features: dict[PipelineFeatureType, dict[str, PolicyFeature]])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1750)

**매개변수:**

initial_features : 초기 특징을 설명하는 사전.

**반환값:**

모든 변환 이후의 최종 기능 설명입니다.

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

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

#### unregister_after_step_hook[[lerobot.processor.DataProcessorPipeline.unregister_after_step_hook]]

```python
unregister_after_step_hook(fn: Callable[[int, EnvTransition], None])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1705)

**매개변수:**

fn : 이전에 등록되었던 정확한 함수 객체입니다.

**예외:** ``ValueError``

- ``ValueError`` -- 목록에서 훅을 찾을 수 없는 경우.

'after_step' 후크를 등록 해제합니다.

#### unregister_before_step_hook[[lerobot.processor.DataProcessorPipeline.unregister_before_step_hook]]

```python
unregister_before_step_hook(fn: Callable[[int, EnvTransition], None])
```

[소스](https://github.com/huggingface/lerobot/blob/v0.7.0/src/lerobot/processor/pipeline.py#L1681)

**매개변수:**

fn : 이전에 등록되었던 정확한 함수 객체입니다.

**예외:** ``ValueError``

- ``ValueError`` -- 목록에서 훅을 찾을 수 없는 경우.

'before_step' 훅을 등록 해제합니다.

## PolicyProcessorPipeline[[lerobot.processor.DataProcessorPipeline]]

#### lerobot.processor.DataProcessorPipeline[[lerobot.processor.DataProcessorPipeline]]

```python
lerobot.processor.DataProcessorPipeline(*args, **kwargs)
```