
Rerun Chunk Processing API 实战指南用 LazyChunkStream 构建多模态机器人数据摄取、变换与转换流水线【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文以 Rerun 的 Chunk Processing API 为核心讲解如何用基于Chunk的 readers、stores 与 lazy streams 三类原语搭建面向多模态机器人数据的摄取ingestion、变换transformation与格式转换conversion流水线。读完本文你将掌握rerun.chunk的完整用法从 MCAP/RRD 等格式读取 chunk、用LazyChunkStream的filter/drop/split/merge/lenses/map/flat_map算子声明式地改写数据、将流水线物化为ChunkStore或直接写出新的.rrd文件并能把处理结果回灌给RecordingStream用于实时可视化。文档原文位于 docs/content/concepts/logging-and-ingestion/chunk-processing-api.md文中所有源码与测试证据均来自当前仓库。一、为什么需要 Chunk Processing APIRerun 内部的所有数据都以Chunk为单位存储与传输。Chunk 是一种由 Apache Arrow。Chunk Processing API 正是围绕 Chunk 这一核心结构构建的、面向数据管线的编程接口。官方文档对其定位是覆盖常见机器人文件格式MCAP、RRD以及实验性的 HDF5、Parquet、MP4的 I/O提供强大的声明式数据整理data wrangling原语过滤、分流、合并、重塑等内置多线程、原生native执行引擎执行时基本不受 GIL 限制设计上预留了未来分布式执行的可能性。与逐行、逐列的rr.log/rr.send_columns日志 API 不同Chunk Processing API 的操作粒度是整个 chunk执行模型是惰性的lazy典型场景是批量摄取、格式转换与后处理流水线。核心模块位置Python 核心 API 位于rerun.chunk包McapReader、RrdReader、Chunk、ChunkStore、LazyStore、LazyChunkStream、DeriveLens、MutateLens、Selector、OptimizationProfile等见 rerun_py/rerun_sdk/rerun/chunk/init.py实验性 ReaderHdf5Reader、ParquetReader、Mp4Reader仍位于rerun.experimentalRust 侧执行引擎位于 rerun_py/src/chunk_stream/engine.rsPython 绑定位于 rerun_py/src/chunk_stream/py_stream.rs。说明McapReader、RrdReader、ChunkStore、LazyStore的 Python 包装类位于rerun_py/rerun_sdk/rerun/chunk/目录实际运算由rerun_bindings中的 Rust 实现承载。二、三类构建原语Readers、Stores、Lazy StreamsChunk Processing API 由三类原语组合而成通过一次终结调用terminal call触发整条流水线的执行Readers读取器从外部数据源产生ChunkStores存储chunk 的集合分为惰性的LazyStore与全量物化的ChunkStoreLazy streams惰性流延迟求值、单遍single-pass的 chunk 迭代器支持过滤、分支、合流、重塑等算子。2.1 Readers流水线的根Readers 负责从文件或数据集catalog server中产出Chunk。它们可以是 Chunk Processing API 自带的类也可以是 Rerun SDK 其他部分提供的类自带类RrdReader、McapReaderrerun_py/rerun_sdk/rerun/chunk/_rrd_reader.py、_mcap_reader.py其他模块提供 Reader 能力的类例如rerun.catalog.DatasetEntry.segment_store()返回对应数据段segment的LazyStore见 rerun_py/src/catalog/dataset_entry.rsrerun.urdf.UrdfTree也在更大的功能集之上提供了 Reader 能力。Readers 提供 chunk 的方式有两种1顺序流式streaming所有 Reader 都支持通过stream()方法顺序地逐块产出全部 chunk。内部实现通常是解析源文件 → 边提取边转换为 chunk → 逐块 yield。2索引随机访问IndexedReader部分 Reader 实现了IndexedReader协议rerun_py/rerun_sdk/rerun/chunk/_indexed_reader.py可以通过LazyStore提供基于索引的随机访问。目前支持RrdReader——依赖 RRD 文件尾部的 footer 索引manifestDatasetEntry.segment_store()——依赖 catalog server 维护的 chunk 索引。当流水线只需要全部 chunk 的一个子集时走LazyStore处理可以避免加载不必要数据的 I/O 开销收益明显。官方文档特别提醒向LazyStore下推过滤条件如lazy_store.stream().filter(content/my/entity)目前尚未实现今天的过滤仍发生在 chunk 被加载之后。无论哪种方式Readers 通常都作为流水线的根并返回一个LazyChunkStream供下游细化与执行。2.2 StoresLazyStore 与 ChunkStore 的取舍Store 是 chunk 的集合有两种互补形态形态语义内存来源LazyStore基于索引、按需加载仅加载清单manifest内存占用小RrdReader(path).store()、DatasetEntry.segment_store()ChunkStore全量物化所有 chunk 常驻内存与录制大小成正比ChunkStore.from_chunks([...])、stream.collect()LazyStore因为只持有索引创建成本低、内存占用有限并且可以只加载与当前处理流水线相关的 chunk来换取性能提升rerun_py/rerun_sdk/rerun/chunk/_lazy_store.py 的 docstring 明确指出manifest 常驻内存chunk 数据按需加载schema()、summary()、__len__无需加载任何 chunk 即可工作。ChunkStore则是全量物化的——这是 Chunk Processing API 中一个重要的例外API 整体倾向于惰性加载与流式执行以便用有界内存处理大数据集但ChunkStore的内存占用随录制大小线性增长使用时需权衡。两类 Store 共享一套通用 API 面提取底层Schemastore.schema()通过.stream()把 Store 重新变成流水线暴露各种统计信息与内容摘要如summary()一行一个 chunk 的确定性文本摘要官方专门用于快照测试。物化ChunkStore的常见理由有两个1运行 chunk 优化compaction详见 优化 chunk 数量文档。rerun rrd optimize背后的同一套合并/拆分逻辑也暴露在 Chunk Processing API 中通过LazyChunkStream.collect(optimizeOptimizationProfile.OBJECT_STORE)即可把优化折叠进 Python 摄取/转换流水线而不是单独跑一个 CLI 步骤。两个内置预设与 CLI 的--profile对应OptimizationProfile.LIVE小 chunk约 4096 行 / 384 KiB面向实时 Viewer 工作流OptimizationProfile.OBJECT_STORE大 chunk约 6.5 万行 / 2 MiB面向 object-store 数据集的高吞吐查询与网络流式传输。对应的数据类定义在 rerun_py/rerun_sdk/rerun/chunk/_optimization_profile.py其字段包括max_bytes、max_rows、max_rows_if_unsorted、extra_passes、gop_batching视频 GoP/关键帧对齐重批处理与split_size_ratio。注意collect()会先把整条流水线物化到内存中的ChunkStore再写出因此整个录制必须能放进 RAM。2直接以 dataframe 查询物化后的ChunkStore.reader(index...)无需启动 catalog server 即可返回一个 DataFusion dataframererun_py/rerun_sdk/rerun/chunk/_chunk_store.py。该 dataframe 与把同样的 chunk 加载进数据集后调用其reader()数据等价因此完整的 dataframe 查询 API 都适用——唯一的差别是没有rerun_segment_id列因为单个ChunkStore没有 segment 概念。例如import rerun as rr from rerun.chunk import Chunk, ChunkStore # 构造一个含 4 行的标量 chunk 并物化 chunk Chunk.from_columns( /sensor, indexes[rr.TimeColumn(frame, sequence[0, 1, 2, 3])], columnsrr.Scalars.columns(scalars[0.0, 0.5, 1.0, 1.5]), ) store ChunkStore.from_chunks([chunk]) # 直接用 DataFusion 查询 from datafusion import col df store.reader(indexframe) df df.filter(col(/sensor:Scalars:scalars)[0] 1.0) print(df) # 或转成 Pandas、Polars、PyArrow 等2.3 LazyChunkStream中央抽象LazyChunkStream是整条流水线的中央抽象一个延迟求值、单遍的 chunk 迭代器提供如下算子rerun_py/rerun_sdk/rerun/chunk/_lazy_chunk_stream.py类别算子语义过滤filter(...)保留每个 chunk 中匹配的部分丢弃其余部分过滤drop(...)filter的补集丢弃匹配部分保留其余分支split(...)分成匹配不匹配两个分支上游只执行一次合流merge(*streams)多路输入扇入为一路各输入内部保序、跨输入顺序不确定重塑lenses(...)用 lens 提取/改写/重路由组件数据逐块变换map(fn)对每个 chunk 应用 Python 函数1:1 输出逐块变换flat_map(fn)对每个 chunk 应用 Python 函数0:N 输出map/flat_map在 Python 中执行受 GIL 限制、顺序执行而filter/drop/split/lenses/merge等结构化算子最终编译为 Rust 侧的原生执行链。设计要点LazyChunkStream不是已物化的集合也不是实际运行的流进程。一个LazyChunkStream实例可以看作流水线描述 DAG有向无环图中的一个叶子节点通过算子组合可以一步步把 DAG 搭起来。一个最小的读 MCAP流水线from pathlib import Path from rerun.chunk import McapReader mcap_path Path(tests/assets/mcap/trossen_transfer_cube.mcap) output_path Path(chunk_processing_intro.rrd) # 只读不处理McapReader.stream() 即流水线根节点 stream McapReader(mcap_path).stream()用filter扩展流水线# 只保留 /robot_left/** 下的数据 stream stream.filter(content/robot_left/**)直到调用终结操作前面没有任何数据被真正读取或处理。例如stream.write_rrd( output_path, application_idrerun_example_chunk_processing_intro, recording_idrun1, )这一行才真正触发流水线执行读取源 MCAP → 执行过滤 → 写出 RRD。以上代码对应仓库中的示例 docs/snippets/all/concepts/chunk_processing_intro.py。流水线执行模型要点流水线是一个 DAG根是若干 reader 或 store叶子是LazyChunkStream组合是廉价的构建 DAG 只是元数据操作与输入规模无关终结方法如.write_rrd()触发实际执行阻塞但多线程、基本无 GIL内存有界内存成本只与某一时刻流过的一个 chunk相关而非总录制大小。移动语义Move Semantics为了准确表达 DAG 的组合过程LazyChunkStream表现出类似 Rust 的移动语义避免意外复用stream.filter(...)会把stream移动进新流水线之后复用stream会抛ValueError: already been consumedstream.split(...)返回两个分支并消费父流每个分支只能被消费一次LazyChunkStream.merge(a, b, ...)消费所有输入。但终结调用不消费流——同一个LazyChunkStream可以针对不同目的地执行多次chunk_list stream.to_chunks() # 第一次执行物化为 chunk 列表 stream.write_rrd(path..., application_id..., recording_id...) # 第二次执行写 RRD注意这样会把整条流水线执行两遍对复杂流水线可能不划算。此时可以先用collect()把流收集成中间的ChunkStore用内存换掉重复计算。终结操作一览源码见 rerun_py/src/chunk_stream/py_stream.rs 与 rerun_py/rerun_sdk/rerun/chunk/_lazy_chunk_stream.py终结方法作用write_rrd(path, application_id..., recording_id...)执行流水线并把所有 chunk 写入.rrd文件collect(optimize...)执行并物化为ChunkStore可带优化配置to_chunks()执行并返回 chunk 列表__iter__()逐块迭代触发执行send_to_recording(recording...)内部rr.send_chunks包装把 chunk 推入 RecordingStreamLazyChunkStream.from_iter(...)静态方法把 Python 可迭代的 Chunk 包装成流作为用户自定义数据源三、实战端到端流水线——把机器人 MCAP 改写成可分析的 RRD官方文档用一个完整案例贯穿全篇读取一个机器人手臂robot-arm的 MCAP 录制把 protobuf 关节状态joint-state列扇出成按关节拆分的Scalars序列单位换算为度再打上一个用Chunk.from_columns从零构造的静态/metadatachunk最后写出新的.rrd。完整源码见 docs/snippets/all/concepts/chunk_processing.py输入文件是 tests/assets/mcap/trossen_transfer_cube.mcap仓库测试资源。仓库中还有更贴近实际场景的参考示例examples/python/robot_data_preprocessing。3.1 Setup导入与定位输入from __future__ import annotations import math import uuid from collections.abc import Callable from pathlib import Path import pyarrow as pa import pyarrow.compute as pc import rerun as rr from rerun.chunk import Chunk, DeriveLens, LazyChunkStream, McapReader, Selector MCAP ( Path(__file__).resolve().parents[4] / tests / assets / mcap / trossen_transfer_cube.mcap ) OUT Path(chunk_processing.rrd)这一步导入了 Chunk Processing API 的入口点读取器McapReader、chunk 与流类型Chunk/LazyChunkStream、lens 原语DeriveLens/Selector并相对仓库根定位输入 MCAP、选取 CWD 相对的输出路径。此时尚未触碰任何 Rerun 数据。3.2 Reading惰性地读取stream McapReader(MCAP).stream()这是唯一触碰数据源的代码行——而且它也是惰性的此刻没有任何 MCAP 字节被解码返回的LazyChunkStream就是流水线 DAG 的根。McapReader构造参数rerun_py/rerun_sdk/rerun/chunk/_mcap_reader.py提供了丰富的摄取控制timeline_type把 MCAPlog_time列解释为墙钟时间戳timestamp_ns默认还是纳秒时长duration_nstimestamp_offset_ns给所有TimestampNs时间列统一加上的纳秒偏移decoders启用的 MCAP 解码器标识列表可用McapReader.available_decoders枚举省略则启用全部include_topic_regex/exclude_topic_regex按 RE2 语法、非隐式锚定的 topic 正则过滤include 先匹配、exclude 后应用start_time_ns/end_time_ns按原始 MCAPlog_time的纳秒上下界截断下界含、上界不含recover当文件尾部缺失或损坏被截断的录制没有 footer/summary时从前到后扫描重建 summary 以尽量恢复数据。3.3 Processing声明式变换drop lenses 扇出JOINTS [ waist, shoulder, elbow, forearm_roll, wrist_angle, wrist_rotate, ] def pick_joint(i: int) - Callable[[pa.Array], pa.Array]: Extract joint i from a listfloat64 column and convert rad → deg. return lambda arr: pc.multiply(pc.list_element(arr, i), 180.0 / math.pi) def fan(side: str) - list[DeriveLens]: return [ DeriveLens( schemas.proto.JointState:message, output_entityf/joints_deg/{side}/{name}, ).to_component( rr.Scalars.descriptor_scalars(), Selector(.joint_positions).pipe(pick_joint(i)), ) for i, name in enumerate(JOINTS) ] processed ( stream .drop(content/video_raw/**) # 按内容剪枝本例中是 no-op .lenses( fan(left), content/robot_left/**, output_modeforward_unmatched, ) .lenses( fan(right), content/robot_right/**, output_modeforward_unmatched, ) )要点逐条拆解drop(content/video_raw/**)对这个 MCAP 而言是 no-op路径不存在但示范了基于内容entity path 表达式的剪枝。fan(side)构建六个DeriveLens每个关节一个。每个 lens 从schemas.proto.JointState:message组件中用Selector(.joint_positions).pipe(pick_joint(i))取出.joint_positions[i]经pyarrow.computepc.list_element取第 i 个元素、pc.multiply乘180/π完成弧度→角度换算然后路由到/joints_deg/side/joint作为Scalars列写出。两次作用域限定的.lenses(...)分别只对/robot_left/**与/robot_right/**下的 chunk 应用对应侧的扇出。同一个组件名schemas.proto.JointState:message在两侧都存在用content作用域消解歧义forward_unmatched让作用域之外的每个 chunk 原样透传。关于DeriveLens的完整 APIrerun_py/rerun_sdk/rerun/chunk/_lens.py构造DeriveLens(input_component, *, output_entityNone, scatterFalse)scatterTrue时启用 1:N 行映射展开列表.to_component(component, selector, *, cast_toNone)新增一个组件输出列cast_to可为auto转为组件的规范 Arrow 类型或显式pyarrow.DataType.to_timeline(timeline_name, timeline_type, selector)从输入列提取新的时间列类型为sequence/duration_ns/timestamp_ns值以纳秒计.to_packed_component(component, *fields, cast_toauto)把多个同类型字段打包为定长列表组件列如Points3D:positions。Selector是一门受 jq。基本语法元素详见 Lenses 概念文档.恒等选择当前值.field访问命名字段如.my.nested.struct.field.sequence[]遍历序列中所有元素.sequence[].x访问序列每个元素上的字段.optional_field?访问可选字段跳过缺失值pack(.x, .y, .z)把多个同类型字段打包成定长列表Nullable 字段需加!如pack(.x!, .y!, .z!)|管道前一个表达式的结果流入下一个——在查询字符串里用于可读性如.poses[] | .x。Selector.pipe()更进一步可以接入宿主语言的任意函数用于超越路径导航的值变换单位换算、算术等这正是pick_joint的用法。Selector.execute(source)直接对pyarrow.Array求值execute_per_row则对 list 数组逐行求值并保证输出行数与输入一致。lens 的output_mode控制流经 lens 时转发哪些组件ForwardUnmatched转发未被任何 lens 消费的原始组件 lens 产物本例用法ForwardAll转发全部原始组件 lens 产物有数据重复但便于调试DropUnmatched只转发 lens 产物丢弃其余默认。3.4 Merging手工构造静态 chunk 并扇入metadata Chunk.from_columns( /metadata, indexes[], columnsrr.AnyValues.columns( processing_typeingestion, processing_versionv1, ), ) merged LazyChunkStream.merge(processed, LazyChunkStream.from_iter([metadata]))Chunk.from_columns(/metadata, indexes[], columns...)从零构造一个静态 chunk——indexes[]即静态无时间列。任意 archetype 的.columns(...)辅助函数都可用此处用rr.AnyValues.columns(...)写入任意键值对元数据LazyChunkStream.from_iter([metadata])把单个 chunk 提升为单元素流以便参与流水线LazyChunkStream.merge(processed, ...)扇入fan-in两个输入汇成一路顺序按输入各自内部保序而非全局有序。Chunk的构造 APIrerun_py/rerun_sdk/rerun/chunk/_chunk.py还有更多入口Chunk.from_columns(entity_path, indexes, columns)镜像rr.send_columns接受相同的rr.Archetype.columns(...)辅助函数Chunk.from_record_batch(record_batch, *, index..., entity_path...)把单个 ArrowRecordBatch解释为 chunk 数据按rerun:*Arrow 元数据分类每列row-id 列 / index 列 / 组件列并按实体路径每实体产出一个 chunkChunk.from_dataframe(dataframe, ...)接受 PyArrowTable、RecordBatchReader或任何实现 Arrow C stream 接口的对象如datafusion.DataFrame逐 batch 调用from_record_batch惰性产出 chunk。3.5 Writing终结执行merged.write_rrd( OUT, application_idrerun_example_chunk_processing, recording_idstr(uuid.uuid4()), )write_rrd(...)是终结操作这里 DAG 才真正执行整条流水线以单次流式遍历完成application_id与recording_id标识产生的录制每次调用用新的uuid.uuid4()保证产出不同录制的记录。四、与日志 API 的关系互操作与选择日志 APIrr.log、rr.send_columns、RecordingStream与 Chunk Processing API 面向同一个底层数据模型但差异明显原文表格日志 APIChunk Processing API方向logging call → sinkchunk source → transform → chunk sink粒度单行或单列数据整个 chunk执行模型连续随日志调用持续发射惰性在流执行时触发chunk 来源由日志 API 的 batcher微批处理构建已存在来自 reader或显式用Chunk.from_columns/Chunk.from_record_batch构建典型用途实时数据记录摄取、转换、后处理流水线两者可以互操作日志 → chunk 处理把RecordingStream存成.rrd再用RrdReader打开得到LazyChunkStream。官方注记这种经文件的往返未来会优化其易用性与性能。chunk 处理 → 日志rerun.send_chunks(chunks, recording...)把 chunk 送入活跃的RecordingStream例如流式送给 viewer 实时查看。send_chunks接受单个Chunk、LazyChunkStream、LazyStore、ChunkStore或任意Chunk可迭代对象rerun_py/rerun_sdk/rerun/_send_chunks.py对LazyChunkStream/LazyStore输入会阻塞至执行/加载完成源的application_id/recording_id不保留chunk 采用目标录制的身份。底层实现是 py_stream.rs 的send_to_recording逐 chunkrecording.send_chunk(...)并刷新垃圾队列。手工构建 chunkChunk.from_columns镜像rr.send_columns、接受同样的rr.Archetype.columns(...)辅助函数因此任何能用rr.send_columns记录的数据都能打包成Chunk注入处理流水线同理Chunk.from_record_batch单个RecordBatch与Chunk.from_dataframe多 batch 的Table/RecordBatchReader/datafusion.DataFrame分别镜像rr.send_record_batch与rr.send_dataframe。注意send_chunks/send_columns路径会绕过时间上下文time context与微批处理器micro-batcher——chunk 以其构建时自带的 timelines 原样转发。而日志 API 走 batcherchunk 由 SDK 侧批量构建。两者配合的完整背景可读 Chunks 概念文档。五、引擎实现原理从 DAG 描述到可运行链Rust 侧的执行引擎位于 rerun_py/src/chunk_stream/engine.rs。其模块注释说明LazyChunkStream维护的是声明式图declarative graph描述compile()把它变成一串实现了ChunkStreamtrait 的可运行节点链第一次遍历scan_split_usage检测悬空dangling的 split 分支将其退化为 filter/drop——否则悬空分支会通过有界 channel 卡死整条流水线第二次遍历compile_inner在CompileContext携带该次编译的整图状态如共享的 split channel中构建可运行链每次compile()调用创建独立的CompileContext编译调用之间不共享可变状态因此同一个流水线描述可以被反复编译、反复排空执行——这正是终结调用不消费流这一语义的底层支撑split 分支通过有界 channel 在并发执行时共享上游两个分支共享同一上游、只执行一次。Python 侧终结调用使用py.detach(...)在释放 GIL 的情况下执行py_stream.rs 中write_rrd、collect、to_chunks、send_to_recording均如此这正是多线程、基本 GIL-free的体现。collect()的物化路径则体现了 chunk 优化与流水线的交汇逐 chunk 插入ChunkStore单遍自然压实随后finalize_compaction依据CompactionOptionsnum_extra_passes、GoP 起点识别is_start_of_gop、split_size_ratio、fix_keyframe等执行额外合并/拆分收敛遍。同一套 CompactionOptions 概念也支撑了rerun rrd optimizeCLI相关实现位于 crates/store/re_chunk_optimizer/src。六、什么时候用它选型建议综合官方文档的定位与仓库实现可以给出如下选型指引实时低延迟记录数据随代码运行逐行产生用rr.log/rr.send_columns由 SDK 的微批处理器自动拼 chunk批量摄取与格式转换把 MCAP/HDF5/Parquet/MP4 等转成 RRD或在不同格式间迁移用 Chunk Processing API——reader →LazyChunkStream算子链 →write_rrd后处理与数据整理过滤、重路由、单位换算、字段提取、按关节/主题拆分filter/drop/split/mergeDeriveLens/Selector是最自然的声明式工具大数据集子集处理优先RrdReader(...).store()/DatasetEntry.segment_store()的LazyStore按需加载 chunk注意过滤下推尚未实现需要 dataframe 分析collect()物化后用ChunkStore.reader(index...)走 DataFusion 查询需要输出优化collect(optimizeOptimizationProfile.OBJECT_STORE / LIVE)把rerun rrd optimize的压缩逻辑内联进 Python 流水线。进一步阅读Chunks底层数据模型Lenses本文用到的重塑原语详解优化 chunk 数量chunk 压缩的动机、CLI 与 API 两种途径仓库示例examples/python/robot_data_preprocessing把 Chunk Processing API 应用到机器人数据的实际工程示例。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考