StanfordVL/BEHAVIOR-1K · 上手攻略

仓库：StanfordVL/BEHAVIOR-1K
链接：https://github.com/StanfordVL/BEHAVIOR-1K
分类：engineering / ai / embodied-ai / benchmark
作者：spark
更新：2026-10-29

0. 自检清单（三证）

[x] GitHub URL（已 fetch README raw + behavior.stanford.edu 的 installation / quickstart / evaluation 三页）
[x] README 子模块 anchor：monorepo 含 OmniGibson/、bddl3/、joylo/、asset_pipeline/、datasets/、docker/、eval-jobqueue/、knowledgebase/、docs/
[x] 论文 anchor：arXiv:2403.09227（Li Chengshu 等 35 位作者，2024，末位作者 Li Fei-Fei）；官方引用块在 README 中 verbatim 给出
[x] 版本提示：以 v3.9.3 tag 为准（官方评测文档要求用 v3.9.3 而非更旧的 v3.9.0）

1. 是什么

BEHAVIOR-1K 是一个具身智能仿真基准平台，核心是一套 1,000 个日常家务活动的任务集：扫地、做饭、整理收纳、洗衣、浇花……

独特之处在于任务来源——这 1,000 个活动不是研究员拍脑袋想的，而是从真实人类时间使用调查和偏好研究中选出来的。官方说法是"the first simulation benchmark grounded in real human needs"：先大规模问"你希望机器人替你做什么"，再把答案变成可编程验证的任务。标题里的 "Human-Centered" 就是这意思。

技术上建立在单体仓库上，核心模拟器是 OmniGibson，构建在 NVIDIA Omniverse / Isaac Sim 之上。所以它不是一个纯 Python 包，而是"数据集 + 模拟器 + 任务定义语言 + 评测协议 + 遥操作工具 + 竞赛体系"的完整生态。

约 1784 stars，MIT 许可，Python 为主，成熟度 research。团队来自 Stanford Vision and Learning Lab（核心成员含 Chengshu Li、Wensi Ai、Stef Ren、Cem Gokmen、Ruohan Zhang、Jiajun Wu、Li Fei-Fei）。

2. 解决什么问题

具身智能研究当下的三块硬骨头，BEHAVIOR-1K 各自给了对应答案：

"任务没人做"——基准与真实需求脱节。MimicGen 类的操作任务多是桌面级短程动作，而家庭机器人真正需要的是长时程（long-horizon）移动 + 操作复合任务：走进厨房、找食材、清洗、烹饪、收拾。BEHAVIOR-1K 提供完整活动链，不是单个抓取。
"仿真不真"——感知与物理保真度不足。OmniGibson 的卖点是流体、形变体、透明材质、热效应与物体状态转移：倒了水、烧热、切开、弄脏。"抓取布料"和"抓取刚体"在这里是两种物理问题。
"怎么量化好不好"——评测口径不统一。BEHAVIOR-1K 用 BDDL 定义任务目标，用部分成功率（满足的 goal 谓词数 / 总 goal 谓词数）而非二值成功率评分，并用每任务 200 条人类演示归一化效率指标（模拟时间、底盘行进距离、末端执行器位移）。人类基线不是参考项，是归一化基准。

3. 快速安装

3.1 硬件要求（很硬，别跳过）

项	要求
OS	Ubuntu 22.04+ / Windows 10+
内存	32GB+
GPU	NVIDIA RTX 2070+
显存	8GB+

原因是继承自 NVIDIA Omniverse / Isaac Sim 的依赖链。

3.2 开发式安装（当前唯一推荐路径）

# 克隆最新稳定 release（推荐）
git clone -b v3.9.3 https://github.com/StanfordVL/BEHAVIOR-1K.git
cd BEHAVIOR-1K

# 完整安装（所有组件）
./setup.sh --new-env --omnigibson --bddl --joylo --dataset --eval --primitives

# 只要核心组件（不含评测与遥操作）
./setup.sh --new-env --omnigibson --bddl --dataset

