Brainmu-Spike完整推理流程实战:从脉冲重建到1000张图像评测的实战指南
Brainmu-Spike完整推理流程实战:从脉冲重建到1000张图像评测的实战指南
Brainmu-Spike 是北京智源人工智能研究院(BAAI)与北京大学余肇飞团队联合开源的脉冲相机影像重建项目:它把脉冲相机采集的 41 帧二值 spike 数据先经卷积小网络重建为条件图像,再驱动 Brainmu 生成模型 + LoRA 输出干净 RGB 图像,并提供面向 1000 张图像的一键评测脚本与多卡网页界面。本文将带你走通它的完整推理流程。
项目架构一览:两级重建流水线
Brainmu-Spike 的推理分为两级,各自独立、可分开运行:
- 脉冲重建小网络(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; - 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 × 250PNG; - 参数:
--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 × 250PNG,大小不符会直接报错; - 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 图像到完整评测报告的实战路线。