isaac-sim-headless-deployment

Isaac Sim 无窗口（--no-window）使用方法

目的

使用受支持的 CLI 标志和 SimulationApp 模式，在无窗口模式下启动 Isaac Sim，用于批量仿真、自动化数据生成和服务器工作负载。

前提条件

• 已构建的 Isaac Sim（$ISAAC_SIM_DIR 或 _build/linux-x86_64/release）。
• 配备当前驱动程序的 NVIDIA GPU（nvidia-smi）。
• isaac-sim-orchestrator 中定义的 Shell 环境变量约定：$ISAAC_SIM_DIR、$ISAAC_LAB_DIR、$WORKSPACE_DIR。

限制

• 适用于 Isaac Sim 6 / Kit 110，除非某个章节另有说明。
• 不取代 NVIDIA 官方文档，也不涵盖其未支持的边缘情况。

故障排除

错误 / 症状	原因	解决方案
找不到扩展或导入项	$ISAAC_SIM_DIR 配置错误或构建过期	将环境变量指向 _build/linux-x86_64/release，或重新构建
画面全黑或为空	缺少灯光，或渲染模式不是 RTX	添加穹顶灯 / 主灯；确认 RTX / PathTracing 设置
加载 Stage 或首次渲染时卡住	MDL 编译或 Stage 过大	按照 isaac-sim-troubleshooting 中的隔离步骤操作

本技能介绍已构建或已安装的 Isaac Sim 的无头使用方法。 不涵盖 Docker 镜像、容器编排或 CI/CD 配置——这些内容属于封装 Isaac Sim 的部署基础设施，而非本技能的范围。

可用脚本

脚本	用途	参数
scripts/batch_simulation.py	Isaac Sim（Kit 110）的无头批量仿真循环	参见脚本的 --help
scripts/ci_physics_nightly.sh	通过 python.sh 或 Kit CLI 运行 CI 物理专用夜间任务	<test_script.py> [args...]

运行脚本

对于提供技能执行辅助函数的 Agent 运行时，请使用 run_script() 调用辅助函数：

run_script("scripts/batch_simulation.py", args=["--help"])

