Rerun 0.24 → 0.25 迁移指南CLI 参数、Flush 语义与 AnyValues 拆分的完整解读【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun导读本文以 Rerun 仓库中的迁移文档 migration-0-25.md 为主体系统梳理从 0.24 升级到 0.25 时所有破坏性变更breaking changes与弃用deprecations。你将掌握废弃 CLI 参数--serve、--drop-at-latency、-o的正确替代写法、Flush 新增可选超时与错误返回的底层机制Rust/C/Python 三端 API 变化、Python 3.9 弃用时间线以及AnyValues与DynamicArchetype拆分后避免数据歧义的正确用法。迁移总览0.25 带来了哪些变化本次迁移涉及三类变化每一类都会直接影响现有代码或脚本的可用性类别变化影响范围CLI 参数移除--serve、--drop-at-latency、-o命令行脚本、script_add_args辅助脚本Flush 语义重构可选超时 错误返回Python / Rust / C 三种 SDKAPI 拆分与弃用AnyValues拆分出DynamicArchetypePython 3.9 弃用使用动态组件的日志代码其中--serve与-o属于“改名即迁移”的低成本变更而 Flush 超时与AnyValues拆分则涉及 API 行为层面的调整下文逐一展开。移除废弃的--serveCLI 参数变更内容0.25 移除了已废弃的--serveCLI 参数迁移方式为# 旧写法0.24 及更早已移除 rerun --serve # 新写法0.25 rerun --web-viewer底层实现佐证从 entrypoint.rs 的源码结构看--web-viewer与--serve-web、--serve-grpc构成了 0.25 起完整的服务端参数体系--web-viewer#[cfg(feature web_viewer)]条件编译要求 Rerun 以web_viewerfeature 编译同时隐含开启--serve-web源码中args.web_viewer为真时强制args.serve_web true--serve-web同时托管一个 HTTP 上的 Web Viewer 与一个 gRPC server作为消息代理接收 SDK 的连接--web-viewer与--serve-web的区别仅在于是否自动打开浏览器open_browser args.web_viewer--serve-grpc只托管 gRPC server不启动任何 Viewer其他相关参数--web-viewer-portWeb Viewer server 监听端口默认取re_web_viewer_server::DEFAULT_WEB_VIEWER_SERVER_PORT、--server-memory-limitgRPC server 缓冲日志消息的内存上限服务于后到的 Viewer、--renderer配合--web-viewer时取webgpu或webgl。因此若你的目标是打开浏览器里的 Web Viewer直接使用rerun --web-viewer若只想托管服务而不自动开浏览器使用rerun --serve-web。移除早已失效的--drop-at-latency参数--drop-at-latency在 0.25 中被彻底移除。官方说明指出该功能已名存实亡很久其更优替代方案的跟踪见 GitHub issuererun-io/rerun#11024。从 entrypoint.rs 的当前参数定义中已搜索不到drop-at-latency相关字段可确认该参数在当前 CLI 解析器中已完全不存在。若你的脚本中还传入了该参数运行时会因未知参数直接报错请直接删除该参数至于按延迟丢弃数据的需求请关注 issue 中替代方案的进展不要自行实现易出错的丢弃逻辑。移除script_add_args中的-o简写变更内容Python 侧rr.script_add_args曾经提供的-o--stdout简写被移除需要显式使用--stdout# 旧写法0.24 及更早已移除 python my_script.py -o | rerun # 新写法0.25 python my_script.py --stdout | rerun底层实现佐证查看 _script_helpers.pyscript_add_args(parser)当前注册的完整参数集为参数说明--headless不显示 GUI--connect连接到外部 Viewer--serve托管 gRPC 与 Web 服务器并打开连接它的 Web Viewer注意这是 Python 辅助脚本的参数与上文的 CLI--serve无关--url连接指定的 Rerun URL--save path将数据保存到指定路径的.rrd文件--stdout将日志数据输出到标准输出便于管道传给 Rerun Viewer而script_setup(args, ...)中对应处理顺序为--stdout→rec.stdout()--serve→rec.serve_grpc()rr.serve_web_viewer(open_browserTrue)--connect→rec.connect_grpc(args.url)--save→rec.save()都不是则按--headless决定是否rec.spawn()。-o简写已不在其中迁移只需把脚本命令行的-o改回--stdout即可其余行为不变。Flush 重构可选超时、错误返回与有进展才阻塞这是 0.25 中语义变化最值得关注的一项涉及三种 SDK。新语义当刷新flush一条 recording stream 时现在可以传入一个最大阻塞时间flush 会一直阻塞直到完成、失败例如连接丢失或到达超时三者之一发生在 C 与 Python API 中负的超时值不再被允许过去负值有特殊含义Python 的 flush 调用在刷新未成功完成时会抛错超时行为得到改进只会在还有进展希望时阻塞。如果 gRPC 连接被切断flush 会以错误中止。因此绝大多数情况下你不需要配置 flush 超时——只有在连接极慢时它才会长时间阻塞。被移除的旧配置入口0.25 移除了三处创建连接时一次性配置 flush 超时的 API语言被移除项Pythonconnect_grpc的flush_timeout_sec参数Rustconnect_grpc_opts的flush_timeout参数Crerun::GrpcSink::flush_timeout_sec也就是说flush 超时从连接时固定改为每次 flush 调用时按需传入。Rust 端flush_with_timeout/flush_blocking/flush_async从 recording_stream.rs 可以看到 0.25 提供的三种刷新方式/// 发起 flush 后立即返回不等待传播永远不会返回 Timeout 错误。 pub fn flush_async(self) - Result(), SinkFlushError /// 阻塞直到 flush 成功完成Ok、出错SinkFlushError::Failed或达到超时SinkFlushError::Timeout。 /// 等价于用 Duration::MAX 调用 flush_with_timeout。 pub fn flush_blocking(self) - Result(), SinkFlushError /// 阻塞至多 timeout 时长期间只要有进展希望就继续等待 /// 例如底层 gRPC 连接断开或从未连上时立即返回 SinkFlushError::Failed。 pub fn flush_with_timeout(self, timeout: Duration) - Result(), SinkFlushError对应错误类型为SinkFlushError其取值至少包含Timeout与Failed由各 Sink 的flush_blocking(self, timeout: Duration)trait 方法实现见 log_sink.rs其中GrpcSink的flush_timeout被描述为flush 期间 SDK 最少等待的时间。Python 端flush(timeout_sec...)PythonRecordingStream.flush的签名变为见 recording_stream.pydef flush(self, *, timeout_sec: float 1e38) - None: timeout_sec: 最多等待这么多秒。 如果达到超时会抛错。 如果设为 0则发起 flush 但不等待。 要点超时参数现在按每次调用传入connect_grpc不再接受flush_timeout_sec见 sinks.py当前connect_grpc仅接受url、default_blueprint、recording达到超时或刷新失败都会抛错因此异常处理应覆盖 flush 调用timeout_sec0等价于非阻塞发起可在析构/退出路径上安全使用源码中__del__与__exit__均以timeout_sec0.0做非阻塞 flush负超时不再被允许。C 端flush_blocking(timeout_sec)C 侧见 recording_stream.hpp/// \param timeout_sec 刷新期间 SDK 最少等待的时间超过后如无进展可能丢弃数据。 /// 传入 FLT_MAX 或 infinity 则阻塞直到成功或失败。 /// 若未能刷新此前发送的全部日志消息返回错误。 Error flush_blocking(float timeout_sec std::numeric_limitsfloat::infinity()) const;同时rerun::GrpcSink::flush_timeout_sec被移除错误码体系中新增了RecordingStreamFlushTimeout见 error.hpp用于表达刷新超时这一失败原因。弃用事项DeprecationsPython 3.9 进入弃用期Python 3.9 已停止官方维护past end-of-lifeRerun 从 0.25 起弃用对 3.9 的支持下一个版本将完全移除 3.9 支持并把最低支持版本提升到Python 3.10建议尽早把 CI 与本地环境升级到 3.10官方支持版本概览见 Rerun Python 文档的 Supported Python versions 一节。AnyValues中的archetype指定被弃用问题背景过去AnyValues允许通过with_field(ComponentDescriptor(...))指定不同的 archetype 名。当同一实体路径下、同名字段使用不同 archetype 名各 log 一次时会出现数据不一致Viewer 能区分二者但 dataframe API 无法唯一区分导致查询结果中只出现一个component_namearbitrary_int 10 example AnyValues() example.with_field(ComponentDescriptor(component_name, archetype_name), arbitrary_int) example.with_field(ComponentDescriptor(component_name, different_archetype), arbitrary_int 1) rr.log(/path, example)from rerun.dataframe import load_recording rec load_recording(path_to_logs_above.rrd) rec.view(indexlog_time, contents/path).select().schema # 只显示一个 component_name 组件信息丢失解决方案拆分为两个工具为消除歧义0.25 将该能力拆成两个工具AnyValues不再携带 archetype 名纯动态组件包DynamicArchetype强制要求提供 archetype 名。使用DynamicArchetype后dataframe API 会把 archetype 纳入列名与内置组件的处理方式一致从而消除歧义arbitrary_int 10 example DynamicArchetype(archetype_name) example.with_component_from_data(component_name, arbitrary_int) another_example DynamicArchetype(another_archetype) another_example.with_field(component_name, arbitrary_int 1) rr.log(/path, example) rr.log(/path, another_example)from rerun.dataframe import load_recording rec load_recording(path_to_logs_above.rrd) rec.view(indexlog_time, contents/path).select().schema # 现在按 archetype 去重后能看到两个 component_name 组件注意下一个版本将彻底移除AnyValues创建时指定archetype的能力请在本版本内完成迁移。源码与测试佐证DynamicArchetype的实现位于 dynamic_archetype.py构造函数签名def __init__(self, archetype: str, drop_untyped_nones: bool True, components: Mapping[str, ComponentValueLike | None] | None None)其内部通过ComponentDescriptor(...).with_builtin_archetype(archetype...)为每个组件批次的描述符注入 archetype从而让下游含 dataframe能区分同名字段还提供with_component_from_data(field, value)、with_component_override(field, component_type, value)等增量方法以及类方法columns(archetype, ...)用于配合rr.send_columns做列式写入Column-oriented返回ComponentColumnList默认按单位长度子批次切分可用.partition重分区。AnyValues的实现位于 any_value.py其内部已改为委托DynamicArchetype._default_without_archetype(...)构造构造后清空 archetype 名即无 archetype 的动态组件包同时保留columns()类方法用于列式场景。两者的drop_untyped_nones默认True控制None/空值组件的丢弃行为默认丢弃因为类型未定型前 logNone没有意义乱序数据场景可设为False但可能触发 warningstrict 模式为异常。组件值可传任意可转换为 pyarrow 数组的数据推荐使用 Rerun 批类型如rr.components.ColorBatch以获得正确的类型处理如 RGBA 打包。仓库测试对两种用法均有覆盖例如 test_registration.py 中使用rr.AnyValues(...)验证类型注册test_chunk.py 与 conftest.py 中使用rr.DynamicArchetype.columns(archetypeImu|Image, components{...})做列式动态组件写入。DynamicArchetype与AnyValues均已从 __init__.py 顶层导出可直接以rr.DynamicArchetype/rr.AnyValues使用。迁移检查清单升级到 0.25 时可按以下清单逐项核对CLI 脚本--serve→--web-viewer或按需使用--serve-web/--serve-grpc删除--drop-at-latency-o→--stdout。Python 辅助脚本rr.script_add_args生成的参数集中已无-o更新文档与调用方确认script_setup的--serve行为托管 gRPC Web 并开浏览器。Flush 调用Python改为rec.flush(timeout_sec...)并为 flush 添加异常处理移除connect_grpc(..., flush_timeout_sec...)Rust使用flush_blocking()/flush_with_timeout(Duration)/flush_async()处理SinkFlushError::{Timeout, Failed}移除connect_grpc_opts的flush_timeoutC使用flush_blocking(timeout_sec)并处理RecordingStreamFlushTimeout等错误移除GrpcSink::flush_timeout_sec三端均不要再传负超时。动态组件需要 archetype 归属时改用rr.DynamicArchetype仅需无类型动态字段时继续用rr.AnyValues确保 dataframe 查询的列名因 archetype 去重而符合预期。Python 版本将开发与 CI 环境升至 Python 3.10为下一版本彻底移除 3.9 做准备。上述所有变更的权威定义均以 migration-0-25.md 与仓库源码为准如果你还停留在更早版本建议逐级参考 docs/content/reference/migration 目录下的各版本迁移文档完成连续性升级。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考