Mini-Nav/docs/experiments.md

# Mini-Nav 实验可行性调研报告

本文档调研当前 Mini-Nav 项目对论文/报告第 6.2–6.8 节实验的支持程度，判断哪些实验可以直接开展，哪些实验只能部分开展，以及还需要补齐哪些代码、脚本或评估流程。

> 调研范围：当前仓库中的 Python 代码、CAM RTL、Cocotb 仿真、benchmark 框架、Scene Graph 原型、Habitat simulator 辅助代码与现有配置。

## 总体结论

| 实验章节 | 当前状态 | 结论 |
|---|---:|---|
| 6.2 CAM 硬件功能正确性验证 | 较完整 | 可以做 |
| 6.3 CAM 硬件性能基准测试 | 有参数化仿真基础 | 部分可做，性能/资源脚本缺失 |
| 6.4 Hash Compressor 检索性能实验 | 有模型和训练代码 | 部分可做，缺系统化评估脚本 |
| 6.5 对象级 Top-K 检索实验 | 有雏形 | 部分可做，但集成问题较多 |
| 6.6 Scene Graph 构建与路径推理实验 | 很弱 | 大多还不能做 |
| 6.7 CAM 加速后的整体框架实验 | 缺软件-硬件桥接与端到端闭环 | 只能做局部模拟 |
| 6.8 消融实验与误差分析 | 依赖前面模块 | 只能做少量离线消融 |

简短判断：**6.2 最成熟；6.3、6.4 可较快补齐；6.5 有雏形但需要修集成；6.6、6.7、6.8 中涉及 Scene Graph 和端到端导航的部分目前还不具备完整实验条件。**

## 项目中已有的关键能力

### CAM 硬件与仿真

相关路径：

- `hw/rtl/cam_top.sv`
- `hw/rtl/cam_noisy.sv`
- `hw/rtl/cam_core_banked.sv`
- `hw/rtl/match_engine_pipeline.sv`
- `hw/rtl/popcount_pipeline.sv`
- `hw/rtl/cam_write_noise.sv`
- `hw/rtl/cam_read_noise.sv`
- `hw/rtl/noise_mask_grouped.sv`
- `hw/rtl/cam_params.svh`
- `hw/sim/model/ref_model.py`
- `hw/sim/sweep_noise.py`
- `hw/sim/tests/*.py`
- `hw/sim/Makefile`
- `.justfile`

已有能力：

- CAM 顶层模块支持写入、查询、匹配输出。
- 参数支持 `NUM_ROWS`、`HASH_BITS`、`LANES`。
- 有写噪声和读噪声模块。
- 有 Python 参考模型用于验证噪声和匹配行为。
- 有 Cocotb/Verilator 测试命令：
  - `just cam-test-py`
  - `just cam-test-all`
  - `just cam-test-module MODULE=...`

### Hash Compressor 与检索

相关路径：

- `mini-nav/compressors/hash_compressor.py`
- `mini-nav/compressors/common.py`
- `mini-nav/compressors/train.py`
- `mini-nav/compressors/pipeline.py`
- `mini-nav/commands/benchmark.py`
- `mini-nav/benchmarks/tasks/retrieval.py`

已有能力：

- `HashCompressor` 支持 DINO token 到二值 hash bits 的映射。
- 默认目标是 512-bit CAM-compatible hash code。
- `HashLoss` 包含 contrastive、distillation、quantization 三类损失。
- `train.py` 可以在 CIFAR-10 上训练 HashCompressor。
- `common.py` 有 Hamming distance / similarity 工具。

### 对象级检索雏形

相关路径：

- `mini-nav/benchmarks/tasks/multi_object_retrieval.py`
- `mini-nav/data_loading/insdet_scenes.py`
- `mini-nav/data_loading/loader.py`
- `mini-nav/compressors/pipeline.py`

已有能力：

- 有多对象检索 benchmark task 雏形。
- 有 object-level vector 建库、query、scene-level aggregation 的基本逻辑。
- `HashPipeline` 支持 OWLv2 文本检测、SAM 分割、DINO 特征、Hash 压缩的流水线设计。

主要问题：

- `multi_object_retrieval.py` 引入 `utils.sam`，但源码中没有 `mini-nav/utils/sam.py`，只有历史 `__pycache__`。
- 普通 benchmark 使用字段 `img`，多对象检索使用字段 `image`，存在数据接口不一致。
- 当前多对象检索主要走 LanceDB 连续向量检索，不是真正的 CAM/hash 检索。

