【habitat学习一】Habitat-Lab 配置键文档详解（CONFIG_KEYS.md）

该文件是 Habitat-Lab（Facebook Research 开发的 Embodied AI 模拟框架）的核心配置文档，详细定义了 Habitat 配置系统（基于 OmegaConf）中所有可配置参数的层级结构、默认值、取值范围及功能说明。以下内容严格按文件结构展开，覆盖所有细节，包括顶级键（Top-Level Keys）、嵌套子键（Nested Keys）、条件依赖（Conditional Dependencies）、默认值、取值范围及实际用例。

---

1. 文档概述

• 目的：提供 Habitat 配置系统的完整参考，用于定义任务（Task）、环境（Environment）、模拟器（Simulator）、训练器（Trainer）等模块的参数。
• 配置格式：YAML 文件，通过 BASE_TASK_CONFIG_PATH 继承基础配置，并支持动态覆盖。
• 关键特性：
  • 层级化结构：配置键按功能模块分层（如 SIMULATOR.AGENT_0.SENSORS）。
  • 条件依赖：某些键仅在特定父键启用时有效（如 DEPTH_SENSOR 仅在 SENSORS 包含 "DepthSensor" 时生效）。
  • 默认值：所有键均提供默认值，但部分关键键（如 BASE_TASK_CONFIG_PATH）必须显式指定。

---

2. 顶级配置键（Top-Level Keys）

2.1 BASE_TASK_CONFIG_PATH

• 描述：指定基础任务配置文件的路径，作为当前配置的起点。
• 默认值："configs/tasks/pointnav.yaml"
• 必需性：必须提供（无默认值时会报错）。
• 取值范围：
  • 预定义任务配置：pointnav.yaml（点目标导航）、objectnav.yaml（目标导向导航）、rearrange.yaml（物体重排）。
  • 自定义路径：需指向有效的 YAML 配置文件（如 "my_config.yaml"）。
• 示例：

  BASE_TASK_CONFIG_PATH: "configs/tasks/objectnav.yaml"
  

---

2.2 TRAINER

定义训练流程的核心参数。

2.2.1 TRAINER.NUM_UPDATES

• 描述：训练过程中总更新次数（每个更新对应一个批次的梯度更新）。
• 默认值：10000
• 取值范围：正整数（>0）。
• 依赖：需与 TRAINER.LOG_INTERVAL 和 TRAINER.CHECKPOINT_INTERVAL 协调。

2.2.2 TRAINER.LOG_INTERVAL

• 描述：每多少次更新记录一次日志（控制控制台输出频率）。
• 默认值：10
• 取值范围：正整数（>0）。

2.2.3 TRAINER.CHECKPOINT_INTERVAL

• 描述：每多少次更新保存一次模型检查点。
• 默认值：50
• 取值范围：正整数（>0）。

2.2.4 TRAINER.BATCH_SIZE

• 描述：每个训练批次的样本数。
• 默认值：2
• 取值范围：正整数（>0）。
• 硬件依赖：受 GPU 内存限制（增大需更高显存）。

2.2.5 TRAINER.LR

• 描述：优化器的学习率。
• 默认值：0.001
• 取值范围：浮点数（>0）。
• 典型值：1e-4（小规模任务）、5e-3（大规模预训练）。

2.2.6 TRAINER.OPTIMIZER

• 描述：优化器类型。
• 默认值："ADAM"
• 取值范围："ADAM", "SGD", "ADAMW"。
• 扩展配置：
  • 若使用 SGD，需额外指定 TRAINER.MOMENTUM（默认 0.9）。

2.2.7 TRAINER.USE_SYNC_BATCH_NORM

• 描述：是否在分布式训练中使用同步批归一化。
• 默认值：False
• 取值范围：True, False。
• 依赖：仅在多 GPU 训练时生效。

---

2.3 TASK

定义智能体需完成的任务类型及评估指标。

2.3.1 TASK.TYPE