# 无头/自动化安装（自动接受 Conda TOS、NVIDIA Isaac Sim EULA、BEHAVIOR 数据集许可）
./setup.sh --new-env --omnigibson --bddl --dataset \
  --accept-conda-tos --accept-nvidia-eula --accept-dataset-tos

./setup.sh --help   # 查看全部选项

Windows 用 PowerShell（需管理员）：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，然后 .\setup.ps1 -NewEnv -OmniGibson -BDDL -JoyLo -Dataset -Eval -Primitives。

激活环境：conda activate behavior

3.3 三个必须知道的安装现状

PyPI 包（omnigibson / bddl / joylo）"即将到来"——官方原文 "are coming soon"。现在没有，别去找。
Docker 安装"暂时不可用"——原文 "temporarily unavailable while we update it for the monorepo structure"。仓库里有 docker/ 和 eval-jobqueue/，但官方安装指南明确指向开发式安装。
安装脚本做了什么：创建名为 behavior 的 conda 环境（带 --new-env 时）、以 editable 模式安装所选组件、下载 Isaac Sim 与 BEHAVIOR 数据集。
用已有 Python 环境：省略 --new-env 即可（./setup.sh --omnigibson --bddl --joylo --dataset）；加 --confirm-no-conda 可跳过 conda 环境确认提示。

3.4 首次运行

# 遥操作一个机器人（--quickstart 自动选场景与机器人）
python -m omnigibson.examples.robots.robot_control_example --quickstart

# 交互式逛新场景
python -m omnigibson.examples.scenes.scene_selector

⚠️ 第一次运行会明显变慢：OmniGibson 首次 import 时 Omniverse 需要一次性启动配置，文档说"可能长达 5 分钟，只会发生一次"。

4. 核心用法

4.1 最小环境程序（官方 Quickstart 骨架）

import omnigibson as og
from omnigibson.macros import gm

cfg = dict()

cfg["scene"] = {"type": "Scene", "floor_plane_visible": True}

cfg["objects"] = [
    {
        "type": "DatasetObject",
        "name": "delicious_apple",
        "category": "apple",
        "model": "agveuv",
        "position": [0, 0, 1.0],
    },
    {
        "type": "PrimitiveObject",
        "name": "incredible_box",
        "primitive_type": "Cube",
        "rgba": [0, 1.0, 1.0, 1.0],
        "scale": [0.5, 0.5, 0.1],
        "fixed_base": True,
        "position": [-1.0, 0, 1.0],
        "orientation": [0, 0, 0.707, 0.707],
    },
    {
        "type": "LightObject",
        "name": "brilliant_light",
        "light_type": "Sphere",
        "intensity": 50000,
        "radius": 0.1,
        "position": [3.0, 3.0, 4.0],
    },
]

cfg["robots"] = [
    {"type": "Fetch", "name": "baby_robot", "obs_modalities": ["rgb", "depth"]},
]

cfg["task"] = {
    "type": "DummyTask",
    "termination_config": dict(),
    "reward_config": dict(),
}

env = og.Environment(cfg)
og.sim.enable_viewer_camera_teleoperation()

for _ in range(10000):
    obs, rew, terminated, truncated, info = env.step(env.action_space.sample())

og.shutdown()

几个必须记住的细节：

所有脚本第一行都应该是 import omnigibson as og——这样才能拿到顶层包的全局变量；gm（global macros）随时可改。
type 字段是类名字符串，配置自动解析成对应类实例；其余关键字参数直接传给构造函数。
物体的 name 必须全局唯一；model 与 category 一起推断数据集中的具体物体，不需要写死 USD 路径。
数据集资产是加密的，只能用 DatasetObject 加载，不能用 USDObject；自己的 USD 文件才用 USDObject。
visual_only: True 表示物体同时受重力和碰撞影响。
没加载机器人时也要给 action：此时 action space 长度为 0，传 [] 或 np.array([]) 即可。

4.2 交互式浏览操作

