Flora-Rewarder Terminal 奖励实战：如何给机器人任务打出 1-5 分成败评分
Flora-Rewarder Terminal 奖励实战：如何给机器人任务打出 1-5 分成败评分
Flora-Rewarder 是 NVIDIA 开源的机器人奖励模型，其 Terminal reward（终端奖励）能力会看完一整段机器人任务视频，直接给出 1-5 的成败评分：1 = 完全失败，5 = 完全成功。这篇实战教程带你用内置的 batch_utils 脚本跑通评分流程：从安装环境、准备任务输入，到读懂评分输出，无需训练模型，一条命令即可出分。
什么是 Terminal Reward：机器人任务的 1-5 分成败评分
Flora-Rewarder 一套权重、三种奖励，靠不同的提示词切换能力；其中 terminal 最直观——给整个任务片段（episode）打一个"成败分"：
| 评分 | 含义 |
|---|---|
| 1 | 完全失败（complete failure） |
| 2 - 4 | 介于完全失败与完全成功之间的分级 |
| 5 | 完全成功（complete success） |
模型只依据视频中可见内容打分，输出格式被正则约束为严格的 Score: <1-5>，可以直接解析成数字，天然适合自动化流水线：数据集筛选、策略评估、部署监控。
3 步一键安装：跑通评分环境
第 1 步：克隆仓库（模型权重与脚本在同一目录中）：
git clone https://gitcode.com/hf_mirrors/nvidia/Flora-Rewarder
第 2 步：安装依赖（项目已在 Python 3.12 + NVIDIA H100 80GB 上验证）：
pip install -r batch_utils/requirements.txt
第 3 步：在仓库根目录运行脚本，默认加载与 batch_utils/ 相邻的权重；首次运行会编译 GPU 内核，需等几分钟才开始评分。
💡 Terminal reward 单张 GPU 即可；如权重存放在别处，用
--model传入本地目录或仓库 id，或设置环境变量FLORA_REWARDER_REPO。
如何准备机器人任务输入：jobs 文件格式
每个任务一行 JSON，视频路径相对于该文件所在目录：
{"id": "ep001", "task": "Put the cup on the tray.", "videos": ["left_wrist.mp4", "top.mp4", "right_wrist.mp4"]}
两个最容易踩坑的点：
- 视频必须时间同步：同一任务的多个相机视角要相同帧率、相同帧数、同步开始，脚本会做同步校验，不通过直接报错；
- 相机顺序要与训练一致：2 视角 = 左、右；3 视角 = 左、中、右；4 视角 = 顶、前/底、左、右（详见 batch_utils/README.md 中的顺序表）。
可参考示例任务文件 batch_utils/examples/jobs.jsonl，把视频路径换成自己的即可。
最快跑法：单条任务评分命令
不想写批处理文件？直接传视频，一条命令出分：
python -m batch_utils.terminal_reward \
--video left_wrist.mp4 top.mp4 right_wrist.mp4 \
--task "Put the cup on the tray." \
--output terminal.jsonl
主脚本 batch_utils/terminal_reward.py 会自动完成：读取并采样视频帧、把多路相机拼成马赛克帧、生成提示词、解析模型回答（核心逻辑在 batch_utils/core.py）。
帧采样规则：模型到底看了多少帧
Terminal reward 对整个 episode 均匀采样 min(64, floor(10 × 时长秒数)) 帧，向下取偶数、至少 2 帧（实现见 batch_utils/core.py）。也就是说：6 秒的任务约看 60 帧，3 分钟的任务看满 64 帧。
务必保留视频原生帧率，不要重采样——模型依赖原始帧时钟来定位绝对时间戳。
批量评分：一次给整个数据集打分
python -m batch_utils.terminal_reward \
--jobs batch_utils/examples/jobs.jsonl \
--output terminal.jsonl
脚本按批处理任务（默认 --max-num-seqs 8 并发），输出文件每任务一行、实时刷盘，中途断开也能保留已完成的结果。输出文件已存在时加 --overwrite 覆盖。
读懂输出：score、probabilities 与 progress 三个关键字段
每条输出包含（字段组装见 batch_utils/terminal_reward.py）：
| 字段 | 含义 |
|---|---|
score |
模型生成的 1-5 评分 |
probabilities |
评分 token 位置的 P(1)…P(5) 分布 |
expected_score |
概率分布的期望值，如 3.2 |
progress |
(expected_score − 1) / 4，归一化到 [0,1] 的进度值 |
rationale |
评分理由（仅 --with-rationale 时出现） |
duration_s / sampled_frames |
视频时长与采样帧数 |
⚠️ 注意：progress 是用于排序的进度值，不是校准过的成功概率，不要当作概率直接使用。概率估算逻辑见 batch_utils/core.py，评分解析见 batch_utils/core.py。
实用参数速查：--with-rationale 与 --dry-run
| 参数 | 用途 |
|---|---|
--with-rationale |
先让模型给一行评分理由再出分，便于人工核对打分依据 |
--dry-run |
只读取视频并打印首个提示词，不加载模型，用来快速验证输入准备 |
--tensor-parallel-size |
张量并行卡数，默认 1（单卡） |
--gpu-memory-utilization |
GPU 显存占用比例，默认 0.88 |
--max-num-seqs |
引擎并发任务数，默认 8 |
例如先空跑验证输入，再正式出分：
python -m batch_utils.terminal_reward --jobs jobs.jsonl --output t.jsonl --dry-run
常见坑位清单
- ❌ 转码或重采样了视频帧率 → 同步校验或帧采样会出错，请保留原始 fps；
- ❌ 相机顺序不对 → 模型只认训练时的视角布局，对照 README 的顺序表排列；
- ⏳ 首次运行特别慢 → 在编译 GPU 内核，属正常现象；
- ⚠️ 商用注意 → 模型遵循 NVIDIA 非商业研究许可，仅限研究与开发用途。
终端奖励能做什么：4 个落地场景
- 数据集质量监控：为新采集的机器人数据自动打分，用
progress排序筛选低质量样本； - 策略评估：策略更新后对固定任务集复跑，对比
score分布变化； - 部署监控：跟踪真实部署中的任务成功率；
- RL 前置标注：需要逐秒动作质量时，再配合同仓库的 dense reward（见 batch_utils/dense_reward.py）。
关键文件索引
| 文件 | 说明 |
|---|---|
| batch_utils/terminal_reward.py | Terminal reward 主脚本 |
| batch_utils/core.py | 提示词、视频处理与评分解析 |
| batch_utils/engine.py | vLLM 推理引擎与通用命令行参数 |
| batch_utils/README.md | 官方用法说明（三种奖励全覆盖） |
| batch_utils/examples/jobs.jsonl | 示例任务文件 |
| batch_utils/requirements.txt | 依赖清单 |
总结
Flora-Rewarder 的 Terminal reward 把"机器人任务完成了吗"变成可复现的 1-5 数字：3 步装好环境、准备一行一个任务的 jobs 文件、一条命令出分，输出同时携带评分、概率分布与可排序的 progress 值。无论是数据筛选、策略评估还是部署监控，这套"视频进、评分出"的流程都能直接跑起来。