openpi 代码库（π0 / π0.5 VLA）

openpi 是 Physical Intelligence 开源的视觉-语言-动作（VLA）模型库。它干的事：给机器人喂相机图像 + 当前姿态 + 一句指令，输出未来一小段动作（若干步、每步若干维）。主体用 JAX 写，2025-09 起加了 PyTorch 双实现。

库里有三种模型，差别只在"动作怎么生成"（细节见 模型架构）：

• π0 —— 动作是连续数，从噪声一步步"去噪"出来。
• π0-FAST —— 把动作当成"词"，像写句子一样一个个生成。
• π0.5 —— π0 的升级版，换了状态和时间的喂法，泛化更好。

系统形状（你在这里）

整体逻辑

推理路径：观测进、动作出

机器人发来一帧观测（相机图 + 关节角 + 指令）→ 多机器人适配层把硬件差异（摄像头数量不同、状态维度不同、坐标系约定不同）翻译成模型的统一格式 → 归一化子系统把数值缩放到统一范围 → 模型生成动作 → 反归一化回物理单位 → 适配层翻译回机器人格式 → 动作发回机器人。

这条路径的逐步代码走读见 一条推理请求的一生（关键路径）——读懂这一条，整个库就活了。

模型：推理和训练的核心

三种变体共享"图像 / 语言 / 状态 → token → 双专家 Transformer → 动作"的骨架，差别在动作怎么生成——完整拆解见 模型架构（π0 / FAST / π0.5）。模型内部 4 个值得钻进去的组件：把图像切块编码的 SigLIP 视觉编码器、承载两套权重并共享注意力的 双专家 Gemma、从噪声去噪出连续动作的 flow matching 算法、以及把连续动作压成离散 token 的 FAST tokenizer。

π0-FAST 的推理方式和 π0 差别够大——自回归逐 token 生成、KV cache、单专家——所以单独拉了一条 π0-FAST 自回归解码 讲清。

训练路径：数据进、检查点出

数据集 + 上面同一套变换管线 + 归一化（训练和推理共用保证一致）→ 载入预训练权重 → 反复取一批、算损失、更新权重 → 定期存检查点。完整流程见 训练循环。训练支持全量更新和 LoRA 微调（冻结大部分权重、只训练低秩小矩阵）两种策略。

配置：一个名字串起一切

上面的推理和训练，全部由一个配置名驱动。pi05_libero 这样一个字符串，经 配置即注册表 展开成一整套实验定义——模型变体、数据集、预训练权重、超参全钉死。train.py、serve_policy.py、compute_norm_stats.py 三个入口脚本都只吃这一个名字。

框架：JAX 为主、PyTorch 镜像

模型主体用 JAX 写，但同时维护了一套完整的 PyTorch 双实现。上层根据检查点格式自动选择走哪条（有 model.safetensors → PyTorch，否则 → JAX），变换管线和适配层完全共用。

改代码前必读

散读文件读不出来、但改之前必须知道的东西——核心设计取舍、不可破坏的不变量、看起来像 bug 其实是护栏的危险区、值得偷师的巧思——都收在 设计决策 / 不变量 / 危险区。