左键点击 + 拖动 = 旋转视角；滚轮中键 + 拖动 = 平移；滚轮上/下 = 缩放；Shift + 左键点击 + 拖动 = 对选中物体施力。

更精细的控制用 og.sim.enable_viewer_camera_teleoperation()（键盘移动相机、记录相机位姿、动态改灯光），或直接设 og.sim.viewer_camera.set_position_orientation(<POSITION>, <ORIENTATION>)。

4.3 跑 2026 BEHAVIOR Challenge 评测

评测用 websocket 策略服务器协议。先起策略服务器，再从仓库根目录跑评测器：

python -m omnigibson.eval.eval \
  --task-name turning_on_radio \
  --host 127.0.0.1 \
  --port 8000 \
  --instance-indices 0 \
  --num-rollouts 1 \
  --output-dir outputs/b1k_eval \
  --write-video

关键参数：

参数	说明
`--task-name`	BEHAVIOR 任务 id，如 `turning_on_radio`
`--host` / `--port`	websocket 策略服务器地址，默认端口 8000；评测器先轮询 `/healthz` 健康检查
`--policy-endpoints`	每个 `--instance-indices` 对应一个 `HOST:PORT`，顺序一致；用于向量化评测
`--instance-indices`	实例索引。0-19 是公开测试实例，20-39 是隐藏实例。榜单报告用 `0`–`9`
`--num-envs`	逻辑环境数，必须等于 `--instance-indices` 的值个数
`--max-steps`	超时步数；省略则用任务专属默认值 = 1.5 × 人类演示平均长度
`--env-wrapper`	默认 `DefaultWrapper`；官方 RGB+depth 赛道用 `RGBDFullResWrapper`
`--output-dir`	结果目录，JSON 指标写在 `<output-dir>/json/`
`--write-video`	保存 rollout MP4 到 `<output-dir>/videos/`。竞赛提交必需

协议细节（对自定义策略服务器很重要）：

评测器发送扁平化观测，服务器返回 msgpack 编码的响应，含当前步的 action 数组。参考实现：服务器侧 omnigibson/eval/utils/network_utils.py 的 WebsocketPolicyServer，客户端侧 omnigibson.eval.policies.WebsocketPolicy。
首次动作查询有 600 秒宽限期（含 checkpoint 加载、GPU 传输、reset、warm-up、推理），不计入 episode 预算；首次查询失败即该 rollout 失败，不补发免费重试。后续查询也须在 600 秒内完成。
websocket 断连时评测器最多重连 3 次并重发当前观测（不推进仿真步），重连不重置 episode 预算。
多端口评测时，某个端口初始化或首次查询失败不影响其他健康端口继续；失败或超预算的 rollout 得 0 分。

可选的 action-chunk replay（默认关闭）：设 --replay-action-chunk-size K（K > 1），服务器需返回 {"action": ..., "action_chunk": ...}，其中 action_chunk 形状为 (..., L, action_dim)、1 <= L <= K，且 action_chunk[0] 必须严格等于 action。客户端立即返回第一个动作，剩余 L-1 个不再发请求直接执行。只应在服务器返回"从当前观测出发的滚动地平线 chunk"时启用；服务器不返回该字段时客户端会打警告并回退到每步一请求。

4.4 自定义机器人配置

默认加载 OmniGibson/omnigibson/eval/r1pro.yaml。2026 挑战不固定本体，可传 --robot-config：

python -m omnigibson.eval.eval \
  --task-name turning_on_radio \
  --robot-config path/to/my_robot.yaml \
  --host 127.0.0.1 \
  --port 8000

最小配置结构：

model: r1pro          # 小写的 OmniGibson 机器人模型 id；用 model，不要用已废弃的 type
name: robot_r1       # 必填
eval:
  camera_sensor_names:
    left_wrist: robot_r1:left_realsense_link:Camera:0
    right_wrist: robot_r1:right_realsense_link:Camera:0
    head: robot_r1:zed_link:Camera:0
obs_modalities:
  - proprio
  - rgb
