【InternNav】 工程详细分析

InternNav 工程详细分析

一、项目概述

InternNav 是一个基于 PyTorch、Habitat 和 Isaac Sim 的开源具身导航（Embodied Navigation）工具箱，版本 0.3.1。核心贡献是 InternVLA-N1 ------ 一个双系统（Dual-System）视觉语言导航基础模型，具备零样本真实世界泛化能力。

---

二、核心原理：双系统架构（Dual-System）

InternVLA-N1 的设计灵感来自认知科学中的「系统1/系统2」理论：

System 2（慢思考）------ LLM 高层规划器

属性	内容
模型	InternVLAN1ForCausalLM（多模态大语言模型，bfloat16）
输入	自然语言指令 + RGB 历史帧（均匀采样）+ 当前帧
输出	像素目标点 （2D 图像坐标）或 离散动作序列（前进/左转/右转/停止）
职责	理解语言指令，做全局路径规划决策

工作流程（internnav/model/basemodel/internvla_n1/internvla_n1_policy.py）：

1. 维护 RGB 历史帧列表，均匀采样 num_history 帧作为上下文
2. 将图像 + 指令构造为多轮对话输入
3. LLM 生成文本输出，通过正则提取像素坐标或离散动作
4. 若输出像素目标 → 生成 latent 向量传递给 S1

System 1（快思考）------ 扩散策略低层控制器

属性	内容
模型	NavDP（Navigation Diffusion Policy）
输入	S2 的像素目标/latent + 当前 RGB + Depth
输出	连续轨迹预测 → 离散化为动作序列
职责	精确运动控制，将高层目标转化为可执行动作

轨迹离散化逻辑（internnav/model/utils/vln_utils.py）：

x < 0.05m 且 |yaw| < 0.05rad → STOP
否则: 前向位移 > 旋转分量 → 前进, 否则 → 左转/右转

双系统协作模式

在 internnav/agent/internvla_n1_agent.py 中实现两种模式：

┌─────────────────────────────────────────────────┐
│  sync（同步模式）                                │
│  S2 推理 → S1 推理 → 执行 → S2 推理 → ...      │
│  每帧都要 S2 推理，延迟高但精度高                 │
├─────────────────────────────────────────────────┤
│  partial_async（部分异步模式）                    │
│  S2 推理一次 → S1 执行多帧 → S2 再推理           │
│  S2 在独立线程运行，S1 主线程高频执行             │
│  sys2_max_forward_step 控制 S1 最多执行多少步     │
└─────────────────────────────────────────────────┘

异步实现使用 Python threading：

• S2 线程 ：后台持续轮询 s2_input.should_infer，触发时执行推理
• S1 主线程：在 S2 结果就绪后，用 latent 做快速推理
• 通过 threading.Lock 保护共享状态

---

三、工程架构

分层设计

┌────────────────────────────────────────────────────────┐
│                    scripts/ (入口层)                     │
│   train.py │ eval.py │ http_server.py │ notebooks      │
├────────────────────────────────────────────────────────┤
│                  internnav/ (核心库)                     │
│  ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌─────────┐  │
│  │  Agent   │ │Evaluator │ │  Trainer  │ │ Dataset │  │
│  └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬────┘  │
│       │             │             │             │       │
│  ┌────┴─────────────┴─────────────┴─────────────┴────┐ │
│  │              Model (Policy Networks)               │ │
│  │  InternVLA-N1 │ NavDP │ CMA │ RDP │ Seq2Seq      │ │
│  └───────────────────────┬───────────────────────────┘ │
│                          │                              │
│  ┌───────────────────────┴───────────────────────────┐ │
│  │                Env (环境抽象)                       │ │
│  │  Habitat │ InternUtopia │ RealWorld (Agilex/Go2)  │ │
│  └───────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────┘

核心设计模式

1. 注册器模式（Registry Pattern）

