Hebbian-Robotics/hflow · 上手攻略

• 仓库：Hebbian-Robotics/hflow
• 链接：https://github.com/Hebbian-Robotics/hflow
• 分类：机器人数据管道 · Physical AI 基础设施
• 作者：Tom
• 更新：2026-08-26

---

是什么

HFlow 是一个开源 SDK，专为机器人和 Physical AI 场景设计的多模态数据流水线工具。它的核心功能是：把原始的多模态 episode 数据（视频、状态、动作、时间戳、元数据）经过质量检查、转换、富化、筛选 curation，最终产出干净、可查询、带 provenance 的训练数据集。

一句话说清：HFlow 让机器人数据团队用普通 Python 函数定义质量检查，由框架负责执行、版本化、可观测和审查追踪。

创始团队来自哥伦比亚大学和新加坡国立大学，曾在 Jane Street、Verkada、Google DeepMind、OpenAI 工作；已从 Y Combinator S26 批量毕业。⚠️ HFlow 是 Dyna Robotics 公开分享的"Training Dyna-2 at million-hour scale"文章的独立开源实现，非 Dyna Robotics 官方产品。

---

解决什么问题

机器人数据团队面临三个层次的数据地狱：

1. 采集端混乱：来自不同系统（人工穿戴摄像头、遥操作机器人、自主策略）的视频/状态/动作数据格式各异，同步困难。
2. 质量检查碎片化：相机冻结、串口漂移、话题消失、重复录制——团队通常靠临时脚本处理，脚本一多就不知道"哪个版本跑了哪批数据"。
3. 规模化后的可审计性缺失：数据变大后，谁跑了什么、数据来自哪批录制、哪个实验用了哪个版本的数据集——全部变成黑箱。

HFlow 的解法是四阶段生命周期：

collection → ingestion → curation → delivery
(landing     (transform   (SQL over    (curated MCAP +
 bucket)     + QC gate +  episode      manifest;
              enrich,      catalog)     convert for
              as Airflow                  training)
              DAG)

---

快速安装

# 安装 SDK（需要 Python ≥ 3.11）
uv add hflow

# 或用 pip
pip install hflow

# clone 仓库并跑 quickstart
git clone https://github.com/Hebbian-Robotics/hflow.git
cd hflow
uv sync --locked
uv run python examples/quickstart.py          # 合成数据，无须 MCAP 文件
uv run python examples/quickstart.py path/to/episode.mcap  # 用自己的数据

⚠️ 版本注记：README 自述"HFlow starts at version 0.2.0"；此前 0.1.x PyPI 版本属于另一个不相关的非活跃项目（名称转移后重新开始）。

---

核心用法

1. 定义质量检查（核心 API）

import hflow
from hflow.checks import camera_frame_stats
from your_existing_qc import check_joint_smoothness  # 你的已有检查代码直接复用

app = hflow.App("kitchen-pipeline")

@app.check()
def joint_smoothness(ep: hflow.Episode) -> hflow.CheckResult:
    joints = ep.channel("/joint_states").to_numpy()
    result = check_joint_smoothness(joints, rate_hz=100)  # 你的代码，零改动
    return hflow.CheckResult(measurements=result)           # 框架记录测量值

@app.check(critical=True)
def camera_blackout(ep: hflow.Episode) -> hflow.CheckResult:
    camera_topic = next(topic for topic in ep.cameras if "wrist_cam" in topic)
    evidence = camera_frame_stats(ep, cameras=[camera_topic])
    black_frame_pct = evidence.measurements[f"{camera_topic}/black_frame_pct"]
    return hflow.CheckResult(
        measurements={"black_pct": black_frame_pct},
        verdict=black_frame_pct < 50.0,  # 阈值由你定，不是框架硬编码
    )

if __name__ == "__main__":
    app.test("episode_0001.mcap")  # 进程内跑完整流水线，无需 Docker/Airflow

关键设计原则：你自己的处理代码保持不变——HFlow 只在"检查结果如何记录"这一层加钩子，不要求你重写质量检查逻辑。

2. Curation 查询（SQL 筛选）

# 命令行 curation
hflow curate "SELECT episode_id, uri FROM episodes WHERE task = 'fold_napkin' AND status = 'ok' AND black_pct < 1.0 AND pipeline_version = 'a41c9f27b3d8'"

# Python API
from hflow import curate
curate(
    data_root / "catalog",
    sql,
    output="manifest.parquet"
)

Curation 输出包含覆盖率（coverage denominators），让你知道查询命中了多少条记录中的多少条。

3. 用你的 MCAP 文件

# 检查你的文件是否符合 HFlow 输入要求
uv run hflow doctor path/to/your-episode.mcap

# 摄入并跑完整流水线
uv run hflow ingest path/to/your-episode.mcap

MCAP 是 HFlow 的 v1 输入/输出边界（Foxglove / ROS 2 原生格式），支持视频（H.264/H.265/VP9/AV1）、状态、动作等时间序列数据的同步存储。

4. 调度流水线（Airflow 3）

# 启动本地 Docker Compose 运行时（包含 Airflow）
app.run()

# 然后用 CLI 触发摄入
uv run hflow ingest path/to/episode.mcap

或把流水线部署到已有的 Airflow 3 环境（Astronomer MWAA / Cloud Composer / 自管理）。

5. 可观测性

