Strands 로봇과 LeRobot 스트리밍 데이터 루프를 Hugging Face 저장 버킷과 함께 사용하기

요약

Hugging Face는 Strands 로봇, LeRobot 데이터셋 스택, Hugging Face 저장 버킷을 연결하는 워크플로우를 발표했습니다. 이를 통해 로봇의 시연을 기록하고, 효율적으로 동기화하며, Hub에서 직접 데이터를 스트리밍하여 훈련하고, 동일한 로봇에 정책을 재배포하는 단일 루프를 완성할 수 있습니다.

루프의 동작 방식

이 루프는 하나의 Robot() 인스턴스를 공유하는 네 단계로 구성됩니다:

  1. 기록 – 로봇(시뮬레이션 또는 하드웨어)이 LeRobotDataset를 기록합니다.
  2. 저장 – 데이터셋이 Hugging Face 저장 버킷으로 동기화되며, 바이트 수준에서 중복 업로드를 제거합니다.
  3. 훈련 – 데이터셋이 LeRobot의 StreamingLeRobotDataset를 사용해 버킷에서 GPU로 직접 스트리밍되며, 전체 다운로드가 필요하지 않습니다.
  4. 배포 – 훈련된 체크포인트가 동일한 Robot()로 다시 로드되며, 이제 mode="real"로 설정되어 다음 시연 세트를 기록함으로써 루프를 완성합니다.

각 단계는 단일 함수 호출 또는 몇 줄의 코드로 이루어져 있어, 노트북이나 GPU 클러스터에서 전체 파이프라인을 실행할 수 있습니다.

사전 요구 사항

최소한의(시뮬레이션) 설정

  • Linux 또는 macOS에서 Python 3.12 이상 (Apple Silicon 지원).
  • Strands 호환 LLM 제공자 (Amazon Bedrock, Anthropic, OpenAI 또는 로컬 Ollama).
  • lerobot 추가 기능이 포함된 Strands 로봇:
    uv pip install -U "strands-robots[sim-mujoco,lerobot]>=0.5.1"
    이 명령어는 LeRobot ≥ 0.6.1, datasets, av, torchcodec를 설치합니다.

고급 설정(버킷, 하드웨어, 실제 정책)

  • 쓰기 권한이 있는 토큰이 있는 Hugging Face 계정과 hf CLI (pip install "huggingface-hub>=1.6.0,<2.0.0").
  • 보정 파일이 ~/.cache/huggingface/lerobot/calibration/에 있는 물리적 로봇 (예: SO-101).
  • 훈련을 위한 NVIDIA GPU (또는 대규모 데이터셋에 대한 GPU 클러스터).
  • 트레이너용 lerobot[training] 추가 기능 (uv pip install "lerobot[training]").

단계 1 – 버킷에 시연 기록하기

로봇은 자체 디스크 형식(상태/행동은 Parquet, 비디오는 MP4)으로 LeRobotDataset를 기록합니다. 에피소드가 끝나면 데이터셋이 저장 버킷으로 동기화됩니다:

from strands import Agent
from strands_robots import Robot, sync_dataset_to_bucket

sim = Robot("so100")  # 기본 mode="sim"
agent = Agent(tools=[sim])

# 프롬프트가 세계 생성, 기록, 가짜 정책 실행을 유도합니다.
agent(
    "so100 로봇이 있는 세계를 생성하고, 빨간 큐브와 전면 카메라를 추가하고, 
    기록을 시작합니다 (repo_id='local/cube_pick', root='/tmp/cube_pick', fps=30, 
    overwrite=True, task='빨간 큐브 들어 올리기'), 60단계 동안 가짜 정책을 실행한 후 기록을 중지합니다."
)

# 완료된 데이터셋을 버킷으로 동기화합니다.
sync_dataset_to_bucket("/tmp/cube_pick", "my-org/robot-fave")
# → {"status": "success", "bucket_uri": "hf://buckets/my-org/robot-fave/cube_pick"}

동기화는 hf://buckets/{bucket}/{run_id}에 쓰이며, run_id는 기본적으로 데이터셋 폴더 이름입니다. 동일한 호출은 lerobot-record CLI를 통해 물리적 SO-101에서 기록한 데이터에도 적용됩니다.

단계 2 – 바이트 수준 중복 제거로 저장하기

저장 버킷은 Xet으로 구동되며, 콘텐츠 기반 청크화와 바이트 수준 중복 제거를 수행합니다. LeRobot은 데이터를 100MB Parquet 파일과 200MB MP4 파일로 청크화하므로, 하루 동기화 시 새로 생성된 청크와 부분 채워진 청크만 업로드됩니다. Hugging Face에서 인용한 벤치마크에 따르면, 단순 오버라이트 대비 전송된 바이트 수가 4배 감소합니다.

단계 3 – Hub에서 스트리밍하여 훈련하기

전체 데이터셋을 로컬 디스크에 복사하는 대신, stream_dataset()는 바이트 범위 요청을 사용해 버킷에서 직접 읽습니다:

