SikongJueluo/Mini-Nav
1
0
Fork 0
mirror of https://github.com/SikongJueluo/Mini-Nav.git synced 2026-07-12 20:15:31 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
42d4a9728d851e5e76229f29a08923a55633b010
Mini-Nav/docs/exps/sw_hw_cam_retrieval_benchmark.md
SikongJueluo 42d4a9728d feat: add hardware retrieval cycle performance measurement 
Add cycle-level performance measurement for hardware CAM retrieval benchmarks
to complement existing quality metrics.

- Add query_topk_once_with_latency with accept→first/last cycle timing
- Add QueryTiming dataclass and summarize_query_timings helper
- Integrate cycle performance into benchmark outputs (CSV + Markdown)
- Log RETRIEVAL_PERF_RESULT with cycles/query and queries/cycle
- Update experiment docs with hardware cycle performance section
- Add unit tests for summarize_query_timings and output writers
2026-05-28 13:05:34 +08:00

214 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 软件/硬件 CAM 检索基准实验总结
**日期**：2026-05-27
**工作区**：`/home/sikongjueluo/Projects/Mini-Nav`
**目标**：对比同一组 CAM 检索数据在硬件仿真与软件汉明距离检索下的检索质量，并记录软件检索速度基线与硬件仿真周期性能。
## 1. 实验配置
### 数据集与哈希配置
| 数据集 | 行数 | 查询数 | 类别数 | 哈希宽度 | Top-K |
|---|---:|---:|---:|---:|---:|
| CIFAR-10 | 512 | 128 | 10 | 512 bit | 5 |
| CIFAR-100 | 512 | 128 | 100 | 512 bit | 5 |
数据文件来自：
- `outputs/cam_retrieval_benchmark/datasets/cifar10_hash512_rows512_queries128.npz`
- `outputs/cam_retrieval_benchmark/datasets/cifar100_hash512_rows512_queries128.npz`
`.npz` 内部字段为：
- `rows_words`
- `row_labels`
- `queries_words`
- `query_labels`
软件基准直接复用硬件基准数据格式，将 little-endian `uint64` words 转为 Python `int` 后执行汉明距离 / XNOR-popcount Top-K 检索，避免通过软件 CAM 时序模拟带来额外开销。
### 运行命令
软件检索速度基准：
```bash
just remote "python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retrieval_benchmark/datasets/cifar10_hash512_rows512_queries128.npz --hash-bits 512 --topk-k 5 --run-id sw_cifar10_hash512_rows512_queries128 && python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retrieval_benchmark/datasets/cifar100_hash512_rows512_queries128.npz --hash-bits 512 --topk-k 5 --run-id sw_cifar100_hash512_rows512_queries128"
```
硬件噪声扫描数据来自远端已有 Cocotb/Verilator 输出与 `docs/exps/cam_retrieval_noise_sweep_*.md`。
硬件检索周期检测命令：
```bash
just cam-test-retrieval-artifact outputs/cam_retrieval_benchmark/datasets/cifar10_hash512_rows512_queries128.npz 512
```
## 2. 软件检索速度与质量
软件路径只计时 Top-K 匹配阶段，不包含 `.npz` 加载、指标聚合和结果写盘。
| 数据集 | Hit@1 | Precision@1 | Std-Recall@1 | Hit@5 | Precision@5 | Std-Recall@5 | Golden Match@5 | ns/query | queries/s |
|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
| CIFAR-10 | 1.000000 | 1.000000 | 0.019531 | 1.000000 | 1.000000 | 0.097656 | 1.000000 | 205835.281 | 4858.254 |
| CIFAR-100 | 0.695312 | 0.695312 | 0.134635 | 0.867188 | 0.462500 | 0.445052 | 1.000000 | 205868.953 | 4857.459 |
观察：
- 两个数据集的软件吞吐都约为 **4.86k queries/s**。
- CIFAR-10 的 Hit@1/Hit@5 均为 1.0，说明在该 512-row 子集上 Top-K 中总能命中同类样本。
- CIFAR-100 的类别更多、每类样本更少，Hit@1 降至 0.695312，Hit@5 为 0.867188。
- `Golden Match@K = 1.0` 表示软件实现与 `hw/sim/model/ref_model.py::match_topk` 的排序结果一致。
## 3. 无噪声硬件仿真与软件基线一致性
硬件无噪声结果来自 `WRITE_NOISE_EN=0` 的 Cocotb/Verilator 检索基准。该结果用于确认硬件 Top-K 输出与参考模型一致。
| 数据集 | 模式 | Hit@1 | Hit@5 | Precision@5 | Std-Recall@5 | Golden Match@1 | Golden Match@5 |
|---|---|---:|---:|---:|---:|---:|---:|
| CIFAR-10 | software-hamming | 1.000000 | 1.000000 | 1.000000 | 0.097656 | 1.000000 | 1.000000 |
| CIFAR-10 | hardware no-noise | 1.000000 | 1.000000 | 1.000000 | 0.097656 | 1.000000 | 1.000000 |
| CIFAR-100 | software-hamming | 0.695312 | 0.867188 | 0.462500 | 0.445052 | 1.000000 | 1.000000 |
| CIFAR-100 | hardware no-noise | 0.695312 | 0.867188 | 0.462500 | 0.445052 | 1.000000 | 1.000000 |
结论：
- 无噪声硬件仿真与软件汉明距离基线在两个数据集上质量指标一致。
- 这说明 `.npz` 数据加载、little-endian word 转换、硬件 CAM 匹配和软件参考模型在当前配置下是对齐的。
## 4. 写噪声对硬件检索质量的影响
硬件噪声实验使用 `WRITE_NOISE_EN=1`，按 10% 步长扫描 `WRITE_NOISE_RATE_NUM / 100`。以下表格保留主要指标 Hit@1、Hit@5 与 Golden Match@K。
### CIFAR-10 噪声扫描
| 写噪声率 | Hit@1 | Hit@5 | Golden Match@1 | Golden Match@5 |
|---:|---:|---:|---:|---:|
| 0% | 1.000000 | 1.000000 | 1.000000 | 1.000000 |
| 10% | 1.000000 | 1.000000 | 0.507812 | 0.000000 |
| 20% | 1.000000 | 1.000000 | 0.234375 | 0.000000 |
| 30% | 0.992188 | 1.000000 | 0.164062 | 0.000000 |
| 40% | 0.984375 | 1.000000 | 0.093750 | 0.000000 |
| 50% | 0.257812 | 0.750000 | 0.023438 | 0.000000 |
| 60% | 0.000000 | 0.015625 | 0.000000 | 0.000000 |
| 70% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
| 80% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
| 90% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
| 100% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
观察：
- CIFAR-10 在 0%–40% 写噪声下 Hit@5 仍保持 1.0。
- Golden Match@5 从 10% 噪声开始降为 0，说明 Top-5 的精确排序对噪声非常敏感。
- 50% 噪声是明显拐点：Hit@1 降至 0.257812，Hit@5 降至 0.75。
- 60% 以后检索基本失效。
### CIFAR-100 噪声扫描
| 写噪声率 | Hit@1 | Hit@5 | Golden Match@1 | Golden Match@5 |
|---:|---:|---:|---:|---:|
| 0% | 0.695312 | 0.867188 | 1.000000 | 1.000000 |
| 10% | 0.585938 | 0.812500 | 0.593750 | 0.023438 |
| 20% | 0.562500 | 0.742188 | 0.460938 | 0.000000 |
| 30% | 0.460938 | 0.640625 | 0.304688 | 0.000000 |
| 40% | 0.234375 | 0.460938 | 0.101562 | 0.000000 |
| 50% | 0.000000 | 0.062500 | 0.000000 | 0.000000 |
| 60% | 0.000000 | 0.007812 | 0.000000 | 0.000000 |
| 70% | 0.000000 | 0.007812 | 0.000000 | 0.000000 |
| 80% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
| 90% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
| 100% | 0.000000 | 0.000000 | 0.000000 | 0.000000 |
观察：
- CIFAR-100 对噪声更敏感：10% 噪声时 Hit@1 从 0.695312 降至 0.585938，Hit@5 从 0.867188 降至 0.812500。
- 40% 噪声时 Hit@5 已降至 0.460938。
- 50% 噪声后检索基本不可用。
- 与 CIFAR-10 相同，Golden Match@5 在低噪声下也迅速接近 0，说明精确排序比类别命中率更脆弱。
## 5. 硬件检索周期性能
本次已将硬件周期检测合并进真实 `.npz` 检索数据集的 Cocotb/Verilator
benchmark。实现位置：
- `hw/sim/tests/top/utils.py::query_topk_once_with_latency`
- `hw/sim/benchmarks/retrieval/test_retrieval_benchmark.py::cam_retrieval_benchmark`
周期口径如下：
| 指标 | 含义 |
|---|---|
| `accept_to_first_result_cycles` | query 被 `query_valid && query_ready` 接受后，到首个 `result_valid` beat 的周期数。 |
| `accept_to_last_result_cycles` | query 被接受后，到 `result_last` 断言的周期数，即完整 Top-K 串行结果输出完成。 |
| `total_query_cycles` | 从拉高 `query_valid` 到 Top-K 输出完成的完整事务周期数。 |
| `cycles_per_query` | 当前报告中的主指标，等于平均 `accept_to_last_result_cycles`。 |
| `queries_per_cycle` | `num_queries / total_query_cycles`，用于观察仿真事务吞吐率。 |
选择 `accept_to_last_result_cycles` 作为主 `cycles_per_query` 的原因是：Top-K
检索只有在串行结果流输出到 `result_last` 后才算完整完成；仅用首个
`result_valid` 会低估实际 Top-K 检索事务成本。
### CIFAR-10 无噪声硬件周期结果
配置：512 rows × 128 queries × 512-bit hash，`TOPK_K=5`，`LANES=8`，
`WRITE_NOISE_EN=0`。
| 数据集 | 模式 | 查询数 | accept→first | accept→last / cycles/query | total query cycles | queries/cycle | 状态 |
|---|---|---:|---:|---:|---:|---:|---|
| CIFAR-10 | hardware no-noise | 128 | 1027.000000 | 1031.000000 | 132096 | 0.000968992 | pass |
对应日志标记：
```text
RETRIEVAL_PERF_RESULT mode=no_noise num_queries=128 cycles_per_query=1031.000000 accept_to_first_result_cycles=1027.000000 accept_to_last_result_cycles=1031.000000 total_query_cycles=132096 queries_per_cycle=0.000968992 status=pass
```
该结果说明：在当前 `NUM_ROWS=512, LANES=8, TOPK_K=5` 的硬件仿真配置下，
一次完整 Top-K 检索事务约为 **1031 cycles/query**。首个结果 beat 约在
1027 cycles 后出现，完整 Top-K 输出额外消耗约 4 个周期。
> 注：以上数据来自 Verilator/Cocotb 仿真，不是 FPGA 板上实测。它可用于
> 架构级周期趋势分析，但不能直接等同于板级频率、吞吐或端到端系统延迟。
## 6. 指标解释
| 指标 | 含义 |
|---|---|
| Hit@K / `recall@k` | 每个 query 的 Top-K 中是否至少出现一个同类样本，然后对 query 取平均。 |
| Precision@K / `macro_precision` | 每个 query 的 Top-K 中同类样本比例，即 `tp / k`，再对 query 取平均。 |
| Std-Recall@K / `retrieval_recall` | 每个 query 检出的同类样本数占数据库中所有同类样本数的比例，即 `tp / |relevant|`，再取平均。 |
| Std-F1@K / `macro_f1` | 使用 Precision@K 与 Std-Recall@K 计算的 F1。 |
| Golden Match@K / `exact_match_rate` | Top-K row index 列表是否与参考模型完全一致。该指标比 Hit@K 更严格。 |
| `ns_per_query` | 软件 Top-K 匹配阶段平均耗时；不含加载和写盘。 |
| `queries_per_second` | 软件 Top-K 匹配阶段吞吐率。 |
| `cycles_per_query` | 硬件仿真中一次完整 Top-K 检索事务的平均周期数，当前采用 accept→last 口径。 |
| `queries_per_cycle` | 硬件仿真中完成 query 数除以总 query 事务周期数。 |
## 7. 当前结论
1. **软件汉明距离基线已可作为硬件 CAM 检索的功能参考。**
在无噪声条件下，硬件仿真和软件基线的质量指标及 Golden Match 均一致。
2. **当前软件基线速度约为 4.86k queries/s。**
该结果来自 Python integer brute-force Hamming scan，数据规模为 512 rows × 128 queries × 512 bits。
3. **硬件检索质量基准现在已经报告 cycles/query。**
在 CIFAR-10 512-row/128-query 无噪声配置下，完整 Top-K 检索为
**1031 cycles/query**，首个结果为 **1027 cycles/query**。
4. **写噪声对精确排序影响显著。**
即使 Hit@K 保持较高，Golden Match@K 也会快速下降，说明噪声首先破坏精确排序，再进一步破坏类别命中。
5. **CIFAR-100 比 CIFAR-10 更能体现检索难度。**
在无噪声下 CIFAR-100 的 Hit@1/Hit@5 分别为 0.695312/0.867188，明显低于 CIFAR-10 的 1.0/1.0，更适合作为后续检索质量对比主数据集。
## 8. 后续建议
1. 对 CIFAR-100 也运行同样的硬件周期检测，补齐与软件质量表同尺度的硬件周期表。
2. 在 `docs/exps` 中继续维护：
- 软件检索速度表；
- 硬件无噪声一致性表；
- 硬件噪声鲁棒性表；
- 硬件 `cycles/query` 表。
3. 对软件基线补充 NumPy/PyTorch vectorized Hamming scan，以区分“朴素 Python baseline”和“优化软件 baseline”。
4. 增加 `NUM_ROWS` sweep：例如 512、1024、2048、4096 rows，观察软件 brute-force scan 的线性增长趋势。
Reference in New Issue View Git Blame Copy Permalink