在已构建的 Isaac Sim 目录中，使用 _build/*/release 下的 ./python.sh（Linux）或 python.bat（Windows）运行同一文件；如果 Shell 辅助脚本不需要模拟器，也可以直接执行。

启动模式

1. 有窗口（默认）

./isaac-sim.sh
# Launches isaacsim.exp.full.kit with full UI

2. 无头渲染

用于无头 GPU 渲染（生成图像但不显示窗口）：

# Native headless — uses EGL/Vulkan offscreen
./isaac-sim.sh --no-window

# With explicit display (required on some systems)
DISPLAY=:0 ./isaac-sim.sh --no-window

3. 无头且不渲染

用于纯物理仿真（无视口、不渲染）：

./isaac-sim.sh --no-window --/app/renderer/enabled=false

4. Python 独立脚本

从独立 Python 脚本运行仿真逻辑：

./python.sh my_simulation.py
# Uses Isaac Sim's Python environment with all extensions available

脚本通过 SimulationApp 配置控制无头行为（参见下文的 批量仿真模式）——python.sh 无需使用 --no-window 标志。

5. 使用 Kit CLI 执行脚本

# Default — full Isaac Sim experience with rendering enabled
./kit/kit apps/isaacsim.exp.full.kit --exec "my_script.py"

# Headless physics-only batch
./kit/kit apps/isaacsim.exp.full.kit \
    --no-window \
    --/app/renderer/enabled=false \
    --exec "physics_batch.py"

主要 CLI 标志

标志	描述
--no-window	禁用窗口创建（无头）
--/app/renderer/enabled=false	完全禁用渲染
--/app/window/width=W	设置视口宽度
--/app/window/height=H	设置视口高度
--/app/settings/fabricDefaultStageFrameHistoryCount=N	Fabric 的帧历史记录
--enable EXT_ID	启用指定扩展
--ext-folder PATH	添加扩展搜索路径
--exec SCRIPT	启动时执行脚本
--no-ros-env	跳过 ROS 2 自动加载环境

应用配置

配置文件	用例
isaacsim.exp.full.kit	完整仿真（默认）
isaacsim.exp.full.newton.kit	Newton 物理引擎
isaacsim.exp.full.fabric.kit	Fabric 场景代理
isaacsim.exp.base.kit	最小基础配置（启动更快）
isaacsim.exp.base.python.kit	仅 Python 基础配置
isaacsim.exp.base.python.physics.headless.kit	仅物理的无头模式（CI 夜间任务）
isaacsim.exp.base.zero_delay.kit	零延迟基础配置

仅物理的 CI 夜间运行

对于仅运行物理模拟的 CI 夜间任务（不渲染、不创建窗口），请使用专用 kit 文件：

# Kit CLI mode — self-contained headless physics config
./kit/kit apps/isaacsim.exp.base.python.physics.headless.kit \
    --no-window \
    --/app/renderer/enabled=false \
    --exec "test_physics_batch.py"

对于自行启动 SimulationApp 的独立 Python 脚本，请使用带有禁用渲染器标志的 python.sh：

# python.sh mode — flags passed through to Carbonite/Kit settings
./python.sh test_physics_batch.py \
    --/renderer/enabled=false \
    --/app/window/enabled=false \
    --/app/livestream/enabled=false

kit 文件（isaacsim.exp.base.python.physics.headless.kit）预先配置了：

• renderer.enabled = false — 不启用 GPU 渲染子系统
• app.window.enabled = false — 不创建窗口
• app.livestream.enabled = false — 不进行流式传输
• 禁用所有 UI/视口/操作器扩展
• 禁用所有渲染扩展（omni.hydra.rtx、omni.rtx.*、omni.syntheticdata、omni.replicator.core）
• 采用针对物理模拟优化的循环设置（rateLimitEnabled = false、manualModeEnabled = true、useFixedTimeStepping = true）

包装脚本 scripts/ci_physics_nightly.sh 封装了这两种模式。 设置 CI_KIT_MODE=1 使用 Kit CLI；不设置则使用 python.sh（默认）。

批量模拟模式

规范的无头启动模式位于：

• source/standalone_examples/api/isaacsim.simulation_app/hello_world.py（最简示例）
• source/standalone_examples/api/isaacsim.simulation_app/load_stage.py（打开场景并运行步进循环，支持 --test 模式）

对于包含 N 个回合的批量驱动程序，可将该启动流程封装在 Python 的 for episode in range(N) 循环中。请使用当前 API：

• isaacsim.core.experimental.utils.stage 用于打开场景／等待加载完成
• isaacsim.core.simulation_manager.SimulationManager.setup_simulation(dt=..., device=...) 用于配置物理模拟
• isaacsim.core.experimental.utils.app（enable_extension、play、stop、update_app）用于驱动循环

骨架代码（改写自 load_stage.py，并针对批量处理进行了调整）：

run_batch_simulation(scene_path, num_episodes, steps_per_episode, dt, device) — 无头 SimulationApp 循环，可打开 USD、等待加载、设置物理模拟、运行步进并在每个回合结束时停止。

参见 scripts/batch_simulation.py。

避免使用旧版 isaacsim.core.api.World／isaacsim.core.utils.stage 路径——它们在 Kit 110 中已弃用。

**迁移：**参见 扩展重命名，了解 omni.isaac.* → isaacsim.* 的映射，其中涵盖 omni.isaac.core、omni.isaac.utils 等扩展。

批量／无头运行的性能调优

仅运行物理模拟（最快）

config = {"headless": True, "renderer": None}
# In step loop:
world.step(render=False)

**吞吐量：**根据场景复杂度，可达到实时速度的 10 至 50 倍。

内存管理

• **在各回合之间清理场景：**使用 world.clear() 并进行垃圾回收
• **使用可实例化资产：**在 config.yaml 中设置 make_instanceable: true
• **监控 GPU 内存：**使用 nvidia-smi — 如果未正确清理场景，Kit 会发生内存泄漏
• **GB10（Jetson）：**最多约 3.5 万个 prim，共享内存为 16GB — 请降低场景复杂度

已知问题（Kit 110）

• 无头视口需要 DISPLAY=:0：在某些 GPU 配置上，Kit 110 运行复杂场景时需要此设置
• 部分配置下，不设置 DISPLAY 时视口无法初始化：请使用 --no-window 和离屏渲染
• **CUDA 显存不足（OOM）：**使用 nvidia-smi 进行监控，将 GPU VRAM 使用率控制在 90% 以下
• **启动时间：**冷启动约需 30 至 60 秒；交互式批量处理请使用持久进程
• **Newton 物理模拟与 torch 冲突：**物理模拟稳定之前，切勿导入 torch