所有 Agent、Env、Evaluator 都使用 @cls.register('name') 装饰器注册，然后通过工厂方法实例化：

@Agent.register('internvla_n1')
class InternVLAN1Agent(Agent): ...

# 使用时
agent = Agent.init(agent_cfg)  # 根据配置自动选择具体类

2. 工厂模式（Factory Pattern）

internnav/model/__init__.py 中 get_policy() / get_config() 按名称延迟加载模型：

policy = get_policy('InternVLAN1_Policy')  # → InternVLAN1Net
config = get_config('InternVLAN1_Policy')  # → InternVLAN1ModelConfig

3. 配置驱动（Config-driven）

使用 Pydantic BaseModel 定义配置，支持从 .py 文件动态加载：

spec = importlib.util.spec_from_file_location("eval_config_module", config_path)
config_module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(config_module)
eval_cfg = getattr(config_module, 'eval_cfg')

---

四、核心流程

1. 训练流程（scripts/train/base_train/train.py）

┌─────────┐    ┌──────────────┐    ┌───────────────┐    ┌────────────┐
│ 解析配置 │ → │ 分布式初始化  │ → │ 加载模型+数据 │ → │ HF Trainer │
│ (yaml)  │    │ (NCCL/DDP)   │    │ (checkpoint)  │    │ 训练循环   │
└─────────┘    └──────────────┘    └───────────────┘    └────────────┘

• 分布式训练：PyTorch DDP + DeepSpeed，NCCL 后端
• 优化器：AdamW + Cosine Annealing LR
• 数据格式：LeRobot 格式 或 LMDB 格式
• 数据增强：ColorJitter、Posterize、Sharpness、Autocontrast
• 检查点：每 N epoch 保存，保留最近 8 个

支持的训练模型：

模型	Trainer	特点
InternVLA-N1	QwenVL Trainer	基于 HuggingFace Transformers 微调
NavDP	NavDPTrainer	Diffusion Policy 训练
CMA/CMA+	CMATrainer	Cross-Modal Attention
RDP	RDPTrainer	RNN 方向预测
Seq2Seq	BaseTrainer	序列到序列基线

2. 评估流程（scripts/eval/eval.py）

┌──────────┐    ┌───────────────┐    ┌─────────┐    ┌────────────────┐
│ 加载配置 │ → │ Evaluator.init│ → │ 创建Env │ → │ Agent-Env Loop │
│ (.py)    │    │ (工厂方法)    │    │ + Agent │    │  (评估循环)     │
└──────────┘    └───────────────┘    └─────────┘    └────────────────┘

评估循环核心逻辑：

for episode in dataset:
    env.reset(episode)
    agent.reset()
    while not done:
        obs = env.get_observation()
        action = agent.step(obs)
        env.step(action)
    metrics = env.get_info()  # SR, SPL, nDTW 等

支持 分布式评估（16 GPU 可获 13x 加速）。

3. 推理流程（单步）

                 观测 (RGB + Depth + Instruction)
                              │
                    ┌─────────▼──────────┐
                    │   should_infer_s2?  │
                    └──┬──────────────┬───┘
                  Yes  │              │  No
         ┌─────────────▼───┐    ┌────▼──────────────┐
         │ S2线程: LLM推理  │    │ policy.step_no_infer│
         │ (像素目标/动作)  │    │ (仅更新历史)        │
         └─────────┬───────┘    └────────────────────┘
                   │
         ┌─────────▼───────────┐
         │ 输出类型判断         │
         └──┬──────────────┬───┘
     离散动作│              │像素目标/latent
            │    ┌─────────▼──────────┐
            │    │ S1: Diffusion推理   │
            │    │ latent → 轨迹 → 动作 │
            │    └─────────┬──────────┘
            │              │
         ┌──▼──────────────▼──┐
         │   返回离散动作       │
         │ [0=停, 1=前, 2=左, 3=右]│
         └────────────────────┘