### Scene Graph 与 Habitat 辅助代码

相关路径：

- `mini-nav/scenegraph/objectnode.py`
- `mini-nav/scenegraph/roomnode.py`
- `mini-nav/scenegraph/scenegraph.py`
- `mini-nav/simulator/habitat.py`
- `mini-nav/simulator/views.py`
- `mini-nav/simulator/topdown.py`

已有能力：

- `ObjectNode` 数据结构中已有 `visual_hash`、`semantic_hash` 字段。
- `SimpleSceneGraph` 目前仅保存 `rooms` 和 `objects` 两个字典。
- Habitat 侧有 simulator 创建、随机 navigable point 采图、topdown map 可视化辅助函数。

主要问题：

- 没有 Scene Graph 构建器。
- 没有 room-waypoint-object 拓扑关系。
- 没有检索结果到导航目标点的转换。
- 没有 episode、policy、SPL/success 等导航评估指标。

## 6.2 CAM 硬件功能正确性验证

结论：**可以做。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.2.1 写入与读取功能验证 | 可以做 | `cam_core_banked`、`cam_top` 有 Cocotb 测试 |
| 6.2.2 汉明距离计算验证 | 可以做 | `match_engine_pipeline` 和 ref model 覆盖 bit match / popcount |
| 6.2.3 Top-K 输出正确性验证 | 部分可做 | 当前硬件更接近 Top-1 输出，不是完整 Top-K 列表 |
| 6.2.4 噪声注入功能验证 | 可以做 | 写噪声、读噪声、组合噪声都有测试和参考模型 |

### 已具备内容

- 写入/读取：`hw/rtl/cam_core_banked.sv`、`hw/sim/tests/test_cam_core_banked.py`
- 匹配与 popcount：`hw/rtl/match_engine_pipeline.sv`、`hw/rtl/popcount_pipeline.sv`
- 噪声模块：`hw/rtl/cam_write_noise.sv`、`hw/rtl/cam_read_noise.sv`
- 参考模型：`hw/sim/model/ref_model.py`
- 集成测试：`hw/sim/tests/test_cam_basic.py`

### 还需补齐

1. 如果论文中写的是严格的 **Top-K 硬件输出**，当前 RTL 需要补 Top-K 选择/排序模块，或者明确实验是 Top-1 / Top-K 由软件侧重排实现。
2. 需要统一整理仿真日志、表格和截图，形成可放入论文的实验结果。
3. 建议补一个 `scripts/run_cam_correctness.py` 或类似脚本，一键跑 6.2 所需配置。

## 6.3 CAM 硬件性能基准测试

结论：**部分可做。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.3.1 不同行数 `NUM_ROWS` 下的延迟 | 部分可做 | Makefile 支持参数化，但缺自动 latency 统计 |
| 6.3.2 不同 `HASH_BITS` 下的资源占用 | 暂不能充分做 | 缺 Yosys/Vivado/Quartus 综合脚本 |
| 6.3.3 不同 `LANES` 下的吞吐率 | 部分可做 | RTL 参数支持，但缺吞吐率测量脚本 |
| 6.3.4 与软件检索方法的性能对比 | 还不能完整做 | 缺统一的硬件/软件 benchmark 脚本 |

### 已具备内容

- `hw/sim/Makefile` 支持：
  - `NUM_ROWS`
  - `HASH_BITS`
  - `LANES`
  - `WRITE_NOISE_*`
  - `READ_NOISE_*`
- `.justfile` 已封装远程 Verilator/Cocotb 执行命令。

### 还需补齐

1. CAM 性能 sweep 脚本：
   - 输入：`NUM_ROWS`、`HASH_BITS`、`LANES`
   - 输出：latency cycles、throughput、仿真耗时
2. Cocotb latency 统计：
   - 记录 `query_valid` 到 `result_valid` 的周期数。
3. 综合/资源统计流程：
   - Yosys 或 Vivado TCL。
   - 输出 LUT、FF、BRAM、频率估计。
4. 软件 baseline：
   - Python/NumPy Hamming scan。
   - PyTorch vectorized Hamming。
   - LanceDB/DINO continuous vector retrieval。

## 6.4 Hash Compressor 检索性能实验

