LeRobot documentation
하위 호환성
하위 호환성
Policy Normalization 마이그레이션 (PR #1452)
중대한 변경 사항: LeRobot 정책에는 더 이상 가중치에 내장된 정규화 레이어가 없습니다. 정규화는 이제 외부 PolicyProcessorPipeline 구성 요소에서 처리됩니다.
무엇이 변경되었나요?
| PR #1452 이전 | PR #1452 이후 | |
|---|---|---|
| 정규화 위치 | 모델 가중치에 내장됨(normalize_inputs.*) | 외부 PolicyProcessorPipeline 구성 요소 |
| 모델 상태 딕트 | 정규화 통계를 포함합니다 | 가중치만 정리 - 정규화 매개변수 없음 |
| 사용법 | policy(batch)이 모든 것을 처리합니다 | preprocessor(batch) → policy(...) → postprocessor(...) |
기존 모델에 대한 영향
- PR #1452 이전에 학습된 모델은 가중치에 정규화가 내장되어 있습니다
- 이 모델들은 새로운
PolicyProcessorPipeline시스템과 함께 작동하려면 마이그레이션이 필요합니다 - 마이그레이션은 정규화 통계를 추출하고 별도의 프로세서 파이프라인을 생성합니다
구형 모델 마이그레이션
이내장된 정규화를 가진 모델을 변환하려면 마이그레이션 스크립트를 사용하세요:
python src/lerobot/processor/migrate_policy_normalization.py \
--pretrained-path lerobot/act_aloha_sim_transfer_cube_human \
--push-to-hub \
--branch migrated스크립트:
- Extracts가 모델 가중치에서 정규화 통계를 추출합니다
- 생성 외부 preprocessor 및 postprocessor 파이프라인
- 모델 가중치에서 정규화 레이어 제거
- Saves는 깨끗한 모델 + 프로세서 파이프라인
- Hub에 Pushes를 자동 PR 생성과 함께 수행
마이그레이션된 모델 사용
# New usage pattern (after migration)
from lerobot.policies import make_policy, make_pre_post_processors
# Load model and processors separately
policy = make_policy(config, ds_meta=dataset.meta)
preprocessor, postprocessor = make_pre_post_processors(
policy_cfg=config,
dataset_stats=dataset.meta.stats
)
# Process data through pipeline
processed_batch = preprocessor(raw_batch)
action = policy.select_action(processed_batch)
final_action = postprocessor(action)하드웨어 API 재설계
PR #777은 LeRobot 보정을 개선하지만 하위 호환성이 없습니다. 아래는 변경 사항 개요와 이 pull request 이전에 생성된 데이터셋을 계속 다루는 방법에 대한 설명입니다.
무엇이 변경되었나요?
| PR #777 이전 | PR #777 이후 | |
|---|---|---|
| 공통 범위 | 도 -180...180° | 정규화된 범위 관절: –100...100 그립퍼: 0...100 |
| 제로 포지션 (SO100 / SO101) | 팔을 수평으로 완전히 뻗기 | 각 관절의 범위 중간 |
| 경계 처리 | ±180° 래핑을 감지하기 위한 소프트웨어 안전장치 | 중간 범위 제로로 인해 래핑 어라운드 로직이 필요하지 않습니다 |
기존 데이터셋에 미치는 영향
- PR #777 이전에 생성된 기록된 궤적은 직접 로드하면 올바르게 재생되지 않습니다:
- 관절 각도가 오프셋되어 있고 정규화가 잘못되었습니다.
- 기존 데이터로 직접 파인튜닝되거나 학습된 모든 모델은 입력과 출력을 변환해야 합니다.
이전 캘리브레이션 시스템으로 만든 데이터셋 사용
이전 캘리브레이션으로 기록된 에피소드를 재생하기 위한 마이그레이션 예제 스크립트를 여기에 제공합니다: examples/backward_compatibility/replay.py.
아래에서는 이전 캘리브레이션 데이터셋이 작동하도록 예제 스크립트에서 수행되는 수정 사항을 안내합니다.
+ key = f"{name.removeprefix('main_')}.pos"
action[key] = action_array[i].item()
+ action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)
+ action["elbow_flex.pos"] -= 90이 내용을 단계별로 살펴보겠습니다.
새로운 코드베이스는 위치 관측값에 .pos 접미사를 사용하며, main_ 접두사는 제거되었습니다:
key = f"{name.removeprefix('main_')}.pos""shoulder_lift" (id = 2)의 경우, 0 위치가 이전 캘리브레이션/코드와 비교하여 -90도 변경되고 방향이 반대로 설정됩니다.
action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)"elbow_flex"(id = 3)의 경우, 0 위치가 이전 캘리브레이션/코드와 비교하여 -90도 변경됩니다.
action["elbow_flex.pos"] -= 90degrees 정규화를 사용하려면 --robot.use_degrees 옵션을 true(으)로 설정합니다.
python examples/backward_compatibility/replay.py \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem5A460814411 \
--robot.id=blue \
+ --robot.use_degrees=true \
--dataset.repo_id=my_dataset_id \
--dataset.episode=0이전 보정 시스템으로 학습된 정책을 사용하는 경우
Policies는 데이터셋과 동일한 형식(torch.Tensors)으로 동작을 출력합니다. 따라서 동일한 변환을 적용해야 합니다.
이러한 변환을 찾기 위해, 위 섹션을 사용하여 정책이 학습된 데이터셋의 에피소드를 먼저 재생하는 것을 권장합니다.
그 후, 추론 스크립트에 동일한 변환을 추가하세요(여기서는 examples/의 evaluate.py 예시처럼 predict_action를 호출하는 스크립트를 기준으로 설명합니다):
action_values = predict_action(
observation_frame,
policy,
get_safe_torch_device(policy.config.device),
preprocessor,
postprocessor,
policy.config.use_amp,
task=single_task,
robot_type=robot.robot_type,
)
action = {key: action_values[i].item() for i, key in enumerate(robot.action_features)}
+ action["shoulder_lift.pos"] = -(action["shoulder_lift.pos"] - 90)
+ action["elbow_flex.pos"] -= 90
robot.send_action(action)질문이 있거나 마이그레이션 문제를 겪는 경우, Discord에서 자유롭게 질문해 주세요.
Update on GitHub