• 描述：任务类型标识符。
• 默认值："Nav-v0"（导航任务）
• 取值范围：
  • "Nav-v0"：通用导航任务。
  • "PointNav-v1"：点目标导航（目标位置为 (x, y, z) 坐标）。
  • "ObjectNav-v1"：目标导向导航（目标为语义对象类别）。
  • "Rearrange-v0"：物体重排任务（如移动物体到指定位置）。

2.3.2 TASK.SUCCESS_DISTANCE

• 描述：判定任务成功的最大允许距离（单位：米）。
• 默认值：0.2
• 取值范围：浮点数（>0）。
• 任务依赖：仅 PointNav 和 ObjectNav 有效。

2.3.3 TASK.MEASUREMENTS

• 描述：任务评估指标列表。
• 默认值：["distance_to_goal", "success", "spl"]
• 取值范围：
  • "distance_to_goal"：智能体到目标的欧氏距离。
  • "success"：是否在 SUCCESS_DISTANCE 内到达目标（二值指标）。
  • "spl"：标准化路径长度（Success weighted by Path Length）。
  • "top_down_map"：生成自上而下的轨迹地图（需额外渲染）。
  • "collisions"：记录碰撞次数（依赖 ENVIRONMENT.ENABLE_COLLISION）。

2.3.4 TASK.SENSORS

• 描述：任务依赖的传感器列表（注意：实际传感器配置在 SIMULATOR.AGENT_0.SENSORS 中定义）。
• 默认值：[]（空列表）
• 取值范围：传感器类名（如 "RgbSensor", "DepthSensor"）。
• 关键点：此处仅声明传感器类型，具体参数需在 SIMULATOR 中配置。

---

2.4 ENVIRONMENT

定义环境运行时的行为约束。

2.4.1 ENVIRONMENT.MAX_EPISODES

• 描述：单次实验的最大 episode 数。
• 默认值：-1（无限）
• 取值范围：整数（-1 表示无限，>0 为有限值）。

2.4.2 ENVIRONMENT.MAX_EPISODE_SECONDS

• 描述：单个 episode 的最大运行时间（秒）。
• 默认值：300
• 取值范围：正整数（>0）。

2.4.3 ENVIRONMENT.MAX_EPISODE_STEPS

• 描述：单个 episode 的最大步数。
• 默认值：500
• 取值范围：正整数（>0）。

2.4.4 ENVIRONMENT.ENABLE_COLLISION

• 描述：是否启用碰撞检测。
• 默认值：True
• 取值范围：True, False。
• 依赖：若启用，TASK.MEASUREMENTS 中的 "collisions" 才会记录数据。

---

2.5 SIMULATOR

定义模拟器及智能体的传感器、场景等参数。

2.5.1 SIMULATOR.SCENE

• 描述：加载的 3D 场景文件路径。
• 默认值："data/scene_datasets/habitat-test-scenes/van-gogh-room.glb"
• 取值范围：有效的 .glb 或 .basis 场景文件路径。
• 依赖：需与 DATASET.CONTENT_SCENES 匹配。

2.5.2 SIMULATOR.AGENT_0

智能体 0 的配置（支持多智能体，但默认仅 AGENT_0）。

2.5.2.1 SIMULATOR.AGENT_0.SENSORS

• 描述：智能体搭载的传感器列表。
• 默认值：["RgbSensor"]
• 取值范围：
  • "RgbSensor"：RGB 相机。
  • "DepthSensor"：深度相机。
  • "SemanticSensor"：语义分割相机（需场景含语义标注）。
  • "EquirectangularSensor"：等距长方体投影传感器（全景相机）。

2.5.2.2 SIMULATOR.AGENT_0.HEIGHT & WIDTH

• 描述：传感器输出图像的高度和宽度（像素）。
• 默认值：HEIGHT=224, WIDTH=224
• 取值范围：正整数（>0）。
• 约束：若启用 SemanticSensor，需确保场景有对应分辨率的语义标注。

