HFlow: 로보틱스 및 물리적 AI를 위한 확장 가능한 멀티모달 데이터 파이프라인의 오픈 소스 SDK

Hebbian Robotics (YC S26)은 로보틱스 및 물리적 AI를 위한 확장 가능한 멀티모달 데이터 파이프라인 오픈 소스 SDK인 HFlow를 구축하고 있습니다. 이 도구는 대규모 로보틱스 팀 내부에서 일반적으로 개발되는 데이터 툴링과 관행을 모든 규모의 팀에 접근 가능하게 만듭니다.

저희는 데이터를 처리하는 것이 로보틱스의 주요 병목 현상이라고 믿습니다. 코퍼스(corpus)는 여러 녹화 시스템으로부터 비디오, 상태(state), 동작(actions), 타임스탬프, 메타데이터를 결합할 수 있습니다. 팀들은 종종 품질 관리에서 문제를 가장 먼저 느낍니다. 즉, 카메라가 멈췄는지, 스트림이 동기화에서 벗어났는지, 필요한 토픽(topics)이 사라졌는지, 또는 중복 녹화가 코퍼스에 들어왔는지를 판단하는 것입니다. 코퍼스가 커질수록 파편화된 스크립트 때문에 무엇이 실행되었는지 알거나, 결과를 감사하거나, 데이터셋을 재현하기 어렵게 됩니다.

사용자는 HFlow의 내장 검사(built-in checks)를 사용하거나, 새로운 변환(transformations), 검사, 레이블링 및 풍부화 기능을 작성할 수 있으며, 이미 사용 중인 처리 코드를 연결할 수도 있습니다. HFlow는 이러한 단계 전반에 걸쳐 오케스트레이션(orchestration), 스토리지, 버전 관리 및 큐레이션을 담당합니다.

HFlow는 처리된 모든 에피소드에 그 출처(provenance)를 기록하고, 파이프라인을 그래프로 렌더링하며, 메타데이터와 품질 증거를 조회 가능한 카탈로그에 저장합니다. 이를 통해 출력물이 어떻게 생성되었는지 추적하고, 모든 단계를 모니터링하며, 기반 녹화 파일(underlying recordings)을 로드하지 않고도 코퍼스(corpus)를 조사할 수 있습니다.

MCAP은 HFlow의 v1 입력 및 출력 경계(boundary)인데, 이는 동기화된 비디오, 상태(state), 행동(action) 및 기타 시계열 스트림을 효율적으로 저장하고 제공하기 때문입니다. 이 형식 요구사항이 데이터가 어디에서 오는지 정의하는 것은 아닙니다. 인간 착용 카메라, 원격 조작 로봇, 자율 정책 및 기타 수집 시스템 모두 데이터가 지원되는 MCAP 에피소드로 표현되면 파이프라인에 데이터를 공급할 수 있습니다.

상태: pre-v1이며, 핵심 라이프사이클은 종단 간(end to end)으로 작동합니다. HFlow는 로컬에서 사용해 볼 준비가 되어 있습니다. 현재 세부 정보 및 남은 작업은 구현된 내용과 오픈 이슈를 참조하십시오.

개방형 로보틱스 커뮤니티 성장에 기여하세요. 저장소 스타(Star the repository), 네트워크에 공유하거나, 기여해 주세요. 우리의 목표는 누구나 로보틱스의 미래를 구축하는 데 참여할 수 있는 오픈 소스 커뮤니티입니다. 기여하기 위해 로봇 하드웨어는 필요하지 않습니다.

무엇을 얻게 되나요

인간 및 로봇 데이터는 네 단계의 라이프사이클을 거쳐 이동합니다:

collection --> ingestion ---------------> curation ------> delivery
(landing (transform -> QC gate -> (SQL over (curated MCAP +
bucket) enrich, as an episode manifest; convert
...

• 사용자 코드는 그대로 유지됩니다. 변환(Transformations), 품질 검사(Quality checks), 레이블링, 그리고 증강(Enrichments)은 사용자 환경 내의 일반 Python 함수입니다. 기존 코드는 독점 프레임워크를 위해 재작성되는 대신 작은 어댑터(adapters)를 통해 플러그인 방식으로 연결됩니다.
• 에피소드는 MCAP 형식이며, 이는 ROS 2가 네이티브로 기록하고 Foxglove 및 Rerun에서 직접 열 수 있는 컨테이너입니다. 이 파일은 인밴드 H.264(in-band H.264)로 작성되었으며, GOP 길이(GOP length)가 데이터 읽기 방식과 일치합니다. 또한 **토픽 그룹 청킹(topic-group chunking)**을 지원하여 (카메라 스트림과 상태 스트림이 절대 하나의 청크를 공유하지 않으므로, 상태 데이터를 읽는 것은 비디오를 건너뛰고 훈련 샘플 하나당 그룹당 한 번의 읽기 비용만 발생합니다).
• 처리된 에피소드는 출처(provenance) 정보를 담고 있습니다. 파일 자체에 해당 파일을 생성한 스키마(schema), 파이프라인, 도구 버전 정보와 사용 가능한 경우 소스 URI가 기록됩니다. 카탈로그 레코드는 측정값과 결과물을 단계별 버전(step versions)에 연결하여, 잘못된 결과가 발생했을 때 그 원점을 추적하기 쉽게 만듭니다.
• 파이프라인은 그래프로 시각화됩니다. HFlow는 Airflow DAG를 렌더링하여 스테이지들이 어떻게 연결되는지 보고 작업 상태, 로그, 재시도(retries), 그리고 재실행(reruns)을 모니터링할 수 있게 합니다.
• 품질 검사는 재사용 가능한 증거를 생성합니다. Accessors는 기존 처리 코드가 예상하는 입력값(numpy 배열, MP4 경로, JPEG 프레임)을 추출하며, 그 결과물은 하드코딩된 판결이 아닌 쿼리 가능한 측정값으로 저장됩니다. 서로 다른 데이터셋에 대해 미디어를 다시 처리하지 않고도 다른 임계값(thresholds)을 적용할 수 있습니다.
• 녹화 파일을 로드하지 않고 코퍼스(corpus)를 쿼리할 수 있습니다. 메타데이터, 품질 측정값, 태그, 버전 스탬프, 그리고 아티팩트 위치는 Parquet 카탈로그에 저장됩니다.

DuckDB(https://duckdb.org/)를 사용하여 기본 MCAP 파일을 열지 않고도 코퍼스 전체에 걸친 질문에 답하고 매니페스트를 생성할 수 있습니다.

첫 실행이 시작되기 전이라도 언제든지 카탈로그에 대한 Open DuckDB 브라우저를 켤 수 있습니다:

hflow catalog ui

호스팅 및 확장성

오픈 소스 배포는 소유하기 쉽도록 구축되었습니다. 포함된 Docker Compose 런타임을 사용하여 단일 테넌트(single-tenant) 워크스페이스를 실행하거나, 이미 운영 중인 Airflow 3 환경에 생성된 DAG 번들을 배포할 수 있습니다. 사용자 계정, RBAC(Role-Based Access Control), 또는 멀티테넌트 제어 평면은 없습니다.

데이터 평면(data plane)은 계정 및 제어 평면의 관심사로부터 분리되어 있어, 동일한 엔진을 외부 제어 평면 뒤에서 여러 개의 격리된 워크스페이스로 확장할 수 있습니다 (예: 팀별 또는 고객별). 이것이 미래에 호스팅될 버전을 위한 의도된 경로이지만, 호스팅 제어 평면은 이 저장소에 구현되어 있지 않으며 v1 출시 약속 사항도 아닙니다.
docs/HOSTING.md에서는 이러한 제어 평면을 추가 기능이 아닌 재구축(rearchitecture)으로 만들기 위한 데이터 평면 계약(data-plane contract)을 문서화합니다: 워크스페이스 단위, 서비스가 구동하는 이음매(seams) (매니페스트, 원격 런타임 주소 지정, 자격 증명 주입), 신뢰 모델, 그리고 현재의 제한 사항입니다.

커뮤니티 및 호스팅 관심사

• 호스팅 플랫폼 대기자 명단: 워크플로우에 대해 알려주세요.
• 커뮤니티 Discord: 질문, 피드백 및 기여 논의를 위해 참여하세요.
• 행동 강령(Code of conduct): 커뮤니티 표준을 검토하고 우려 사항은 비공개로 보고해 주세요.

재현 가능한 버그 및 범위가 지정된 기능 요청에는 GitHub 이슈를 사용하세요.

설치 및 사용해 보기

uv를 사용하여 PyPI에서 SDK를 설치합니다:

uv add hflow

Hebbian Robotics 프로젝트는 버전 0.2.0으로 시작합니다. 동일한 PyPI 이름 하의 이전 0.1.x 릴리스는 이름이 이전되기 전의 관련 없는 비활성 프로젝트에 속했습니다.

리포지토리와 함께 제공되는 빠른 시작(quickstart)을 실행하려면:

git clone https://github.com/Hebbian-Robotics/hflow.git
cd hflow
uv sync --locked
...

이 빠른 시작은 입력 파일이 주어지지 않을 때 카메라 및 상태 스트림을 가진 작은 멀티모달 에피소드를 합성하고, 파이프라인을 인-프로세스(in-process)로 실행하며, 그 출력을 gitignore된 data/ 디렉토리에 작성합니다. Docker나 Airflow가 필요하지 않습니다. 사용자의 녹화 데이터를 사용하려면:

uv run python examples/quickstart.py path/to/episode.mcap

실제 자아중심(egocentric) 영상을 사용하여 권장되는 첫 실행을 하려면 첫 자아중심 에피소드 평가하기를 따르십시오. 이 문서는 HFlow의 로컬 결정론적 품질 기준선(deterministic quality baseline)과 두 개의 호스팅된 의미론적 검사(semantic checks)를 함께 실행합니다. 호스팅 API에 액세스하려면 문의하십시오.

CLI는 uv run hflow --help를 사용하여 확인할 수 있습니다. 동일한 파이프라인을 스케줄링할 준비가 되면 런타임 가이드로 계속하십시오. 개발자 및 기여자들은 CONTRIBUTING.md부터 시작해야 합니다. 자아중심 코퍼스(egocentric-corpus)와 OpenAI 비전 경로를 위해 예제 카탈로그를 찾아보십시오.

LeRobot Dataset v3 에피소드를 동일한 표준 MCAP 경계로 가져오려면:

uv run hflow import lerobot \
  --repo lerobot/pusht --revision main \
  --camera observation.image --episode-index 0 \
...

이 임포터는 main을 불변 소스 커밋(immutable source commit)으로 해석하고 이를 에피소드 출처(episode provenance)로 기록합니다. 지원되는 기능 하위 집합과 멀티 카메라 예제는 LeRobot 가져오기 가이드를 참조하십시오.

어떤 모습인지

코드 6줄로 시작할 수 있습니다. 이 더 완전한 예제는 로봇 원격 조작 에피소드를 사용하지만, 동일한 단계 인터페이스가 자기 중심적 비디오(egocentric video) 및 기타 물리적 AI 녹화에도 적용됩니다.

import asyncio
import hflow
from hflow.asyncio_utils import run_blocking
...

모든 검사(check), 풍부화(enrichment), 그리고 파생 채널은 버전을 선언합니다. HFlow는 그 값을 작성된 그대로 저장합니다: 동작 보존 리팩토링을 위해 유지하고, 오래된 결과와 새로운 결과가 더 이상 비교 가능하다고 간주되어서는 안 될 때만 증가시킵니다.

큐레이션(Curation)은 나중에 hflow.curate(data_root / "catalog", sql, output="manifest.parquet") 또는 명령줄에서 hflow curate "<sql>"을 통해 이루어지며, 어느 쪽이든 매니페스트와 함께 커버리지 분모를 보고합니다:

SELECT episode_id, uri FROM episodes
WHERE task = 'fold_napkin'
  AND status = 'ok'
...

설계 원칙

1. 아키텍처의 민주화, 최적화는 유보. 작은 규모에서 유용한 워크플로우와 표준 인터페이스를 보존하고, 각 프로덕션 규모 메커니즘을 구현됨(implemented), 단순화됨(simplified), 유보됨(deferred), 또는 범위를 벗어남(out of scope)으로 정직하게 라벨링합니다.
2. 판결이 아닌 증거. 검사는 커버리지를 가진 측정값을 기록합니다; 통과/실패 정책은 소비자가 큐레이션 시점에 가집니다. 품질 태그는 에피소드를 라우팅하며, 데이터를 절대 삭제하지 않습니다.
3. 모든 경계에서 표준 형식. MCAP 에피소드, Parquet 카탈로그, Airflow DAGs. 저희 코드는 형식이 브리징(bridging)을 강제하거나 함정이 진정으로 명확하지 않은 경우에만 존재합니다.
4. 당신의 코드는 당신의 코드입니다. 기존 변환(transforms), 검사(checks), 풍부화(enrichments)는 다시 작성되는 대신 작은 어댑터(adapters)를 통해 플러그인됩니다.

요구 사항

• Python ≥ 3.11
• Docker (파이프라인 실행용; app.test()는 필요 없음), 또는 자체 Airflow 배포판 사용 (Astronomer, MWAA, Cloud Composer, 직접 관리)
• 첫 번째 hflow up은 약 2GB의 컨테이너 이미지를 다운로드하고 태스크 venv를 구축합니다 (일회성; app.test()는 이것들을 필요로 하지 않음)
• 네이티브 s3://, gs://, 및 Azure 데이터 루트는 선택적 버킷 백엔드(uv sync --extra bucket)를 사용하며, 로컬 경로는 이를 가져오지 않습니다
• Linux x86_64/aarch64 환경에서는 첫 번째 비디오 작업이 체크섬 검증된 고정 ffmpeg/ffprobe 빌드를 사용자 캐시에 다운로드합니다. 대신 관리하는 바이너리를 사용하려면 HFLOW_FFMPEG와 HFLOW_FFPROBE를 설정하세요.
• Windows는 WSL2를 통해 지원됩니다 (Airflow는 Windows에서 네이티브로 실행되지 않습니다)

문서화