如何 10 分钟跑通 Brainmu-SpikeCamera:CPU 轻量环境下的脉冲相机影像重建快速上手教程

原创2026-10-19 23:10:121,825 阅读
文章标签:人工智能计算机视觉微调

如何 10 分钟跑通 Brainmu-SpikeCamera:CPU 轻量环境下的脉冲相机影像重建快速上手教程

Brainmu-SpikeCamera 是北京大学余肇飞团队与北京智源人工智能研究院(BAAI)联合推出的脉冲相机影像重建研究项目:它能把脉冲(事件)相机采集的 DAT 数据流重建为清晰的自然图像。本教程将带你用仅 18 万参数的小网络,在 CPU 轻量环境下 10 分钟内跑通脉冲相机影像重建推理,无需 GPU。

一、30 秒了解 Brainmu-SpikeCamera 📦

脉冲相机(Spike Camera)以极高的时间分辨率捕捉场景中的亮度变化,输出的是一串二值"脉冲"事件,而非传统帧图像。Brainmu-SpikeCamera 分两个阶段处理这些数据:

阶段 说明 硬件要求
① 卷积重建前端(SpikeConvFrontend) 180,705 参数的小网络,直接把脉冲流映射为图像 CPU 即可
② Brainμ 生成阶段(可选) 大模型 + LoRA 微调做精细重建 需 NVIDIA GPU,权重暂未发布

本教程聚焦阶段 ①:它是发布包里开箱即用的部分,根目录的 config.json(网络结构与输入规格)和 model.safetensors(小网络权重)都已就绪。

二、动手前:先认识数据格式

推理脚本对输入有严格的格式约定,提前确认可以少走弯路:

  • 脉冲数据:*.dat 文件,每条包含 41 × 250 × 400 的二值序列(little-bit 打包,共 512,500 字节),读取时会沿高度方向翻转;
  • 真值图像(可选):与 DAT 同名的 PNG,尺寸为 400 × 250。提供后才会计算 PSNR/SSIM 指标;
  • 网络结构与输入参数均由 config.json 声明,权重加载时会校验 SHA256,见 src/code/project_config.py。

三、第一步:搭建 CPU 轻量环境(约 3 分钟)⏱️

完整 GPU 环境需要 PyTorch + FlashAttention,编译较重;而小网络推理只需要 CPU 版 PyTorch,依赖极其精简(完整说明见 src/USAGE.md)。

1. 获取代码

git clone https://gitcode.com/BAAI/Brainmu-SpikeCamera
cd Brainmu-SpikeCamera

2. 创建虚拟环境并安装依赖(需已安装 uv,Python 3.12)

uv venv --python 3.12 .venv
source .venv/bin/activate

# CPU 版 PyTorch + 四个轻量依赖
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install numpy==1.26.4 opencv-python-headless==4.11.0.86 Pillow==11.3.0 safetensors==0.4.5

Windows PowerShell 用户将激活命令换为 .\.venv\Scripts\Activate.ps1。到这里,CPU 轻量环境就完成了——比完整 GPU 环境少了 FlashAttention、transformers 等一长串依赖(见 src/requirements.txt)。

四、第二步:运行脉冲相机影像重建推理(约 2 分钟)

在仓库根目录执行 src/scripts/infer_frontend.py:

python src/scripts/infer_frontend.py \
  --spike-dir /path/to/spike \
  --gt-dir /path/to/gt \
  --output-dir outputs/frontend_test \
  --device cpu

常用参数一览(src/scripts/infer_frontend.py):

参数 必填 说明
--spike-dir ✅ DAT 文件所在目录
--gt-dir ❌ 同名 GT PNG 目录,省略则只出图、不算指标
--output-dir ✅ 输出目录,必须是不存在的空目录
--device ❌ 默认 cpu,有 GPU 可写 cuda:0
--limit 3 ❌ 只跑排序后的前 3 张,快速试错
--config / --checkpoint ❌ 默认读根目录的 config.json 与 model.safetensors

💡 建议:第一次运行加上 --limit 3,几秒内即可验证环境是否配置正确,再跑完整数据集。

五、第三步:查看重建结果 📊

脚本完成后会在输出目录生成三类内容:

文件 内容
prediction/*.png 每张 DAT 对应的重建灰度图像
metrics.csv 逐样本的 PSNR / SSIM(提供 GT 时)
metrics.json 运行状态、完成数量与平均指标

看到终端输出 COMPLETE 3/3; frontend only; output: ...,且 metrics.json 中 status 为 complete,即代表 10 分钟跑通成功!

六、进阶:完整 GPU 流程与网页演示 🔍

小网络只是"前端"。若你准备了基础大模型 + LoRA 权重(暂未随仓库发布),并拥有 NVIDIA GPU,可以走完整重建与评测流程:

# 1. 搭建完整环境(Python 3.12 + CUDA 13.0 + FlashAttention)
bash src/scripts/setup_uv.sh

# 2. 完整推理与评测(默认 1,000 对数据)
CUDA_VISIBLE_DEVICES=0 bash src/scripts/test.sh \
  --model-path /path/to/base_model \
  --adapter /path/to/adapter.safetensors \
  --frontend "$PWD/model.safetensors" \
  --spike-dir /path/to/test/spike \
  --gt-dir /path/to/test/gt \
  --output-dir "$PWD/outputs/test1000"

此外,项目还内置网页演示(src/ui/,支持 1/2/4/8 卡调度):激活 src/.venv 后执行 bash src/scripts/start_ui.sh,打开 http://127.0.0.1:8997 即可在浏览器里加载权重、跑评测。远程部署请通过 SSH 端口转发访问,界面没有用户认证,不要直接暴露公网。

七、常见问题快速解答 ❓

  • 报错 "Use a new output directory":输出目录已存在,换一个空目录即可(程序刻意禁止覆盖旧结果)。
  • 报错 "Default checkpoint SHA256 mismatch":model.safetensors 损坏或不完整,重新获取仓库。
  • 报错 "No DAT files found":检查 --spike-dir 路径,目录下需直接包含 *.dat 文件。
  • 报错 "GT size mismatch":GT 必须与预测尺寸一致(400 × 250),且文件名与 DAT 同名。
  • CPU 上跑得慢?:属正常现象,先用 --limit 3 验证流程;完整数据集建议用 GPU。

八、文件资料速查 📁

资料 说明
README.md 项目总览与环境安装
src/USAGE.md CPU 轻量环境安装与推理说明
config.json / model.safetensors 小网络结构与权重
src/scripts/infer_frontend.py 本教程使用的 CPU 推理入口
src/scripts/setup_uv.sh 完整 GPU 环境安装脚本
src/scripts/test.sh 完整流程评测入口
src/code/ 训练、微调与数据导出代码
src/ui/ 网页演示与多 GPU 调度

从 git clone 到看到第一张重建图像,整个过程只需要一条轻量安装命令和一条推理命令。掌握这套流程后,你便拥有了继续探索事件相机影像重建的起点——祝实验顺利!

登录后查看全文
Brainmu-SpikeCamera