# Rotor Safety Engine — 面向具身智能的物理安全实时判定引擎 > **Real-time Robot Safety Middleware — with Dynamic Contact Area, Impulse Boundary & Reaction Force Stability** > > 面向协作机器人与人形机器人的 Physical AI 安全层。ISO 10218 / ISO/TS 15066 对齐，七级风险粒度 · 动宾不可能组合校验。 > > 纯确定性物理 · 动力学驱动 · 单文件零依赖 · 亚毫秒级 · 边缘推理就绪 **当前版本：v4.3.0（社区版）** --- ## 这是什么 Rotor Safety Engine 是一款面向协作机器人与人形机器人的 **实时安全中间件（real-time safety middleware）**，也是 VLA 推理管线中的 **VLA safety layer**，连接 AI 规划与运动执行。 不同于静态阈值检查器，它引入了 **动态接触面积（Dynamic Contact Area）** 用于软物压强建模、**冲量安全边界（Impulse Safety Boundary）** 用于重物运动控制、以及 **反作用力稳定性（Reaction Force Stability）** 约束用于移动操作机器人底盘稳定性判定。 设计对齐 **ISO 10218** 与 **ISO/TS 15066** 安全标准，提供 **Power and Force Limiting (PFL)** 力与功率限制能力，搭配 **七级风险粒度（7-level risk granularity）**，纯 **零依赖 Python（zero-dependency Python）** 实现，适合 **边缘推理（edge inference）** 实时控制场景。 **一句话定位：不理解你的任务，只保证你的动作在物理上是安全的。** --- ## 版本选择 | 功能 | 社区版（Community） | 企业版（Pro） | |------|-------------------|--------------| | 版本 | v4.3.0 | v4.3.1+ | | 四层安全判定 | ✅ | ✅ | | **动态接触面积（Dynamic Contact Area）** | ✅ | ✅ | | **冲量安全边界（Impulse Safety Boundary）** | ✅ | ✅ | | **反作用力稳定性（Reaction Force Stability）** | ✅ | ✅ | | **七级风险粒度（7-Level Risk Granularity）** | ✅ | ✅ | | 超标倍率（over_ratio） | ✅ | ✅ | | 回退参数推荐（retreat_params） | ✅ | ✅ | | 语义合理性分（semantic_plausibility） | ✅ | ✅ | | **动-宾不可能组合（Verb-Object Impossibility）** | ✅ | ✅ | | ISO 合规标注 | ✅ | ✅ | | **作用-反作用完整对（3D向量）** | — | ✅ | | **动量-冲量-时间链路分析** | — | ✅ | | **旋转矩阵方向向量（rotation_matrix）** | — | ✅ | | **Stribeck 静动摩擦曲线** | — | ✅ | | **接触时间物理推导** | — | ✅ | | **能量守恒校验（Work = F × d）** | — | ✅ | | **纯函数力学分析接口（pure_analyze）** | — | ✅ | | **世界模型力学校验能力** | — | ✅ | | 开源协议 | MIT | 商业授权 | | 适用场景 | 研发、原型、教育 | 生产、工业、世界模型 | > **企业版咨询**：contact@rotor-dynamics.ai --- ## 核心特性（社区版） - ⚡ **亚毫秒级延迟 · 实时安全看门狗** — Python 版平均 ~17μs，单线程吞吐量 ~6 万次/秒，**边缘推理**实时控制场景就绪 - 🎯 **Physical AI · 100% 可解释** — 纯物理不等式 + 确定性规则，**动力学驱动**，面向人形机器人与协作机器人安全，零神经网络，零黑盒 - 📦 **单文件 · 零依赖** — 一个 Python 文件，仅用标准库，直接嵌入任何管线 - 🏗️ **四层安全架构** — 语义解析 → 安全适配 → 动作分类 → 综合决策 - 🤖 **35+ 中文动词支持** — 抓取/握持/推拉/插拔/拧转/按压……自然语言模式开箱即用 - 📏 **ISO 标准参考** — 设计对齐 ISO 10218 / ISO/TS 15066，人体接触场景自动标注 - 🎛️ **两种输入模式** — 自然语言模式（接 VLA 输出）+ JSON 参数模式（接控制器） ### 🔬 独家技术亮点 - **🟢 动态接触面积（Dynamic Contact Area）** — 根据 force / stiffness 实时计算接触面积与压强，而非将面积视为常量；可区分"面包压手"与"铁块砸手"的本质差异 - **🟡 冲量安全边界（Impulse Safety Boundary）** — 引入动量（mass × velocity）判定，区分 grasp（轻冲量）与 carry（重冲量）阈值，防止高速移重物侧翻 - **🔴 反作用力稳定性（Reaction Force Stability）** — 将底盘稳定性纳入安全判定（base_weight × g × friction），机械臂力过大可能推倒自身时直接判 FAIL，适配移动操作机器人（Mobile Manipulator） - **📊 七级风险粒度（7-Level Risk Granularity）** — L0～L6 细粒度分级 + over_ratio（超标倍率），破除传统 Low/Medium/High 三档的粗糙划分 - **🧠 动-宾不可能组合（Verb-Object Impossibility）** — 语义知识图谱硬编码常识壁垒（如 grasp + fluid → REJECT），纯物理引擎做不到的"常识推理"第一道防线 - 🔌 **外部数据配置** — 动词库/物体库/规则表支持 JSON 文件加载，业务定制无需改源码 - 🛡️ **健壮输入校验** — 类型/范围/NaN 全面校验，非法输入优雅降级，附带 input_warnings 诊断 --- ## 四层安全架构 ``` 输入（动作 + 物体 + 参数） │ ▼ ┌──────────────────────────┐ │ Layer 1 语义解析层 │ │ 动词库 · 对象属性库 │ │ 机器人能力表 · 规则匹配 │ │ 安全区间计算 · 参数推荐 │ └───────────┬──────────────┘ │ ▼ ┌──────────────────────────┐ │ Layer 2 安全适配层 │ │ 机器人能力约束 │ │ 动作-目标兼容性校验 │ │ 参数安全阈值校验 │ └───────────┬──────────────┘ │ ▼ ┌──────────────────────────┐ │ Layer 3 动作分类层 │ │ FAV 三维分类器 │ │ 动作阶段自动识别 │ │ （idle / grasping / holding） └───────────┬──────────────┘ │ ▼ ┌──────────────────────────┐ │ Layer 4 综合决策层 │ │ PASS / FAIL / REJECT │ │ 全量输出 + 修正建议 │ │ ISO 合规标注 · 七级风险 │ └──────────────────────────┘ ``` > 企业版额外提供 **Layer 5 力学增强层**（作用-反作用 / 动量-冲量 / 能量守恒），详见版本对比。 --- ## 快速开始 ### 安装 ```bash # 方式 1：pip 安装（推荐） pip install rotor-safety-engine # 方式 2：从 GitHub 安装最新版 pip install git+https://github.com/rotor-dynamics/safety-engine.git # 方式 3：单文件，直接拷走即可 cp src/safety_engine.py your_project/ ``` ### 基本使用 — 自然语言模式 ```python from safety_engine import SafetyEngineV4 engine = SafetyEngineV4() # 正常操作 → PASS result = engine.check_command("抓取", "鸡蛋", params={"force": 2.0, "speed": 0.03}, robot="humanoid_basic") print(result["verdict"]) # PASS print(result["risk_level"]) # LOW print(result["risk_level_7"]) # L1 # 力太大 → FAIL result = engine.check_command("抓", "玻璃面板", params={"force": 80.0, "speed": 0.5}, robot="humanoid_basic") print(result["verdict"]) # FAIL print(result["correction"]) # 参数不安全: ... print(result["over_ratio"]) # 超标倍率 print(result["recommended_params_v2"]) # 推荐安全参数 ``` ### 基本使用 — JSON 参数模式（生产推荐） ```python scene = { "objects": [{ "object_id": "metal_part", "name": "铝合金工件", "mass_kg": 2.5, "stability": "rigid", "contact_area_mm2": 500, }] } action = { "type": "grasp", "force_n": 25.0, "velocity_ms": 0.3, "acceleration_ms2": 3.0, "target_object": "metal_part", } robot = { "max_force_n": 150, "max_velocity_ms": 2.0, "max_acceleration_ms2": 10.0, } result = engine.check_action(scene, action, robot) print(result["verdict"]) # PASS print(result["pressure_kPa"]) # 接触压强 print(result["contact_area_mm2"]) # 动态接触面积 ``` ### 自定义数据配置（v4.3.0+） 动词库、物体库、动作规则表支持从外部 JSON 文件加载，业务定制无需改源码： ```python from safety_engine import SafetyEngineV4 # 方式 1：从 JSON 文件加载 engine = SafetyEngineV4.from_config( verb_db_path="config/verbs.json", object_db_path="config/objects.json", action_rules_path="config/rules.json", ) # 方式 2：直接传入字典 engine = SafetyEngineV4( verb_db={"my_verb": {...}}, action_rules={"my_action": {...}}, ) ``` ### 运行 Demo ```bash python examples/demo.py ``` ### 运行测试 ```bash # 方式 1：直接运行（零依赖，推荐快速验证） python tests/test_engine.py # 方式 2：pytest 运行（需安装 pytest） pip install pytest pytest tests/test_engine.py -v ``` --- ## 性能指标 > 测试环境：Python 3.10+ / x86_64 / JSON 参数模式 / 10 万次循环 | 指标 | 数值 | |------|------| | 平均延迟 | **~17 μs**（0.017 ms） | | P95 延迟 | ~22 μs | | P99 延迟 | ~27 μs | | 单线程吞吐量 | **~58,000 次/秒** | | 自然语言模式延迟 | 0.3–0.8 ms | | 内存占用 | < 5 MB | | 外部依赖 | 0（仅 Python 标准库） | | 确定性 | 100%（相同输入永远相同输出） | --- ## 七级风险分级规则 引擎采用七级风险等级（L0~L6），对 PASS 和 FAIL 样本分别使用不同的划分依据： - **PASS 样本**：按 `safety_margin`（安全裕度）分档，裕度越高越安全 - **FAIL 样本**：按 `over_ratio`（超标倍率）分档，倍率越大越危险 | 等级 | 中文标签 | 判定 | 划分依据 | 范围 | |------|----------|------|----------|------| | **L0** | 安全 | PASS | safety_margin | 0.50 ~ 1.00 | | **L1** | 低风险 | PASS | safety_margin | 0.30 ~ 0.50 | | **L2** | 中低风险 | PASS | safety_margin | 0.15 ~ 0.30 | | **L3** | 中风险/接近边界 | PASS | safety_margin | 0.05 ~ 0.15 | | **L4** | 中高风险/临界 | PASS | safety_margin | 0.00 ~ 0.05 | | **L5** | 高风险/越线 | FAIL | over_ratio | 1.0 ~ 1.5 | | **L6** | 危险/严重越线 | FAIL | over_ratio | > 1.5 | --- ## 技术原理 ### 三层力约束模型 力的安全性由三层约束共同决定，最终取最严格值： 1. **输出端约束** — 机器人输出能力上限（电机 / 关节极限） 2. **接收端约束** — 物体力学响应上限（材料 / 结构极限，含动态接触面积、冲量、压强计算） 3. **双向约束** — 反作用力与本体稳定性（牛顿第三定律，机器人基座摩擦力上限） ### 动态接触面积 软质 / 易碎物体在受力后接触面积会增大，压强随面积动态调整： - 刚体（金属、石头）：刚度大，接触面积基本不变 - 软物（面包、水果）：刚度小，接触面积随力线性增长 - 易碎物（鸡蛋、玻璃）：变形极小但压强大了直接碎，以压强阈值判定 ### 冲量安全校验 对 carry / move / push / pull / lift 等有位移的动作，增加 `冲量 = 质量 × 速度` 的安全约束： - 易碎物 / 液体：冲量上限低 - 重物 / 刚体：冲量上限高 - 人体接触：冲量上限收紧 ### 反作用力约束 机器人对物体施加的力，等于物体对机器人的反作用力。 当反作用力超过机器人基座能提供的最大静摩擦力时，机器人会失稳。 ``` max_reaction = base_weight_kg × G × friction_coef ``` --- ## 支持的动作 & 物体类型 **JSON 模式核心动作（10+）**： `grasp` / `carry` / `push` / `pull` / `lift` / `place` / `press` / `insert` / `rotate` / `hold` / `release` 等 **自然语言模式（中文 35+ 动词）**： 抓态类 + 持态类 + 复合类 **物体类型（7种）**： `rigid`（刚性）/ `semi_rigid`（半刚性）/ `flexible`（柔性）/ `fragile`（易碎）/ `fluid`（液体）/ `human`（人体）/ `heavy`（重物） --- ## ISO 标准参考 - **ISO 10218-1/2** — 工业机器人安全标准（设计参考） - **ISO/TS 15066** — 协作机器人技术规范（设计参考） > 注：本产品为软件中间件，ISO 标准为设计层面的对齐与参考，非第三方认证级合规声明。 --- ## 与 VLA 模型的关系 ``` 用户指令 │ ▼ ┌──────────┐ 动作+参数 ┌──────────────────┐ │ VLA 模型 │ ────────────────► │ Safety Engine V4 │ │（语义/规划）│ │ （物理安全守门员） │ └──────────┘ ◄──────────────── └──────────────────┘ │ PASS/修正建议 │ ▼ │ 动作执行 ◄───────────────────────────┘ ``` - VLA 模型负责**理解意图、规划动作** - Safety Engine 负责**校验动作的物理安全性** - 两层各司其职，互补不重叠 --- ## 部署 ### 边缘设备 纯 Python 标准库实现，无外部依赖，可直接部署到： - 机器人控制器（ARM / x86） - 边缘计算设备（Jetson、RK3588 等） - 工控机 / PLC 上位机 ### 集成方式 ```python # 方式1：直接嵌入 from safety_engine import SafetyEngineV4 engine = SafetyEngineV4() result = engine.check_command(action, obj, params) # 方式2：封装为 HTTP 服务 # 方式3：编译为 C 扩展（Cython / Nuitka） ``` --- ## API 参考 ### SafetyEngineV4 主引擎类，提供两种输入模式。 #### `__init__(self, verb_db=None, object_db=None, action_rules=None, rules=None)` 初始化引擎。所有参数均可选，不传则使用内置默认值。 | 参数 | 类型 | 说明 | |------|------|------| | `verb_db` | `Optional[Dict]` | 自定义动词库字典 | | `object_db` | `Optional[Dict]` | 自定义物体属性库字典 | | `action_rules` | `Optional[Dict]` | 自定义动作规则表字典 | | `rules` | `Optional[SafetyRules]` | 自定义全局安全规则 | #### `from_config(verb_db_path=None, object_db_path=None, action_rules_path=None, rules=None)` 类方法，从 JSON 文件加载配置数据并创建引擎实例。 ```python engine = SafetyEngineV4.from_config( verb_db_path="config/verbs.json", action_rules_path="config/rules.json", ) ``` #### `check_command(self, action, obj, params=None, robot=None, object_params=None, context=None) -> Dict` 自然语言模式输入。 | 参数 | 类型 | 说明 | |------|------|------| | `action` | `str` | 动作名称（中文动词，如"抓取"/"推"） | | `obj` | `str` | 目标物体名称 | | `params` | `Optional[Dict]` | 动作参数 `{"force": N, "speed": m/s, ...}` | | `robot` | `Optional[str / Dict]` | 机器人配置：字符串机型名或自定义能力字典 | | `object_params` | `Optional[Dict]` | 自定义物体属性（覆盖内置物体库） | | `context` | `Optional[Dict]` | 上下文 `{"near_human": bool, "fragile": bool, "semantic_score": float}` | 返回：V4Result 字典，含 verdict / risk_level / risk_level_7 / over_ratio / input_warnings 等 20+ 字段。 #### `check_action(self, scene_data, action_data, robot_data) -> Dict` JSON 参数模式输入（生产推荐，性能最优）。 | 参数 | 类型 | 说明 | |------|------|------| | `scene_data` | `Dict` | 场景数据，含 `objects` 列表 | | `action_data` | `Dict` | 动作数据，含 `type` / `force_n` / `velocity_ms` / `target_object` 等 | | `robot_data` | `Dict` | 机器人能力数据 | ### 输入校验（v4.3.0+） 引擎在入口处自动进行输入有效性检查： | 情况 | 处理方式 | |------|----------| | 类型错误（如 params 不是 dict） | `REJECT` + 说明 | | 空值 / None 关键参数 | `REJECT` + 说明 | | 数值