2.5.2.3 SIMULATOR.AGENT_0.ROTATION

• 描述：智能体初始朝向（四元数 [x, y, z, w]）。
• 默认值：[0, 0, 0, 1]（朝向正前方）
• 取值范围：有效四元数。

2.5.3 SIMULATOR.HABITAT_SIM_V0

Habitat-Sim 的底层参数。

2.5.3.1 SIMULATOR.HABITAT_SIM_V0.GPU_DEVICE_ID

• 描述：用于渲染的 GPU 设备 ID。
• 默认值：0
• 取值范围：非负整数（需与系统 GPU 数量匹配）。

2.5.3.2 SIMULATOR.HABITAT_SIM_V0.ALLOW_SLIDING

• 描述：是否允许智能体在斜坡上滑动。
• 默认值：True
• 取值范围：True, False。

---

2.6 DATASET

定义数据集来源及划分。

2.6.1 DATASET.TYPE

• 描述：数据集类型标识符。
• 默认值："PointNav-v1"
• 取值范围：
  • "PointNav-v1"：点目标导航数据集。
  • "ObjectNav-v1"：目标导向导航数据集。
  • "RearrangeDataset-v0"：物体重排数据集。

2.6.2 DATASET.SPLIT

• 描述：数据集划分（训练/验证/测试）。
• 默认值："train"
• 取值范围："train", "val", "test"。

2.6.3 DATASET.CONTENT_SCENES

• 描述：加载的场景列表。
• 默认值：["*"]（加载所有场景）
• 取值范围：
  • ["*"]：通配符加载全部。
  • ["scene_01", "scene_02"]：指定场景列表。
  • []：不加载任何场景（需手动指定 SIMULATOR.SCENE）。

2.6.4 DATASET.DATA_PATH

• 描述：数据集文件的路径模板。
• 默认值："data/datasets/pointnav/habitat-test-scenes/v1/{split}/{split}.json.gz"
• 格式要求：必须包含 {split} 占位符（自动替换为 DATASET.SPLIT）。

---

2.7 CHECKPOINT

检查点管理参数。

2.7.1 CHECKPOINT.CHECKPOINT_FOLDER

• 描述：检查点保存目录。
• 默认值："data/checkpoints"
• 取值范围：有效的文件系统路径。

2.7.2 CHECKPOINT.NUM_CHECKPOINTS

• 描述：保留的检查点最大数量。
• 默认值：50
• 取值范围：正整数（>0）。
• 行为：超出数量时自动删除最旧的检查点。

---

2.8 VIDEO_OPTION

视频记录配置。

2.8.1 VIDEO_OPTION

• 描述：启用的视频记录选项。
• 默认值：[]（空列表）
• 取值范围：
  • "disk"：保存视频到磁盘。
  • "tensorboard"：将视频写入 TensorBoard。
  • "wandb"：将视频上传至 Weights & Biases。

2.8.2 VIDEO_DIR

• 描述：视频保存目录。
• 默认值："data/videos"
• 依赖：仅当 VIDEO_OPTION 包含 "disk" 时生效。

---

2.9 其他关键键

2.9.1 TORCH_GPU_ID

• 描述：PyTorch 使用的 GPU ID。
• 默认值：0
• 取值范围：非负整数。
• 与 SIMULATOR.HABITAT_SIM_V0.GPU_DEVICE_ID 区别：
  • TORCH_GPU_ID：控制神经网络计算的 GPU。
  • SIMULATOR.HABITAT_SIM_V0.GPU_DEVICE_ID：控制场景渲染的 GPU。
  • 推荐设置：两者使用同一 GPU 以避免数据传输开销。

2.9.2 VERBOSE

• 描述：是否启用详细日志输出。
• 默认值：False
• 取值范围：True, False。
• 效果：设为 True 时打印调试信息（如传感器初始化细节）。

