Rerun Python SDK 实战指南安装、日志、架构与从源码构建【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerunRerun Python SDKPyPI 包名rerun-sdkPython 模块名rerun是 Rerun 项目面向物理 AI 场景提供的数据层工具链用于对多速率multi-rate、多模态multimodal的机器人数据进行录制、转换、查询、可视化乃至模型训练。本指南以 rerun_py/README.md 为骨架结合 rerun_py/ARCHITECTURE.md 与 rerun_py/pyproject.toml 等仓库源码带你掌握 SDK 的安装方式、日志 API 的底层设计、Viewer 与 Logger 的进程分离使用、从源码构建开发版、运行单元测试以及基于 puffin 的性能剖析。SDK 是什么为物理 AI 打造的数据层Rerun 将自己定位为 The data layer for physical AI——提供构建、理解并优化数据回路data loop所需的数据原语data primitives面向从第一次录制到大规模数据集的、跨速率的异构数据。开源的 Rerun Python SDK 提供了一条统一的工具链用于日志Log将多模态、多速率数据写入 Rerun 数据管道转换Transform对数据做重采样、重投影等处理查询Query按时间轴与实体路径检索数据查看View在 Rerun Viewer 中实时可视化训练Train为机器学习训练流程提供数据接入。SDK 本体由 Rust 实现见 rerun_py/src/lib.rs基于 PyO3 绑定通过maturin打包为 Python wheel再向上暴露一个易学、Pythonic 的 API。安装基础安装在 Python 3.10 及以上环境见 rerun_py/pyproject.toml 中的requires-python 3.10中直接使用 pippip install rerun-sdk这里有一个容易混淆的点README 特别强调Python 模块名rerunimport rerun as rrPyPI 包名rerun-sdk。因此安装命令写的是pip install rerun-sdk而代码里import rerun。Jupyter Notebook 支持如果希望在 Jupyter 中交互式可视化数据可以安装配套的 Notebook 组件pip install rerun-sdk[notebook]该 extra 在 rerun_py/pyproject.toml 中声明为notebook [rerun-notebook0.38.0-alpha.1dev]。SDK 还提供了rerun.notebook()等 API 以及rerun_sdk/rerun/notebook.py中的实现便于在 Notebook 单元格内直接渲染 Viewer。运行时依赖从 rerun_py/pyproject.toml 可以看到 SDK 的核心依赖及用途依赖最低版本用途attrs23.1.0生成 archetype/component/datatype 的原生 Python 对象numpy2数值数据交互与批量构建pillow8.0.0图像读取与 JPEG 编码psutil7.0tracing_session()采集 CPU 与网络指标pyarrow18.0.0Arrow 序列化与列式数据交互typing_extensions4.5类型标注兼容快速上手记录一个 3D 点云README 给出的最小示例在初始化之后仅用一行rr.log即可把点云推给 Viewerimport numpy as np import rerun as rr rr.init(rerun_example_app, spawnTrue) positions np.vstack([xyz.ravel() for xyz in np.mgrid[3 * [slice(-5, 5, 10j)]]]).T colors np.vstack([rgb.ravel() for rgb in np.mgrid[3 * [slice(0, 255, 10j)]]]).astype(np.uint8).T rr.log(points3d, rr.Points3D(positions, colorscolors))这一小段代码背后是 SDK 的核心设计详见 rerun_py/ARCHITECTURE.mdComponent组件内存布局良好、语义明确的数据块。例如Color组件内部是一个uint32表示 sRGB/RGBA 的 rgba32 信息Archetype原型一组组件的集合代表 Viewer 能够理解的一类高层对象。以Points3D为例它由Position3D坐标单数形式、Colorrgba32可选、Label文本标签可选、Radii点半径可选等组件组成Datatype数据类型内存布局良好但通常缺乏语义的对象如Vec3D是长度为 3 的float32数组可被Position3D等组件复用。rr.log是 SDK 最主要的日志入口。查看 rerun_py/rerun_sdk/rerun/_log.py 的实现其签名与行为要点如下entity_path数据在空间层级中的路径既可以是字符串特殊字符需转义、按未转义的/拆分也可以直接传一个未转义字符串的列表——world/my image!与[world, my image!]等价。以__开头的路径保留给 SDK 自身使用entity任何实现了rerun.AsComponents接口的对象通常是 archetype或一组DescribedComponentBatch的可迭代对象*extra可额外传入任意数量的组件包只要不产生冲突的组件就会被合并记录到同一个实体路径下例如同时记录rr.Points3D、rr.Arrows3D和一个自定义的rr.AnyValues(confidence[...])static为True时数据记录为静态数据——不关联任何时间存在于所有时间轴上并无条件遮蔽同类型的时间数据默认False时数据会被自动打上log_time时间戳recording指定使用的RecordingStream缺省时使用当前活动的全局 recordingstrict为True时对不可日志化的数据抛出异常False时降级为警告None时采用全局rerun.strict_mode()的设定。初始化参数详解rr.init的完整签名见 rerun_py/rerun_sdk/rerun/init.pyapplication_id应用的唯一标识Viewer 将按此 ID 归类 recording。以rerun_example_开头的 ID 保留给官方示例会开启额外分析、并确定性初始化随机种子recording_id进程写入的 recording UUID。默认值基于multiprocessing.current_process().authkey因此通过multiprocessing派生的所有子进程默认共享同一个 recording——这正是多进程日志的关键机制。若要让多个独立进程写入同一 recording需手动指定相同的recording_idspawnTrue时自动拉起一个 Rerun Viewer 并流式发送数据等价于单独调用spawn不传则日志事件会无限期缓冲直到调用connect_grpc、show或savedefault_enabledRerun 日志默认是否开启可用环境变量RERUNon/RERUNoff覆盖init_logging是否为此应用初始化日志系统strict严格模式开关也可用RERUN_STRICT环境变量覆盖默认等价于Falsedefault_blueprint设置应用的默认蓝图blueprint仅在用户点击 reset blueprint 或调用send_blueprint后才会立即生效send_properties是否立即把 recording 属性发送给 Viewer默认True。另一个值得注意的语义init()再次调用时会 flush 全部现有 recording 并销毁孤儿 recording 以释放文件描述符等资源同时若两次调用不指定recording_id它们写入的是同一个recording进程生命周期内保持不变不会产生两个独立 recording。要创建多个独立 recording应显式传入不同的 UUIDfrom uuid import uuid4 rr.init(my_app, recording_iduuid4()) rr.init(my_app, recording_iduuid4())Viewer 与 Logger 跨进程运行Viewer 与 Python 日志器可以运行在不同的进程中甚至运行在不同的机器上。README 给出的是标准的两终端工作流。终端一启动 Viewerpython3 -m rerun是模块入口实际委托给rerun_cli/__main__.py的main()见 rerun_py/rerun_sdk/rerun/main.pypython3 -m rerun终端二运行带--connect选项的示例脚本让 SDK 连接已启动的 Viewerpython3 examples/python/plots/plots.py --connect上述示例脚本位于 examples/python/plots/plots.py。在本地调试时通常用rr.init(app, spawnTrue)一键完成启动 Viewer 连接而当 Viewer 与 Logger 分属不同进程/机器时则先手动启动 Viewer再让各日志进程以--connect或对应的连接 API 接入。SDK 提供的连接选项还包括connect_grpc、save写.rrd文件等 sink具体实现见 rerun_py/rerun_sdk/rerun/sinks.py。架构透视对象类型与代码生成理解 SDK 的快速上手体验来自架构设计rerun_py/ARCHITECTURE.md 对此有系统阐述。三类对象形态每个 archetype、component、datatype 在 SDK 中最多对应三种对象形态原生对象ObjectName基于attrs包实现负责 Pythonic 的用户构造 API支持__init__、__array__等魔法方法Arrow 扩展类型对象ObjectNameTypePyArrow 侧的扩展类型定义Arrow 扩展数组对象ObjectNameArrayType负责把用户数据序列化为可直接发送给 Viewer 或写入.rrd文件的 Arrow 数组其from_similar()方法是核心入口从不自动生成、必须手工实现。另有类型别名ObjectNameLike与ObjectNameArrayLike用于类型标注。代码生成多语言 SDK 同步的保障由于 C、Rust、Python 多语言 SDK 需要与 Viewer 的 schema 保持同步大量实现是自动生成的。Python SDK 由re_sdk_types与re_types_builder两个 crate 生成生成器代码位于crates/build/re_types_builder/src/codegen/python.rs。Archetype最简单的生成对象字段即其组成组件以 Arrow 扩展数组形式存储字段转换器一律使用对应组件的from_similar()archetype 原生对象是 SDK 面向用户的主要 APIComponent核心职责是把用户数据序列化为可直接日志的 Arrow 数组。按约定组件必须是恰好一个字段的结构体。生成器区分两类委托式组件delegating字段类型是 datatype其 Arrow 数组实现直接委托给对应 datatype如Point2D委托给Point2Ddatatype非委托式组件non-delegating字段类型是原生类型如float、int需自行处理序列化因此会额外生成原生对象与类型别名Encoding编码/数据类型建模结构良好的数据类型提供用户友好的构造 API 与 Arrow 序列化支持复杂的嵌套结构如含 struct 和 union 的Transform3D需要专门处理。扩展机制TypeExt 与手工覆盖钩子完全自动生成无法满足易用、Pythonic的全部要求因此生成器提供了若干扩展钩子extension hooks每个类都会在同目录寻找class_ext.py文件如encodings/rgba32_ext.py是Rgba32datatype 的扩展。扩展类必须以TypeExt命名以 mixin 方式并入生成类可覆盖__init__()自定义构造逻辑覆盖后生成类以define(initFalse)创建可在实现中调用attrs生成的__attrs_init__()回退到默认构造fieldname__field_converter_override()静态方法作为字段的converter参数用于把宽松的用户输入归一化为确定类型__array__()让 numpy 自动、受控地吸收类实例native_to_pa_array_override()提供到 Arrow 数据的主要序列化路径。以Color组件为例三者的配合展示了钩子与生成方法之间的精妙互动ColorExt.rgba__field_converter_override()将用户输入灵活归一化为int型 RGBA 存储自动生成的__int__()让Color实例可被 numpy 数组创建函数识别ColorExt.native_to_pa_array()又复用了原生对象的这些能力简化实现。Internal/wrapper 模式仓库经验表明围绕 pyo3 内部对象做一层纯 Python 包装是成功模式以rerun.catalog.CatalogClient为例把接受任何输入的魔法留在 Python 侧而 Rust 对象只暴露简单、规范类型的方法更易受益于 pyo3 的魔法类型转换。具体做法是在src中创建PyMyObjectInternal并以 pyo3 暴露为MyObjectInternal在rerun_bindings中为该对象编写精简但类型精确的 stub公开类MyObject位于rerun_sdk/rerun下持有名为_internal的单一数据成员。从源码构建开发版仓库使用pixi作为开发工具与任务管理器。安装 pixi、克隆仓库后在仓库的rerun/目录下执行以下命令。构建并安装开发版 Python SDKdebug 配置pixi run py-build构建优化版release 配置pixi run py-build-release在开发环境中运行示例pixi run uvpy examples/python/minimal/minimal.py构建 wheel 以便手动安装pixi run py-build-wheel从打包配置rerun_py/pyproject.toml可以看到SDK 的构建后端是maturinbuild-backend maturinwheel 名称为rerun_bindings并通过rerun_sdk.pth把rerun_sdk/rerun加入 Python path 从而支持import reruninclude中还会随包携带rerun/rerun.exeCLI 二进制或 macOS 的Rerun.app应用包各平台只取其一缺失不算打包失败。可编辑安装pip install -e使用 debug profile 以共享 cargo 缓存。完整的 Viewer 与 SDK 构建选项参见 BUILD.md。运行 Python 单元测试运行完整 Python 测试套件pixi run py-test构建 SDK 后只跑单个测试文件pixi run py-build pixi run uvpy -m pytest rerun_py/tests/unit/test_tensor.py测试代码位于 rerun_py/tests含unit/、integration/、e2e_redap_tests/等目录。从 rerun_py/pyproject.toml 的[project.optional-dependencies]可见测试依赖包括pytest、inline-snapshot、syrupy快照对比、torch、datafusion、opencv-python、PyAV用于 mp4 视频流解复用测试等pytest配置将警告一律视为错误filterwarnings error。性能剖析 Python SDK当需要定位 SDK 侧的性能瓶颈例如日志吞吐时README 给出了基于 puffin 分析器的流程cargo install puffin_viewer RERUN_PUFFIN1 pixi run uvpy your_script.py设置环境变量RERUN_PUFFIN1后SDK 会把 puffin 记录到的 profile 数据发送给puffin_viewer进行可视化分析也可以从 Viewer 中保存一段 recording 供离线分析。仓库内提供了skills/investigate-puffin/技能含compare_traces.py、find_scopes.py等辅助脚本用于分析 puffin 轨迹。若问题在 Viewer 一侧或需要排查端到端流式延迟参见 诊断延迟与性能。预发布版本针对main分支的每日开发 wheel 以 pre-release 形式发布。main分支可能不稳定使用这类 wheel 需要自行承担风险——适合想要提前体验最新 API 的用户生产环境仍建议使用 PyPI 上的稳定发布版。小结从pip install rerun-sdk到一行rr.log完成点云可视化从python3 -m rerun启动 Viewer 到pixi run py-build从源码构建Rerun Python SDK 为多模态、多速率的物理 AI 数据提供了一条完整的录制 → 转换 → 查询 → 查看 → 训练链路。其底层以 Archetype/Component/Datatype 三级抽象统一数据模型以代码生成保证多语言 SDK 与 Viewer 的 schema 同步并以 TypeExt 钩子保留手工打磨 Pythonic API 的空间。若想深入源码推荐从 rerun_py/rerun_sdk/rerun/_log.py 的log()与 rerun_py/rerun_sdk/rerun/init.py 的init()读起再结合 rerun_py/ARCHITECTURE.md 理解整体设计。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考