Brainmu-Spike完整推理流程实战:从脉冲重建到1000张图像评测的实战指南

原创2026-10-20 14:16:45751 阅读
文章标签:人工智能计算机视觉图像处理大模型微调

Brainmu-Spike完整推理流程实战:从脉冲重建到1000张图像评测的实战指南

Brainmu-Spike 是北京智源人工智能研究院(BAAI)与北京大学余肇飞团队联合开源的脉冲相机影像重建项目:它把脉冲相机采集的 41 帧二值 spike 数据先经卷积小网络重建为条件图像,再驱动 Brainmu 生成模型 + LoRA 输出干净 RGB 图像,并提供面向 1000 张图像的一键评测脚本与多卡网页界面。本文将带你走通它的完整推理流程。

项目架构一览:两级重建流水线

Brainmu-Spike 的推理分为两级,各自独立、可分开运行:

  1. 脉冲重建小网络(SpikeConvFrontend):仅 180,705 个参数的卷积栈(41→64→128→64→16→1 通道,3×3 卷积 + ReLU),把 41 × 250 × 400 的二值 spike 序列重建为单张灰度条件图像。结构定义在 config.json,权重为 model.safetensors,网络实现见 src/code/train_recon.py;
  2. Brainmu 生成阶段(可选):以条件图像为输入,配合固定提示词 Restore the clean image. 和 LoRA 适配器,采样 12 步生成最终 RGB 图像。推理参数(seed、CFG 强度等)固化在 src/configs/inference.json 与 config.json 中,保证可复现。

提示:根目录权重只包含脉冲重建卷积模块;基础大模型与 LoRA 权重未随仓库发布,运行完整流程前需要自行准备这两部分权重。

一键安装环境:GPU 与轻量两条路线

项目要求 Linux + NVIDIA GPU,并使用 uv 管理环境。完整脚本见 src/scripts/setup_uv.sh,在仓库根目录执行:

bash src/scripts/setup_uv.sh

脚本会创建 src/.venv(Python 3.12),安装 PyTorch 2.11.0 + CUDA 13.0 构建、torchvision 0.26.0,并本地编译 FlashAttention 2.8.3.post1;其余依赖来自 src/requirements.txt。注意它不会覆盖已有环境,已有兼容环境可通过环境变量 BRAINMU_ENV 指定。

如果你只想跑第一级小网络,则不需要 GPU 和 FlashAttention:按 src/USAGE.md 的轻量说明,仅安装 CPU 版 torch 及几个依赖即可,对新手是最友好的上手路径。

脉冲重建小网络推理:CPU 也能跑的快速验证 🚀

小网络入口为 src/scripts/infer_frontend.py,它读取根目录的配置与权重,不加载任何大模型。在仓库根目录执行:

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

输入输出约定:

  • 输入:每个 .dat 文件是 41 × 250 × 400 的二值序列(little-bit 打包,共 512,500 字节),读取时沿高度翻转;GT 为同名的 400 × 250 PNG;
  • 参数:--gt-dir 可省略(省略时只出图、不算指标);--limit 3 只跑排序后前 3 张,适合试跑;GPU 环境改 --device cuda:0;
  • 输出:prediction/ 下的重建 PNG,提供 GT 时另附逐图 PSNR/SSIM 及平均值;
  • 权重会做 SHA256 校验,防止文件损坏或被篡改,输出目录必须是全新的。

完整流程推理:1000 张图像评测一条命令搞定

准备齐基础模型、LoRA 和测试数据后,激活 src/.venv,用一键脚本 src/scripts/test.sh(内部调用 src/scripts/infer.py):

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"

默认检查并评测 1,000 对数据,运行过程逐张打印 PSNR/SSIM,全部完成后输出平均值。

常用参数速查

参数 作用
--check-only 只校验文件与数据,不加载模型、不占 GPU,适合先体检
--expected-count N 强制要求恰好 N 对数据,防止拿错测试集
--expected-count 0 --limit 3 对排序后前三张做小规模试运行
--prompt 自定义提示词(默认 Restore the clean image.)

输出目录都生成了什么?

每次运行使用全新输出目录,内容完整、便于复盘:

文件或目录 内容
condition/ 卷积模块生成的条件图像
prediction/ Brainmu 重建出的 RGB 图像
metrics.csv 逐样本 PSNR/SSIM
metrics.json 已完成数量、平均指标、运行状态
dataset_manifest.json 输入文件清单及内容 SHA256
run_config.json 推理参数、包版本与环境指纹

只有 status=complete 且完成数量等于请求数量,才代表评测真正跑完。评测口径为:预测图转灰度、归一化到 <a href="https://link.gitcode.com/i/600e1fd9b0c3dc074fb25a9c07706679" target="_blank">0,1],逐图 PSNR 取平均;SSIM 使用 11×11 高斯窗口(σ=1.5)、不裁剪边界;GT 会按预测尺寸缩放。指标实现见 [src/ui/engine.py 与 src/code/infer_brainmu_lora.py。

⚠️ 请务必使用独立测试数据:程序不会自动检测训练/测试集重叠,混用会高估指标。

网页演示:1/2/4/8 卡并行评测

不想敲命令?项目自带网页测试台(前端为 src/ui/index.html,调度逻辑见 src/ui/multi_gpu.py):

source src/.venv/bin/activate
bash src/scripts/start_ui.sh

打开 http://127.0.0.1:8997,界面分三步走:加载权重 → 加载 1,000 对测试数据 → 开始评测,还能在页面里查看输入 spike 动图与逐图结果,默认 8 卡并行(每卡 125 张),seed 按全局样本序号固定,保证与命令行结果一致。远程部署时用两条 SSH 端口转发(8997 为界面、8998 为媒体服务)即可安全访问;界面没有用户认证,切勿直接暴露公网,Ctrl+C 即停止服务。

数据格式与指标口径速记卡

  • DAT:41 × 250 × 400 二值、little-bit 打包、512,500 字节、高度翻转;
  • GT:同名 400 × 250 PNG,大小不符会直接报错;
  • PSNR:灰度、[0,1] 归一化、逐图计算后取平均;
  • SSIM:11×11 高斯窗口、σ=1.5、无边界裁剪;
  • 推理参数(12 步采样、seed 20260903、cfg_text_scale 4.0、cfg_img_scale 1.5 等)全部固化在配置中,保证 1000 张评测可复现。

写在最后

Brainmu-Spike 把脉冲影像重建拆成了"小网络重建 + 生成模型精修"两级:先用 CPU 友好的小网络脚本验证数据与权重,再上一键脚本完成 1000 张的完整评测,最后还能切到网页界面多卡并行。配合输出目录里的 metrics.csv、dataset_manifest.json 等审计文件,整个流程既好上手又便于复现——这就是从第一张 spike 图像到完整评测报告的实战路线。

登录后查看全文
Brainmu-Spike