controller_config:
  base:
    name: HolonomicBaseJointController
    motor_type: velocity
  arm_left:
    name: JointController
    motor_type: position
  arm_right:
    name: JointController
    motor_type: position

要点：

controller_config 决定动作空间；返回的 action 数组形状必须匹配 robot.action_dim。
评测器会在运行时用任务实例规定的起始位姿覆盖机器人的位置与朝向。
eval.camera_sensor_names 映射相机角色，--write-video 要求 head、left_wrist、right_wrist 三个角色都存在。
eval.use_presampled_pose_key：2025 挑战继承的任务只按机器人模型（fetch、r1、r1pro、stretch、tiago）存了预采样位姿。模型不在此列表的机器人必须设这个字段（如 use_presampled_pose_key: r1pro），否则那些任务环境创建会失败。### 4.5 竞赛赛道规则（2026）

允许的策略输入：RGB + depth + 本体感知。评测期间不允许真值分割、物体状态、目标物体位姿、全场景点云、机器人全局位姿等任何仅模拟器可见的特权信息。训练时可用特权信息，只要评测时不使用；BDDL 任务定义可用且保持一致。

策略方法不限：IL、RL、TAMP 都行，SLAM、LLM 查询等附加组件也允许。若方案依赖外部模型查询 API，参赛者必须自备凭据、配额与推理服务配置。

4.6 评测指标与 2026 竞赛

主指标（排名用）：任务成功分数 Q，在 100 个任务上平均。Q = 满足的 goal BDDL 谓词数 / goal 谓词总数——即部分成功也算分，不是二值。

次要指标（效率，用于打破平局）：模拟总时间、底盘累计行进距离、末端执行器/手的累计位移。这三项用每任务 200 条人类演示的平均值归一化。每个成功 rollout 产出 JSON，含 q_score、time、agent_distance 和归一化效率指标。

赛程与规则：

训练：训练实例与人类演示（每任务 200 条）公开。
自评与上报：每任务另有 20 个配置实例；用前 10 个公开实例（索引 0-9）在每个实例上评测恰好 1 次，用默认的 1.5× 人类平均长度超时。索引 10-19 不进榜单，可当测试集。
仿真不确定性：同一策略不同 rollout 结果可能不同。禁止挑选 rollout 结果或跨运行/实例/任务拼装最好结果来抬高成功率。
最终评测：截止后主办方用另外留出的 10 个隐藏实例（索引 20-39）对榜单前 5 名做最终评测。
奖金池 $11,000：一等奖 $5,000、二等奖 $3,000、三等奖 $2,000、开源优秀奖 $1,000。

5. 典型适用场景

训练长时程家庭任务策略：1000 个活动 + 人类演示 + 任务定义，是 VLA 模型的训练场；
2026 BEHAVIOR Challenge 参赛：提交自定义策略服务器，用官方评测器跑分；
具身 AI 入门：OmniGibson 的 Gym 风格 Python API 上手门槛相对低；
机器人数据集采集：JoyLo 遥操作采集人类演示，官方提供 LeRobot 数据集格式；
仿真保真度研究：需要流体、形变、透明材质、热效应、状态转移的研究。

6. 坑与注意

