企业官网建设流程全解析

Rerun Python SDK 实战指南：安装、日志、架构与从源码构建

【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun

Rerun Python SDK（PyPI 包名rerun-sdk，Python 模块名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"）中直接使用 pip：

pip install rerun-sdk

这里有一个容易混淆的点，README 特别强调：

• Python 模块名：rerun（import rerun as rr）；
• PyPI 包名：rerun-sdk。

因此安装命令写的是pip install rerun-sdk，而代码里import rerun。

Jupyter Notebook 支持

如果希望在 Jupyter 中交互式可视化数据，可以安装配套的 Notebook 组件：

pip install rerun-sdk[notebook]

该 extra 在 rerun_py/pyproject.toml 中声明为notebook = ["rerun-notebook==0.38.0-alpha.1+dev"]。SDK 还提供了rerun.notebook()等 API 以及rerun_sdk/rerun/notebook.py中的实现，便于在 Notebook 单元格内直接渲染 Viewer。

运行时依赖

从 rerun_py/pyproject.toml 可以看到 SDK 的核心依赖及用途：

快速上手：记录一个 3D 点云

README 给出的最小示例在初始化之后，仅用一行rr.log即可把点云推给 Viewer：

import numpy as np import rerun as rr rr.init("rerun_example_app", spawn=True) 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, colors=colors))

这一小段代码背后是 SDK 的核心设计（详见 rerun_py/ARCHITECTURE.md）：

• Component（组件）：内存布局良好、语义明确的数据块。例如Color组件内部是一个uint32，表示 sRGB/RGBA 的 rgba32 信息；
• Archetype（原型）：一组组件的集合，代表 Viewer 能够理解的一类高层对象。以Points3D为例，它由Position3D（坐标，单数形式）、Color（rgba32，可选）、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，缺省时使用当前活动的全局 recording；
• strict：为True时对不可日志化的数据抛出异常，False时降级为警告，None时采用全局rerun.strict_mode()的设定。

初始化参数详解

rr.init的完整签名见 rerun_py/rerun_sdk/rerun/init.py：

• application_id：应用的唯一标识，Viewer 将按此 ID 归类 recording。以rerun_example_开头的 ID 保留给官方示例（会开启额外分析、并确定性初始化随机种子）；
• recording_id：进程写入的 recording UUID。默认值基于multiprocessing.current_process().authkey，因此通过multiprocessing派生的所有子进程默认共享同一个 recording——这正是多进程日志的关键机制。若要让多个独立进程写入同一 recording，需手动指定相同的recording_id；
• spawn：True时自动拉起一个 Rerun Viewer 并流式发送数据，等价于单独调用spawn；不传则日志事件会无限期缓冲，直到调用connect_grpc、show或save；
• default_enabled：Rerun 日志默认是否开启，可用环境变量RERUN=on/RERUN=off覆盖；
• init_logging：是否为此应用初始化日志系统；
• strict：严格模式开关，也可用RERUN_STRICT环境变量覆盖，默认等价于False；
• default_blueprint：设置应用的默认蓝图（blueprint），仅在用户点击 "reset blueprint" 或调用send_blueprint后才会立即生效；
• send_properties：是否立即把 recording 属性发送给 Viewer（默认True）。

另一个值得注意的语义：init()再次调用时会 flush 全部现有 recording 并销毁孤儿 recording 以释放文件描述符等资源；同时若两次调用不指定recording_id，它们写入的是同一个recording（进程生命周期内保持不变），不会产生两个独立 recording。要创建多个独立 recording，应显式传入不同的 UUID：

from uuid import uuid4 rr.init("my_app", recording_id=uuid4()) rr.init("my_app", recording_id=uuid4())

Viewer 与 Logger 跨进程运行

Viewer 与 Python 日志器可以运行在不同的进程中，甚至运行在不同的机器上。README 给出的是标准的两终端工作流。

终端一：启动 Viewer（python3 -m rerun是模块入口，实际委托给rerun_cli/__main__.py的main()，见 rerun_py/rerun_sdk/rerun/main.py）：

python3 -m rerun

终端二：运行带--connect选项的示例脚本，让 SDK 连接已启动的 Viewer：

python3 examples/python/plots/plots.py --connect

上述示例脚本位于 examples/python/plots/plots.py。在本地调试时通常用rr.init("app", spawn=True)一键完成"启动 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 中最多对应三种对象形态：

1. 原生对象（ObjectName）：基于attrs包实现，负责 Pythonic 的用户构造 API，支持__init__、__array__等魔法方法；
2. Arrow 扩展类型对象（ObjectNameType）：PyArrow 侧的扩展类型定义；
3. 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 面向用户的主要 API；
• Component：核心职责是把用户数据序列化为可直接日志的 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 的扩展）。扩展类必须以<Type>Ext命名，以 mixin 方式并入生成类，可覆盖：

• __init__()：自定义构造逻辑，覆盖后生成类以@define(init=False)创建，可在实现中调用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 SDK（debug 配置）：

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 的构建后端是maturin（build-backend = "maturin"），wheel 名称为rerun_bindings，并通过rerun_sdk.pth把rerun_sdk/rerun加入 Python path 从而支持import rerun；include中还会随包携带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_PUFFIN=1 pixi run uvpy your_script.py

设置环境变量RERUN_PUFFIN=1后，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