# 查看流水线图（Airflow DAG 可视化）
# app.run() 后自动渲染 DAG

HFlow 在每个处理的 episode 上附加 provenance 元数据：schema 版本、流水线版本、工具版本、源 URI。这些元数据写入 Parquet catalog，后续可用 DuckDB 查询。

---

典型适用场景

• 机器人遥操作数据清洗：采集的原始视频往往包含相机冻结、黑帧、不同步等问题；用 camera_frame_stats 等内置检查快速过滤。
• Physical AI 数据规模化：百万小时级别的数据 corpus，需要可重复、可追溯的流水线；HFlow 提供了 provenance + 版本化的基础设施。
• 多团队数据共享标准：不同实验室的数据格式和质量标准不同；MCAP + HFlow 作为共享边界，让数据消费者自己写 SQL 筛选，不需要对方改格式。
• 训练数据质量审计：DuckDB SQL 查询可直接对 catalog 进行统计分析，无需加载原始视频。

---

坑与注意

1. pre-v1 状态：README 自述"Status: pre-v1, with the core lifecycle working end to end"——核心功能可用，但 API 可能在 1.0 前有 Breaking Change。

2. MCAP 是硬性要求：HFlow 的 v1 输入/输出边界是 MCAP 格式；非 MCAP 数据需要先转换才能进入流水线。

3. Training 不在范围内：HFlow 流水线终点是"已清洗、带标签、版本戳记的 episode + manifest"，不负责训练；LeRobot 等训练格式转换器计划作为独立包提供（convert to training formats）。

4. Windows 支持通过 WSL2：Airflow 不支持原生 Windows，必须用 WSL2。

5. 第一次 hflow up 要下载 ~2 GB 容器镜像：只有 Docker 运行时需要；app.test() 完全不需要 Docker。

6. Dyna Robotics 背景：HFlow 是 Dyna Robotics "Training Dyna-2 at million-hour scale"文章的独立开源实现，设计理念相同但实现完全独立，不要与 Dyna 的商业产品混淆。

7. 质量检查是证据，不是判决：CheckResult 记录测量值（measurements），通过（verdict）由 Curation 时由用户定义的 SQL 阈值决定——HFlow 不会因为一个黑帧就删数据。

8. FFmpeg 自动下载：Linux x86_64/aarch64 上首次视频操作会下载校验过的 ffmpeg 二进制；可用 HFLOW_FFMPEG / HFLOW_FFPROBE 环境变量指定自己的版本。

---

与同类对比

项目	核心功能	输入格式	质量检查	调度
HFlow	机器人数据清洗 + curation	MCAP	Python 函数（你的代码）	Airflow 3 / Docker Compose
Foxglove Data Platform	机器人数据管理	MCAP	闭源内置	云服务
Rerun	数据可视化	多格式	❌	❌
LeRobot	机器人学习	自定义	❌	❌
Open X-Embodiment	数据集聚合	多种	❌	❌
Mentat / DVC	数据版本化	任意文件	❌	❌

HFlow 的差异化在于：质量检查是你自己的 Python 代码，不需要学框架的 DSL；且 provenance 直接写入数据本身，不只是元数据表。

---

一句话推荐结论

如果你在采集或处理机器人/Physical AI 数据，HFlow 是目前最接近"数据团队自己定义质量标准"的开源方案——用普通 Python 写检查，用 Airflow 跑流水线，用 DuckDB 做筛选，生产级数据管道从第一天就能本地跑通。

---

最小可跑命令

# 环境：Python ≥ 3.11 · Docker（仅生产调度用，dev 不必需）
# 硬件：无特殊要求；Linux x86_64/aarch64 首次视频操作下载 ffmpeg

# 1. 安装（uv 或 pip）
uv add hflow

# 2. 克隆并装依赖
git clone https://github.com/Hebbian-Robotics/hflow.git
cd hflow && uv sync --locked

# 3. 用合成数据跑 quickstart（不需要 MCAP 文件）
uv run python examples/quickstart.py

# 4. 用自己的 MCAP 文件跑
uv run python examples/quickstart.py path/to/episode.mcap

# 5. 检查文件是否符合 HFlow 输入要求
uv run hflow doctor path/to/episode.mcap

# 6. 查看 CLI 帮助
uv run hflow --help

⚠️ 视频处理需要 ffmpeg（Linux x86_64/aarch64 自动下载；macOS/Windows 请自行安装 ffmpeg）；app.test() 不需要 Docker，完整 app.run() 调度才需要 Docker Compose。

---

来源与引用

• 主仓库：https://github.com/Hebbian-Robotics/hflow
• 文档首页：https://strandsagents.com/（HFlow 文档站）
• Quickstart 指南：https://github.com/Hebbian-Robotics/hflow/blob/main/docs/RUNTIME.md
• Dyna-2 原始文章（Aug 2026）：HFlow 设计参考，Dyna Robotics 公开博客
• Dealroom YC S26 报道：https://app.dealroom.co/news/note/hebbian-robotics-launches-from-yc-s26-with-data-quality-apis-for-robotics
• MCAP 格式（Foxglove）：https://foxglove.dev/
• Airflow 3：https://airflow.apache.org/

⚠️ 不确定处：benchmark 数据（文档提到 benchmark 报告）未在本文档中直接引用，无法验证具体数字；pre-v1 状态意味着 API Breaking Change 风险存在，生产使用前请关注 GitHub releases。