reader = sim.stream_dataset(
    "my-org/robot-fave/cube_pick",
    repo_type="bucket",
    shuffle=False,
    max_num_shards=1,
    buffer_size=1,
)

print(reader.num_episodes, reader.num_frames, reader.fps)
for frame in reader:
    # 관측 텐서는 원격 MP4 청크에서 실시간으로 디코딩됩니다.
    img = frame["observation.images.front"]
    state = frame["observation.state"]
    action = frame["action"]
    break

작은 meta/ 폴더만 로컬에 캐시되며, 비디오 프레임은 필요할 때마다 디코딩됩니다. 훈련을 위해 DataLoader로 리더를 감싸면 됩니다:

for batch in reader.dataloader(batch_size=64, num_workers=4):
    loss, _ = policy(batch)
    loss.backward()

LeRobot의 CLI도 직접 스트리밍을 지원합니다:

lerobot-train \
  --policy.type=act \
  --dataset.repo_id=my-org/robot-fave/cube_pick \
  --dataset.repo_type=bucket \
  --dataset.streaming=true \
  --num_workers=4

단일 NVIDIA L4 인스턴스는 120프레임 에피소드에 대해 500개의 최적화 단계를 133초 만에 완료했으며, create_policy()로 로드할 수 있는 체크포인트를 생성했습니다.

단계 4 – 정책 배포 및 루프로 데이터 반환하기

새로 훈련된 체크포인트를 물리적 로봇에 배포하려면 Robot 모드를 real로 전환합니다:

robot = Robot(
    "so100",
    mode="real",
    port="/dev/ttyACM0",
    cameras={"front": {"type": "opencv", "index_or_path": "/dev/video0", "fps": 30}},
)
agent = Agent(tools=[robot])
agent("빨간 큐브 들어 올리기.")

로봇은 동일한 LeRobot 형식으로 실행을 기록하며, 다음 훈련 반복을 위해 버킷으로 다시 동기화할 수 있습니다.

샘플 애플리케이션

완전한 노트북은 examples/notebooks/05_streaming_data_loop.ipynb에 제공됩니다. 이 노트북은 가짜 정책과 함께 시뮬레이션에서 전체 루프를 실행하며, GPU나 Hugging Face 자격 증명이 필요하지 않습니다. 로컬에서 시도하려면:

git clone https://github.com/strands-labs/robots.git
cd robots
uv pip install -U "strands-robots[sim-mujoco,lerobot]>=0.5.1"
jupyter notebook examples/notebooks/05_streaming_data_loop.ipynb

BUCKET = "my-org/robot-fave"로 설정하고, 선택적으로 RUN_ID를 지정하여 데이터가 저장될 위치를 제어할 수 있습니다.

보안 고려 사항

  1. 프롬프트 삽입 – 에이전트는 LLM 생성 프롬프트를 실행합니다. 도구를 제한하고 신뢰할 수 있는 입력만 제공하세요.
  2. 훈련 데이터 신뢰 경계 – 데이터 수집(쓰기)과 훈련(읽기)에 별도의 자격 증명을 사용하세요. 에피소드를 추적하기 위해 고유한 run_id를 사용하세요.
  3. 버킷 토큰 범위 – 대상 네임스페이스에 한정된 토큰을 사용하고, 수집 데이터에는 개인 버킷을 우선 고려하세요.
  4. 버킷에 리비전 기록 없음 – 오버라이트는 이전 런을 대체합니다. 감사 가능성을 위해 검토된 버전은 일반 Hub 데이터셋에 게시하세요.
  5. 신뢰할 수 있는 모델 로딩 – 사용자 정의 정책을 위해 trust_remote_code=True가 필요합니다. 신뢰할 수 있는 조직에서만 체크포인트를 로드하고, 가능하면 safetensors를 사용하세요.

정리

저장 비용을 방지하기 위해 버킷 내용과 임시 파일을 제거하세요:

hf buckets rm my-org/robot-fave/cube_pick/ --recursive --dry-run   # 미리 보기
hf buckets rm my-org/robot-fave/cube_pick/ --recursive           # 삭제
hf buckets delete my-org/robot-fave                               # 전체 버킷 삭제
rm -rf /tmp/cube_pick /tmp/cube_pick_ft /tmp/nb5_dataset /tmp/nb5_ft

push_to_hub()로 생성된 버전화된 저장소는 영향을 받지 않습니다.

다음 단계

  • 로봇 카탈로그, 시뮬레이션 백엔드, 다중 로봇 메시에 대해 Strands 로봇 문서 탐색하기.
  • TrainSpec의 provider 문자열을 변경하여 다른 정책 제공자(GR00T, Cosmos 3, SmolVLA 등) 사용하기.
  • 펌 fleet 확장: 각 로봇에 고유한 run_id를 부여하고, 동일한 버킷에 동시에 쓰기 가능하게 하기.
  • Amazon S3와 같은 외부 저장소와 결합하기. LeRobot 형식은 저장소에 독립적이며, 버킷 스트리밍은 추가 연결 없이 Hub 내부 경로를 제공합니다.

자료

Strands 로봇

LeRobot 및 Hub

정책

배경 지식

Sources

관련