结论：**部分可做。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.4.1 原始 DINOv2 特征与二值哈希特征对比 | 可补后做 | DINO 和 Hash 都有，但缺统一评估脚本 |
| 6.4.2 不同哈希长度消融实验 | 可补后做 | `HashCompressor(hash_bits=...)` 支持，但训练脚本固定 512 |
| 6.4.3 不同压缩方法对比实验 | 暂不能做 | 目前只有一种 MLP HashCompressor，无 PCA/随机投影/ITQ/LSH baseline |
| 6.4.4 相似度保持能力分析 | 可补后做 | 有 DINO embedding 和 hash similarity，缺相关性分析脚本 |

### 已具备内容

- `HashCompressor.encode()` 可以生成 binary bits。
- `HashCompressor.compute_similarity()` 可以计算 Hamming similarity。
- `HashLoss` 支持相似度蒸馏，有利于做 similarity preservation 分析。
- `train.py` 可训练基础 512-bit compressor。

### 还需补齐

建议新增 `scripts/eval_hash_retrieval.py`，支持：

- DINO baseline vs Hash baseline。
- `hash_bits = 64 / 128 / 256 / 512`。
- Recall@K、mAP、query latency。
- DINO cosine similarity 与 Hash Hamming similarity 的 Spearman/Pearson 相关性。
- storage compression ratio。

如果要做 6.4.3，需要新增压缩 baseline：

- random projection + sign。
- PCA + sign。
- LSH。
- ITQ 或简化二值量化方法。

## 6.5 对象级 Top-K 检索实验

结论：**部分可做，但当前不能顺畅跑完整实验。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.5.1 图像查询实验 | 部分可做 | 有 object retrieval 框架，但需修 `utils.sam` 和字段兼容 |
| 6.5.2 文本类别查询实验 | 部分可做 | `HashPipeline` 支持 OWLv2 text labels，但 benchmark 未集成 |
| 6.5.3 多视角对象特征融合实验 | 暂不能做 | 没有 object tracking / multi-view merge / feature aggregation |
| 6.5.4 类别过滤与重排序实验 | 只有基础 | 有 mask filtering；类别级过滤和重排序逻辑还需补 |

### 已具备内容

- `multi_object_retrieval.py` 有对象级检索任务结构。
- `data_loading/loader.py` 能加载带 bbox/category 的 InsDet scene 数据。
- `HashPipeline` 支持文本标签驱动的 OWLv2 检测。

### 主要问题

1. `utils.sam` 缺失。
2. `img` / `image` 字段不一致。
3. 数据库 schema 与 object-level retrieval 的 schema 需要和 runner 对齐。
4. 当前 object retrieval 不是 hash/CAM 检索。
5. 缺类别过滤、重排序、多视角融合的正式评估接口。

### 还需补齐

1. 补 `mini-nav/utils/sam.py`，或改为复用 `compressors/model_loader.py` 与 `compressors/proposal`。
2. 统一 benchmark dataset item 字段。
3. 给 object retrieval 增加三种模式：
   - DINO continuous vector。
   - Hash/Hamming。
   - CAM/ref_model Hamming。
4. 增加 category filter 与 rerank 开关。
5. 多视角融合需要新增 object association 和 feature aggregation。

## 6.6 Scene Graph 构建与路径推理实验

结论：**大部分还不能做。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.6.1 ObjectNode 构建质量验证 | 只能做静态/伪数据 | 有数据结构，无自动构建流程 |
| 6.6.2 房间层与 waypoint 层关系验证 | 不能做 | 没有 waypoint node / room-waypoint graph |
| 6.6.3 检索结果到导航目标点转换实验 | 不能做 | 没有 object → navigable point / goal pose 映射 |
| 6.6.4 基于 Scene Graph 的路径生成实验 | 不能做 | 没有 graph search / Habitat path planner 封装 |

### 已具备内容

- `ObjectNode` 能存储 object id、room id、position、visual hash、semantic hash。
- `RoomNode` 和 `SimpleSceneGraph` 是极简数据结构。
- Habitat simulator helper 可以采集场景图像和 topdown map。

### 还需补齐

1. SceneGraph builder：
   - 输入多视角图像、检测结果、相机位姿。
   - 输出 ObjectNode、RoomNode、WaypointNode。
2. 多视角 object association：
   - 判断不同视角中同一物体。
   - 合并位置和 hash 特征。
3. Waypoint graph：
   - 房间节点、waypoint 节点、object 节点关系。
4. Path planning：
   - 检索结果转 target pose。
   - target pose 转 Habitat shortest path 或自定义 graph path。

## 6.7 CAM 加速后的整体框架实验