2.9.3 EVAL_CKPT_PATH_DIR

• 描述：评估时加载的检查点路径。
• 默认值：""（空字符串）
• 用例：指定后跳过训练，直接加载模型进行评估。
• 示例：

  EVAL_CKPT_PATH_DIR: "data/checkpoints/experiment1/ckpt.100.pth"
  

---

3. 配置继承与覆盖机制

• 继承链：BASE_TASK_CONFIG_PATH → 主配置文件 → 命令行覆盖。
• 覆盖示例：

  python run.py --exp-config=config.yaml TASK.SUCCESS_DISTANCE=0.1 TRAINER.BATCH_SIZE=4
  

• 条件覆盖：仅当父键存在时，子键覆盖才生效（如 SIMULATOR.AGENT_0.SENSORS 必须先存在才能修改 HEIGHT）。

---

4. 典型配置文件结构示例

BASE_TASK_CONFIG_PATH: "configs/tasks/pointnav.yaml"
TRAINER:NUM_UPDATES: 20000BATCH_SIZE: 4LR: 0.0003
TASK:SUCCESS_DISTANCE: 0.1MEASUREMENTS: ["distance_to_goal", "success", "spl", "top_down_map"]
SIMULATOR:AGENT_0:SENSORS: ["RgbSensor", "DepthSensor"]HEIGHT: 256WIDTH: 256HABITAT_SIM_V0:GPU_DEVICE_ID: 0
DATASET:SPLIT: "val"
VIDEO_OPTION: ["disk", "tensorboard"]

---

5. 注意事项与最佳实践

1. 传感器一致性：
   • 若 TASK.SENSORS 包含 "DepthSensor"，必须确保 SIMULATOR.AGENT_0.SENSORS 也包含 "DepthSensor"，否则任务会失败。
2. 内存优化：
   • 增大 TRAINER.BATCH_SIZE 时，需同步调整 SIMULATOR.AGENT_0.HEIGHT/WIDTH 避免 OOM。
3. 分布式训练：
   • 启用 TRAINER.USE_SYNC_BATCH_NORM 时，需通过 torch.distributed 启动多进程训练。
4. 调试技巧：
   • 设置 VERBOSE: True 并检查 SIMULATOR 初始化日志，确认场景和传感器加载正确。
5. 版本兼容性：
   • 配置键可能随 Habitat-Lab 版本变化，需参考对应 Git 提交的文档（本文件对应 main 分支最新提交）。

---

6. 与 Habitat 生态的关联

• Habitat-Sim：SIMULATOR 键直接调用 Habitat-Sim 的 C++ 后端。
• Habitat-Baselines：TRAINER 键与 habitat-baselines 的 RL 训练器深度集成。
• 数据集格式：DATASET.DATA_PATH 需匹配 Habitat Challenge 官方数据集结构。

---

7. 常见错误与解决方案

错误现象	原因	解决方案
Scene file not found	SIMULATOR.SCENE 路径错误	检查 DATASET.CONTENT_SCENES 和场景文件实际位置
Sensor not registered	TASK.SENSORS 与 SIMULATOR.AGENT_0.SENSORS 不一致	确保两者包含相同传感器类型
CUDA out of memory	BATCH_SIZE 过大或图像分辨率过高	降低 BATCH_SIZE 或 HEIGHT/WIDTH
Task metric not computed	TASK.MEASUREMENTS 缺失必要指标	添加 "distance_to_goal" 等基础指标

---

8. 扩展阅读建议

• Habitat-Lab 官方教程：examples/example.py 展示配置加载流程。
• OmegaConf 文档：Habitat 配置系统的底层库（OmegaConf GitHub）。
• 任务定制指南：通过继承 habitat.core.embodied_task.EmbodiedTask 实现新任务。

此文档是 Habitat 配置系统的唯一权威参考，覆盖所有可配置参数及其交互逻辑，适用于从快速实验到大规模分布式训练的全场景需求。