4. 真实世界部署流程（scripts/realworld/）

┌────────────────┐  HTTP  ┌──────────────────┐  Serial  ┌──────────┐
│ Robot (Go2/H1) │ ←────→ │ Flask Server      │ ←──────→ │ Camera   │
│ 电机控制        │        │ InternVLA-N1推理  │          │ RGB+Depth│
└────────────────┘        └──────────────────┘          └──────────┘

Flask 服务器接收 RGB+Depth 图像，运行模型推理，返回离散动作给机器人。

---

五、数据流

训练数据格式

• LeRobot 格式：标准化的机器人学习数据格式，含轨迹数据
• LMDB 格式：高效键值对存储，适合大规模数据
• 数据内容 ：(RGB, Depth, Instruction, Action) 序列对

支持的数据集/Benchmark

任务类型	数据集	描述
VLN-CE	R2R, RxR	连续环境中的语言导航
VLN-PE	VLN-PE	物理环境中的语言导航
VL-LN	对话+轨迹	交互式对话导航
Visual Nav	ClutteredEnv, GRScenes-100	视觉目标导航

---

六、关键技术细节

相机内参计算

fx = (width / 2.0) / tan(hfov / 2.0)
intrinsic = [[fx, 0, cx, 0], [0, fy, cy, 0], [0, 0, 1, 0], [0, 0, 0, 1]]

用于将像素坐标转换为 3D 空间坐标。

深度处理

• 深度值归一化到 0-10m 范围
• 超过阈值（5m）截断：depth[depth > threshold] = threshold
• 用于避障和距离感知

LLM 输出解析

S2 从 LLM 文本输出中通过正则表达式提取：

• 像素坐标：(row, col) 格式
• 离散动作：↑, ←, →, STOP 等符号

---

七、工程亮点

1. 模块解耦：Agent/Model/Env/Evaluator/Trainer 完全独立，可自由组合
2. Sim-to-Real：同一模型可在 Habitat 仿真和真实机器人（Unitree Go2）上运行
3. 异步推理：S2 慢推理与 S1 快推理解耦，提高实时性
4. 分布式支持：训练和评估均支持多 GPU 并行
5. 多模型支持：通过统一接口支持 6 种不同架构的导航模型
6. 配置灵活：Python 文件作为配置，支持任意逻辑和动态计算

---

八、项目目录结构

InternNav/
├── internnav/                      # 主包目录
│   ├── agent/                      # Agent 实现
│   ├── dataset/                    # 数据集加载与处理
│   ├── env/                        # 环境封装
│   ├── evaluator/                  # 评估框架
│   ├── configs/                    # 配置类定义
│   ├── model/                      # 模型实现
│   │   └── basemodel/
│   │       ├── internvla_n1/       # 双系统 VLN 模型
│   │       ├── navdp/             # 扩散导航策略
│   │       ├── cma/               # Cross-Modal Attention
│   │       ├── rdp/               # RNN 方向预测
│   │       └── seq2seq/           # Seq2Seq 基线
│   ├── trainer/                    # 训练代码
│   ├── utils/                      # 工具函数
│   └── habitat_extensions/         # Habitat 扩展
├── scripts/                        # 执行脚本
│   ├── train/                      # 训练脚本
│   ├── eval/                       # 评估脚本
│   ├── realworld/                  # 真实世界部署
│   └── notebooks/                  # Jupyter 演示
├── checkpoints/                    # 预训练权重
├── data/                           # 数据集文件
├── third_party/                    # 外部依赖
├── tests/                          # 测试
├── requirements/                   # 依赖规格
└── docs/                           # 文档

---

总结

InternNav 是一个设计精良的具身导航研究框架，其核心创新是将大语言模型（慢思考/规划）与扩散策略（快执行/控制）结合的双系统架构，通过异步线程实现了高效的实时导航。框架支持从仿真训练到真实机器人部署的完整流程，具备良好的模块化和可扩展性。