没有 PyPI 包，没有可用 Docker 安装。官方明确标注 PyPI 包 "are coming soon"、Docker "temporarily unavailable"（适配 monorepo 中）。只能用开发式安装。
硬件门槛真实存在：32GB 内存 + 8GB 显存 + RTX 2070 以上。低于这个跑不动，不是配置问题。
EULA 与数据集许可需显式接受。无头安装加 --accept-nvidia-eula --accept-dataset-tos 会自动接受 NVIDIA Isaac Sim EULA 和 BEHAVIOR 数据集许可——这是法务动作，自己读一遍再决定是否用这个 flag。
首次 import 慢是正常的（一次性 Omniverse 启动配置，可能 5 分钟），不要误判为安装失败反复重装。
GPU 选错会卡在渲染器创建：报 "stuck at HydraEngine rtx failed creating scene renderer" 通常是用了不受支持的 GPU（默认 id 0）。跑 nvidia-smi 看列表，用 export OMNIGIBSON_GPU_ID=<ID> 指定。
CuRobo 安装失败大概率是 CUDA toolkit 配置问题。变通：先 ./setup.sh --new-env --bddl --omnigibson 装不带 primitives 的版本，再在 conda 环境 conda install "cuda-compiler=12.4" "cuda-toolkit=12.4" -c conda-forge，然后把 CUDA_HOME/CUDACXX/CUDA_PATH/CPATH/LIBRARY_PATH/LD_LIBRARY_PATH 指向 $CONDA_PREFIX，最后 ./setup.sh --bddl --omnigibson --primitives。这些环境变量在 curobo 首次 JIT 编译前必须设好。
版本用 v3.9.3，别用 v3.9.0。官方评测文档明确：challenge 评测器与数据集接口在 v3.9.3 里包含主办方将用于评测的最新兼容性修复。
数据集资产加密，只能用 DatasetObject 加载；物体 name 必须全局唯一。
--num-envs 必须等于 --instance-indices 的长度。
首次查询的 600 秒宽限期不是白给的：首次查询失败即该 rollout 失败，没有补发机会。
--write-video 在竞赛里是必需的（rollout 视频是提交材料），且要求 head + 双腕三个相机角色都在 eval.camera_sensor_names 里映射好。
自定义机器人（非 fetch/r1/r1pro/stretch/tiago）必须设 use_presampled_pose_key，否则继承 2025 挑战的任务环境创建会失败。
不要 cherry-pick rollout 结果。规则明文禁止；仿真非确定性是预期现象，官方靠"多任务 × 多实例"稀释。
model 而不是 type：机器人配置里 type 键已废弃，写了不生效。
⚠️ 本文未实机安装运行（写作环境无 NVIDIA GPU）。命令与参数均来自官方 README 与 behavior.stanford.edu 的 installation / quickstart / evaluation 文档原文；数据集实际体积、下载速度与首次编译耗时未实测。
⚠️ 仓库为 monorepo 且活跃开发（仓库卡记录最近提交 2026-10-28），main 分支不稳定，正式复现请固定 tag。

7. 与同类对比

对比 RoboCasa / RoboCasa365：RoboCasa 系列（100 / 365 任务）是桌面单臂操作基准，轻快、社区活跃；BEHAVIOR-1K 是长时程移动+操作，复杂度高一个量级，代价是安装重、渲染慢。选哪个取决于你研究的是"灵巧度"还是"任务链完整性"。
对比 ManiSkill：ManiSkill 主打仿真速度与可扩展 RL 训练（几千环境并行）；BEHAVIOR-1K 主打保真度 + 真实需求驱动的任务设计。要大规模 RL 采样选 ManiSkill，要可信具身评测选 BEHAVIOR-1K。
对比 Habitat：导航/具身探索的老牌基准，BEHAVIOR-1K 直接补上"操作"这一环并提供家庭场景。
对比 BEHAVIOR Robot Suite：同团队的真实机器人套件（2025 年 8 月），提供 sim-and-real 对照；BEHAVIOR-1K 是仿真侧。

硬件成本上，BEHAVIOR-1K 需 Isaac Sim + 8GB 显存（极高），RoboCasa / ManiSkill / Habitat 属"中-低"，Robot Suite 需真机。

一个反向评价："任务来自真实需求"是它的核心资产，但也意味着仿真难度分布是按人的时间分配来的，不是按机器人可学习性来的——某些活动在仿真里非常难，可能超出现有策略水平。

8. 一句话推荐结论

如果你在具身智能领域需要一个有真实人类需求背书、覆盖长时程家庭活动、物理保真度足够、且有完整评测协议和竞赛生态的开源基准，BEHAVIOR-1K 目前几乎无可替代；但请先确认你的机器扛得住 32GB 内存 + 8GB 显存 + Isaac Sim 全家桶，并且务必用 v3.9.3 tag 而不是 main 分支——否则你会在安装阶段就怀疑人生，而不是在算法阶段。