# SpikeTransOps **Repository Path**: GuoEulerLab/SpikeTransOps ## Basic Information - **Project Name**: SpikeTransOps - **Description**: A GPU-accelerated data conversion operator library, efficiently implementing tensor-stream to spike-stream data conversion. - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: TransOps - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 76 - **Forks**: 44 - **Created**: 2025-11-03 - **Last Updated**: 2026-06-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # SpikeTransOps `SpikeTransOps` 是一个 CUDA 研究原型项目，用于研究一种轻量级推理流水线，该流水线结合了以下三部分： 1. 从稠密激活生成动态 spike； 2. 使用按位 spike 编码实现紧凑的时间维表示； 3. 为 GEMM 路径提供分组 INT8 权重量化。 该仓库有意保持小型化，并专注于 CUDA kernel。当前主要目标是让这些 kernel 的实现、构建、运行、benchmark 和 profiling 都更容易查看和复现。 ## 数据流 完整流水线由两条并行路径组成：激活路径和权重路径。两条路径最终会输入 GEMM。解码和 GEMM 阶段已经存在于代码库中，但在默认 benchmark 流程中处于禁用状态。 ```text 输入 x [B, in_f] float32 — 激活矩阵 w [out_f, in_f] float32 — 权重矩阵 b [out_f] float32 — 偏置向量 ══════════════════════════════════════════════════════ Stream 1 — 激活路径 ══════════════════════════════════════════════════════ Step 1 │ dynamic_spikes_kernel │ 对每一行计算：vth = mean(|x|) / k │ tmp_x[b, f] = round(x[b, f] / vth[b]) │ │ x [B, in_f] → tmp_x [B, in_f] （整数值 spike） │ vth [B] （逐行阈值） │ Step 2 │ GPU 编码预处理 │ (a) find_min_max_kernel │ 扫描 tmp_x，得到全局最小值和最大值 │ (b) CPU 决定变换模式 │ • bidirectional + 全部非负 → half-up transform │ • unidirectional + 存在负数 → 按 min 做 offset │ • 其他情况 → 不做变换 │ (c) transform_and_find_absmax_kernel │ 原地变换 tmp_x， │ 并计算变换后数值的 abs_max │ (d) CPU 计算 max_T = ceil(log2(abs_max + 1)) │ Step 3 │ spike_bitwise_encode_kernel │ 将每个整数值编码为长度为 max_T 的二进制 spike train │ 支持三种模式（见 config.h）： │ • unidirectional standard binary （默认） │ • bidirectional non-complement │ • bidirectional two's complement │ │ tmp_x [B, in_f] → spikes_bitwise [max_T, B, in_f] │ 每个元素为 0 或 ±1 ── （默认流程中禁用）─────────────────────────────── Step 4 │ spike_bitwise_decode_kernel │ spikes_bitwise → decoded_spikes [B, in_f] Step 5 │ dynamic_spikes_reverse_kernel │ decoded_spikes + vth → x_reconstructed [B, in_f] ══════════════════════════════════════════════════════ Stream 2 — 权重路径 （与 Step 2–3 并行运行） ══════════════════════════════════════════════════════ Step A │ compute_scales_kernel │ 对 w 中每一行的每个 w_group_size 列分组： │ scale = absmax(group) / 127 │ │ w [out_f, in_f] → scales [out_f, in_f / w_group_size] Step B │ weight_quantize_kernel_fused │ w_q[i, j] = round(w[i, j] / scale[group(j)]) │ 使用向量化 float4 读取 + shared-memory scale 缓存 │ │ w [out_f, in_f] → w_q [out_f, in_f] （INT8 量化值） ══════════════════════════════════════════════════════ （默认流程中禁用） ══════════════════════════════════════════════════════ Step 6 │ gemm_kernel │ out = x_reconstructed @ w_q^T + b │ out [B, out_f] ``` 默认 benchmark 会分别测量 Step 1–3 和 Step A–B。Step 4–6 被注释掉，以便将计时重点放在编码和量化 kernel 上。 ## 项目亮点 - 针对固定输入宽度 `3584` 优化的 dynamic-spikes kernel - 面向 spike 编码的 GPU 辅助预处理： - 最小值 / 最大值检测； - 可选的 offset 或 half-up transform； - 变换后绝对最大值 reduction - 可配置方向模式的按位 spike 编码 - 使用 GPU 计算 scale 的分组对称 INT8 权重量化 - 支持 batch size sweep 的脚本，并输出 CSV benchmark 汇总 - 用于 kernel profiling 的 Nsight Compute 辅助脚本 ## 仓库状态 当前应将该项目视为一个研究原型，而不是生产级库。 - 默认可执行程序使用 `src/main.cu` 中生成的合成输入、权重和偏置张量。 - 当前活跃执行路径面向 benchmark，重点是测量 kernel 阶段耗时以及端到端运行时间。 - reconstruction 和 GEMM kernel 已存在于代码库中，但在默认 main 流程中被禁用。 - 优化版 dynamic-spikes 路径假设 `in_f == 3584`。 - 默认 `Makefile` 目标架构为 `sm_89`。 这些限制是有意保留的，目的是让仓库在进行 kernel 实验时保持紧凑且易于复现。 ## 环境要求 - Linux - NVIDIA GPU - 带有 `nvcc` 的 CUDA toolkit - GPU 架构需要与 `Makefile` 中的设置兼容 - 默认：`sm_89` Nsight Compute 辅助脚本当前假设 `ncu` 位于： ```bash /usr/local/cuda-12.8/bin/ncu ``` ## 构建 ```bash make ``` 或者使用： ```bash ./run.sh ``` ## 运行 可执行程序接受以下参数： ```text ./spike_quant_gemm ``` 示例： ```bash ./spike_quant_gemm 10 1024 ``` 程序会打印以下部分的计时信息： - `dynamic_spikes_kernel` - `Spike Bitwise Encoding - Kernel Only` - `Spike Bitwise Encoding - Total` - `Weight Quantization` - 多次重复运行的整体平均耗时和总运行时间 ## Benchmark 脚本 `benchmark/` 目录中包含 batch size sweep 辅助脚本： - `run_perf.sh`：端到端计时汇总 - `run_perf_dynamic_spikes.sh`：dynamic-spikes 计时汇总 - `run_perf_spike_encoding.sh`：spike-encoding 计时汇总 - `run_perf_spike_encoding_total.sh`：spike encoding 相对于 total runtime 的统计 - `run_perf_weight_quant.sh`：weight quantization 相对于 total runtime 的统计 典型用法： ```bash cd benchmark bash run_perf.sh ``` CSV 结果会写入 `statistics/` 目录下。 ## 配置开关 主要的编译期配置项位于 `src/config.h`： - `is_bidirectional` - `is_two_complement` - `w_group_size` 当前默认配置为： - unidirectional spike encoding - non-two's-complement mode - 权重量化 group size 为 `128` ## 可复现性说明 benchmark 使用直接在 `src/main.cu` 中初始化的合成张量： - `x[i] = i + 1` - `w[i] = 0.1 * (i + 1)` - `b[i] = 0.5` 这样可以让仓库保持自包含，但也意味着当前测量结果对应的是固定合成 workload，而不是接入真实模型后的输入流水线。