推理流水线概述

系统目的与范围

推理服务包（inference_service）连接已训练的 LeRobot 策略与实时机器人控制。其核心职责包括：

模型加载：加载 ACT、Diffusion Policy、VLA 和其他 LeRobot 兼容 checkpoint 文件 src/inference_service/inference_service/core/pure_inference_engine.py:169-176。
观测处理：使用 TensorPreprocessor 将 ROS 2 传感器流（相机、关节状态）转换为模型可用的 tensor src/inference_service/inference_service/core/preprocessor.py:73-86。
GPU 推理：通过 PureInferenceEngine 执行策略 forward pass src/inference_service/inference_service/core/pure_inference_engine.py:1-14。
动作生成：通过 TensorPostprocessor 将输出 tensor 转换为可执行命令 src/inference_service/inference_service/core/postprocessor.py:70-86。
部署灵活性：同时支持单机（zero-copy）和分布式（edge-cloud）执行 src/inference_service/inference_service/lerobot_policy_node.py:5-26。

该流水线不处理动作执行、时间平滑或电机控制，这些由 Action Dispatch 系统负责。

来源：src/inference_service/inference_service/lerobot_policy_node.py:1-33，src/inference_service/inference_service/core/pure_inference_engine.py:1-14

三组件架构

推理流水线遵循 “Composition over Inheritance” 设计，将 AI 执行工作流拆分为三个独立且不依赖 ROS 的核心组件。深入技术细节请参见 Inference Architecture。

组件图

        graph TB
    subgraph "Core Components (inference_service.core)"
        Preprocessor["TensorPreprocessor<br/>(CPU)"]
        Engine["PureInferenceEngine<br/>(GPU)"]
        Postprocessor["TensorPostprocessor<br/>(CPU)"]
    end
    
    subgraph "ROS Integration Layer"
        PolicyNode["LeRobotPolicyNode"]
        Coordinator["InferenceCoordinator"]
    end
    
    subgraph "External Systems"
        Contract["robot_config.yaml<br/>(Contract)"]
        Dispatch["ActionDispatcherNode"]
        Sensors["ROS Sensors<br/>(cameras, joint_states)"]
    end
    
    Contract --> PolicyNode
    Sensors --> PolicyNode
    PolicyNode --> Coordinator
    Coordinator --> Preprocessor
    Preprocessor --> Engine
    Engine --> Postprocessor
    Postprocessor --> PolicyNode
    PolicyNode --> Dispatch

来源：src/inference_service/README.md:7-14，src/inference_service/inference_service/lerobot_policy_node.py:57-67，src/inference_service/inference_service/core/pure_inference_engine.py:3-14

TensorPreprocessor

处理观测 tensor 的转换与归一化，例如 numpy -> torch、HWC -> CHW。它使用模型数据集统计信息准备输入 src/inference_service/inference_service/core/preprocessor.py:73-94。

PureInferenceEngine

无状态执行引擎，封装 ACT、Pi0 等策略模型。它支持 CUDA、Ascend NPU 和 Rockchip RKNN 等多种后端 src/inference_service/inference_service/core/pure_inference_engine.py:29-49。

TensorPostprocessor

将输出动作 tensor 反归一化为物理控制命令，并可按物理安全限制进行 clamp src/inference_service/inference_service/core/postprocessor.py:70-86。

来源：src/inference_service/inference_service/core/preprocessor.py:1-13，src/inference_service/inference_service/core/pure_inference_engine.py:1-14，src/inference_service/inference_service/core/postprocessor.py:1-14

执行模式

推理流水线支持两种部署架构，可通过 robot_config.yaml 中的 execution_mode 参数选择 src/robot_config/config/robots/so101_single_arm.yaml:100-101。

Monolithic Mode (Single-Machine)

在 monolithic 模式中，所有处理（Pre -> Infer -> Post）都在机器人上的单个进程中完成。该模式面向搭载高性能板载 GPU 的机器人，用于获得 zero-copy 延迟 src/inference_service/README.md:20-26。详情请参见 Monolithic Execution Mode。

Distributed Mode (Edge-Cloud)

LeRobotPolicyNode 在机器人（device）上作为代理运行，执行基于 CPU 的预处理，然后把轻量 tensor batch 发送到局域网中的 GPU 服务器上的 pure_inference_node src/inference_service/README.md:28-35。详情请参见 Distributed Execution Mode。

        graph LR
    subgraph "Device (Robot)"
        EdgeNode["LeRobotPolicyNode (Proxy)"]
        EdgePre["Preprocessor (CPU)"]
        EdgePost["Postprocessor (CPU)"]
    end

    subgraph "Cloud/Edge (GPU Server)"
        CloudNode["PureInferenceNode"]
        CloudEngine["PureInferenceEngine (GPU)"]
    end

    EdgeNode --> EdgePre
    EdgePre -->|"/preprocessed/batch"| CloudNode
    CloudNode --> CloudEngine
    CloudEngine -->|"/inference/action"| EdgeNode
    EdgeNode --> EdgePost

来源：src/inference_service/inference_service/lerobot_policy_node.py:5-26，src/inference_service/README.md:37-54

策略节点

流水线通过两个主要 ROS 节点实现。实现细节请参见 Policy Nodes。

LeRobotPolicyNode：主入口。它管理对传感器数据的 ROS 订阅，提供 DispatchInfer action server，并协调推理工作流 src/inference_service/inference_service/lerobot_policy_node.py:148-169。
PureInferenceNode：分布式模式中的轻量节点。它订阅预处理 tensor 并发布原始动作，用于 GPU offloading src/inference_service/inference_service/pure_inference_node.py:38-46。

来源：src/inference_service/inference_service/lerobot_policy_node.py:1-34，src/inference_service/inference_service/pure_inference_node.py:1-15

模型导出与验证 (model_utils)

流水线支持标准 PyTorch 之外的专用硬件后端。详情请参见 Model Export and Validation (model_utils)。

Ascend NPU：通过 AscendOMPolicyWrapper 支持 .om 模型 src/inference_service/inference_service/core/pure_inference_engine.py:83-85。
Rockchip NPU：支持用于 RK3588 部署的 .rknn 模型 src/inference_service/inference_service/core/pure_inference_engine.py:83-85。
验证：测试确保编译后端产生与 PyTorch 一致的结果 src/inference_service/tests/test_ascend_om.py:103-111。

来源：src/inference_service/README.md:156-188，src/inference_service/inference_service/core/pure_inference_engine.py:29-49

注意力可视化 (attention_viz)

流水线集成 attention_viz 包，用于观察模型决策过程。详情请参见 Attention Visualization (attention_viz)。

Heatmap 生成：向 ROS topic 发布 cross-attention 权重用于可视化 src/inference_service/inference_service/lerobot_policy_node.py:102-111。
交互式 Masking：支持 UI 驱动的 masking，用于调试 ACT transformer attention src/inference_service/README.md:80-95。

来源：src/inference_service/inference_service/lerobot_policy_node.py:102-113，src/robot_config/robot_config/launch_builders/execution.py:64-70

Launch 集成

推理流水线由 robot_config 启动系统根据当前 control_mode 动态启动。

关键 launch builder 函数：generate_inference_node()，位于 src/robot_config/robot_config/launch_builders/execution.py:123-142。它解析模型路径，配置执行模式（monolithic vs distributed），并设置可选的注意力可视化 sidecar src/robot_config/robot_config/launch_builders/execution.py:72-120。

来源：src/robot_config/robot_config/launch_builders/execution.py:123-166，src/robot_config/config/robots/so101_single_arm.yaml:88-103