结论：**端到端还不能做；局部对比可以做。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.7.1 无 CAM 与加入 CAM 的检索延迟对比 | 可补脚本后做局部实验 | 可用 Python CAM ref model 模拟，但无硬件级整体接入 |
| 6.7.2 无 Scene Graph 与加入 Scene Graph 的目标选择对比 | 不能做 | Scene Graph 目标选择逻辑不足 |
| 6.7.3 Top-K 候选切换与失败恢复实验 | 不能做 | 没有导航策略/失败恢复机制 |
| 6.7.4 端到端离线闭环实验 | 不能做 | 缺 query → retrieve → goal → plan → evaluate 闭环 |

### 可以先做的局部实验

- DINO/LanceDB 检索延迟 vs Hash/Hamming 检索延迟。
- Python CAM ref model 检索延迟 vs PyTorch Hamming scan。
- 噪声 CAM 对 Top-1 / Top-K 稳定性的影响。

### 还需补齐

1. Hash output 到 CAM/ref_model 的桥接脚本。
2. CAM 检索 API：给定 query hash 和 database hash，返回 Top-K candidate。
3. 整体 pipeline：
   - image/text query
   - object retrieval
   - scene graph rerank
   - target waypoint selection
   - path planning
   - offline evaluation

## 6.8 消融实验与误差分析

结论：**只能做部分离线消融。**

| 小节 | 状态 | 说明 |
|---|---:|---|
| 6.8.1 去除类别过滤 | 可补后做 | 类别过滤还没有完整 pipeline |
| 6.8.2 去除多视角融合 | 不能做 | 多视角融合本身未实现 |
| 6.8.3 去除 Scene Graph 重排序 | 不能做 | Scene Graph rerank 未实现 |
| 6.8.4 CAM 噪声对最终结果的影响 | 可做局部 | 可测对检索结果影响，不能测完整导航最终结果 |
| 6.8.5 失败案例分析 | 可做检索失败分析 | 导航失败案例暂不可做 |

### 可先做的误差分析

- Hash 检索失败案例：query 与 top candidates 可视化。
- CAM 噪声导致 Top-1 改变的案例。
- DINO 与 Hash 排序不一致的案例。
- SAM/OWLv2 分割或检测失败案例。

### 暂不能做的误差分析

- 多视角融合失败原因。
- Scene Graph 重排序失败原因。
- 端到端导航失败恢复分析。

## 推荐实施顺序

### 阶段 1：快速产出可用实验结果

优先完成：

1. 6.2 CAM correctness。
2. 6.3 CAM 仿真性能 sweep。
3. 6.4 DINO vs Hash 检索性能对比。

建议新增脚本：

- `scripts/run_cam_correctness.py`
- `scripts/sweep_cam_perf.py`
- `scripts/eval_hash_retrieval.py`

### 阶段 2：解锁对象级实验

优先修复：

1. `mini-nav/utils/sam.py` 缺失问题。
2. benchmark dataset 字段不一致问题。
3. object-level schema 与 runner 对齐问题。
4. object retrieval 的 hash/CAM 模式。

然后开展：

- 6.5.1 图像查询实验。
- 6.5.2 文本类别查询实验。
- 6.5.4 类别过滤与重排序实验。

### 阶段 3：实现 Scene Graph 与端到端闭环

需要新增核心模块：

1. SceneGraph builder。
2. Waypoint graph。
3. Object-to-goal mapping。
4. Navigation evaluator。
5. Candidate switching / failure recovery。

完成后才能正式开展：

- 6.6 Scene Graph 构建与路径推理。
- 6.7 CAM 加速后的整体框架实验。
- 6.8 中涉及 Scene Graph、导航闭环、多视角融合的消融实验。

## 最小可行实验组合

如果目标是尽快形成一组完整、可信的实验章节，建议先采用以下组合：

1. **CAM 功能正确性**：覆盖 6.2。
2. **CAM 参数化仿真性能**：覆盖 6.3 的一部分。
3. **DINO vs Hash 检索性能**：覆盖 6.4.1。
4. **Hash length ablation**：覆盖 6.4.2。
5. **CAM noise 对检索稳定性的影响**：覆盖 6.2.4、6.8.4 的离线部分。
6. **对象级检索 demo**：修复 `utils.sam` 后覆盖 6.5.1 的基础版本。

这组实验避开了目前尚未实现的 Scene Graph 端到端导航闭环，同时能充分利用当前仓库中已经完成度较高的 CAM 和 HashCompressor 模块。