| # 0413 当前 Spatial-BEATs 基线总结 |
|
|
| 本文档记录 2026-04-13 时点仓库内当前可复现的 `Spatial-BEATs` 基线状态。 |
| 重点不是回顾全部试错，而是明确： |
|
|
| - 当前应该以哪个 checkpoint / preset 为基线 |
| - 当前模型架构到底是什么 |
| - 当前训练和验证流程如何工作 |
| - 这条线已经证明了什么，没证明什么 |
| - 后续继续改时，哪些地方不要再误改 |
|
|
| 当前本地快照提交： |
|
|
| ```text |
| b782333 snapshot: restore 0410 local_spatial baseline state |
| ``` |
|
|
| ## 1. 当前基线对象 |
|
|
| 当前恢复并确认的基线是： |
|
|
| ```text |
| train_spatial_beats.py --preset ov1_local_spatial |
| ``` |
|
|
| 对应的历史参考 checkpoint 是： |
|
|
| ```text |
| checkpoints/spatial_beats_ov1_local_spatial_run1/best.pt |
| ``` |
|
|
| 这条线对应的设计目标是： |
|
|
| - 用 `W` 通道的 BEATs 路径提供语义时间序列 |
| - 用 `WXYZ + IVxyz` 的 local spatial branch 提供局部空间时间序列 |
| - 两者在 token 时间轴上对齐后相加融合 |
| - 用一个单路 fused temporal token 序列同时做： |
| - clip-level class |
| - direction |
| - distance |
| - 最终 `llm_spatial_tokens` |
|
|
| 这条线不是： |
|
|
| - `semantic_aux_classifier` 双头版本 |
| - 原始 Kaldi fbank W semantic special path 版本 |
| - class/spatial 分别从不同 token 读出的版本 |
|
|
| 这些后续尝试都已经从当前基线中移除。 |
|
|
| ## 2. 当前模型架构 |
|
|
| 当前 `ov1_local_spatial` 的主路径如下： |
|
|
| ```text |
| FOA waveform [B, 4, T] |
| -> SpatialBEATsPreprocessor |
| -> foa_feat [B, 7, T_f, F] |
| channels = [W, X, Y, Z, IVx, IVy, IVz] |
| |
| -> extract_patch_tokens() |
| base path: |
| W_logmel -> original single-channel BEATs patch embedding |
| spatial delta path: |
| 7ch foa_feat -> SpatialDeltaPatchAdapter -> delta_patch_tokens |
| patch_tokens = base_patch_tokens + delta_patch_tokens |
| |
| -> BEATs trunk |
| -> frequency_pool |
| -> TemporalResampler(target_token_rate = 2.5 Hz) |
| -> ShallowTemporalReadout |
| -> semantic_embeddings [B, T_s, D] |
| |
| -> LocalSpatialEncoder(foa_feat) -> local_patch_rate_tokens [B, T_f, D_s] |
| -> LocalSpatialResampler -> local_spatial_tokens [B, T_s, D_s] |
| -> local_spatial_proj: Linear(D_s, D) |
| -> fused_embeddings = LayerNorm(semantic_embeddings + local_update) |
| |
| -> LocalSpatialPredictionHeads(fused_embeddings) |
| -> class pooled token |
| -> spatial pooled token |
| -> pred_class_logits [B, 65] |
| -> pred_direction [B, 3] |
| -> pred_distance [B, 1] |
| |
| -> SpatialTokenProjector(fused_embeddings) |
| -> llm_spatial_tokens [B, T_s, d_llm] |
| ``` |
|
|
| ### 2.1 FOA 前端 |
|
|
| 代码入口： |
|
|
| - [spatial_modules.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/spatial_modules.py) |
| - [spatial_beats.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/spatial_beats.py) |
|
|
| 当前前端行为： |
|
|
| - 输入波形按 DCASE 存储顺序 `[W, Y, Z, X]` |
| - `SpatialBEATsPreprocessor` 内部先重排到 `[W, X, Y, Z]` |
| - 计算： |
| - `WXYZ logmel` |
| - `IVx, IVy, IVz` |
| - 输出 `foa_feat [B, 7, T_f, F]` |
|
|
| 这里仍然是当前基线的一部分。 |
| 也就是说，当前基线不是完全复用原始 `BEATs.py preprocess()`，而是： |
|
|
| - 用自实现 STFT/mel 前端 |
| - 再用 BEATs 统计量做归一化 |
|
|
| 这点非常重要，因为后续很多分类迁移问题都和这里有关。 |
|
|
| ### 2.2 Patch token 构造 |
|
|
| 当前 patch 输入仍然是“W base + 7ch delta”风格： |
|
|
| - `patch_embedding.proj` 只接收 `W_logmel` |
| - `SpatialDeltaPatchAdapter` 从完整 `foa_feat` 生成 patch-level residual update |
| - 最终送入 trunk 的是： |
|
|
| ```text |
| patch_tokens = base_patch_tokens + delta_patch_tokens |
| ``` |
|
|
| 当前 `ov1_local_spatial` preset 中： |
|
|
| - `train_patch_embedding_in_stage1 = False` |
| - `train_spatial_adapter_in_stage1 = False` |
| - `patch_adapter_residual_alpha_init = 0.0` |
| - `patch_adapter_out_proj_scale_init = 0.0` |
|
|
| 也就是说，在这条恢复后的 run1 基线里： |
|
|
| - trunk 冻结 |
| - patch embedding 冻结 |
| - patch delta adapter 也不训练 |
|
|
| 真正训练的是后面的 local spatial 分支和 fused readout。 |
|
|
| ### 2.3 BEATs trunk 路径 |
|
|
| 当前 trunk 保持的是原 BEATs 主干： |
|
|
| - `layer_norm` |
| - `post_extract_proj` |
| - `encoder.pos_conv` |
| - `encoder.layers.*` |
| - `encoder.layer_norm` |
|
|
| 预训练初始化来自： |
|
|
| ```text |
| pretrain_ckpt/BEATs_iter3_plus_AS2M.pt/BEATs_iter3_plus_AS2M.pt |
| ``` |
|
|
| 加载逻辑在： |
|
|
| - [spatial_beats.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/spatial_beats.py) |
|
|
| 当前日志行为应类似： |
|
|
| ```text |
| [SpatialBEATs] Reusing 201 compatible BEATs keys |
| [SpatialBEATs] Reusing original single-channel BEATs patch embedding |
| ``` |
|
|
| ### 2.4 Local spatial 分支 |
|
|
| 当前 spatial branch 是当前基线的核心增量，结构为： |
|
|
| - `LocalSpatialEncoder` |
| - 2D CNN 提取局部多通道空间模式 |
| - 频率池化 |
| - temporal Transformer |
| - `TemporalResampler` |
| - 把 local spatial token 序列重采样到和 semantic token 同样的 `T_s` |
| - `local_spatial_proj` |
| - `Linear(D_s, D)`，小尺度初始化 |
| - `local_spatial_fusion_norm` |
| - `LayerNorm(semantic + local_update)` |
|
|
| 代码位置： |
|
|
| - [spatial_modules.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/spatial_modules.py) |
| - [spatial_beats.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/spatial_beats.py) |
|
|
| ### 2.5 Prediction heads |
|
|
| 当前 `LocalSpatialPredictionHeads` 是 0410 那条线真正使用的版本： |
|
|
| - 输入只有 `fused_tokens` |
| - class 和 spatial 都从同一个 fused sequence 上做 attention pooling |
| - 不是 class 从 semantic token 读、spatial 从 fused token 读的后改版本 |
|
|
| 结构： |
|
|
| ```text |
| fused_tokens [B, T_s, D] |
| -> class_score -> class attention pooling -> class_token |
| -> spatial_score -> spatial attention pooling -> spatial_token |
| |
| class_token -> class_head -> pred_class_logits |
| spatial_token -> direction_head -> pred_direction (normalized) |
| spatial_token -> distance_head -> pred_distance (softplus) |
| ``` |
|
|
| 初始化细节： |
|
|
| - `class_score.weight/bias = 0` |
| - `spatial_score.weight/bias = 0` |
|
|
| 所以初始 attention pooling 等价于均匀 mean-pool。 |
| 这就是为什么它可以比较平滑地接入之前的 class head checkpoint。 |
|
|
| ## 3. 当前 supervision 与 loss |
|
|
| 当前 `ov1_local_spatial` 使用： |
|
|
| ```text |
| cfg.loss.supervision_mode = "mono_ast" |
| ``` |
|
|
| 对应 loss 计算在： |
|
|
| - [spatial_loss.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/spatial_loss.py) |
|
|
| 当前这条线不是 Hungarian slot matching，而是单源 clip-level supervision： |
|
|
| - 每个样本必须只有一个有效源 |
| - 从第一个有效源读取： |
| - class |
| - azimuth |
| - elevation |
| - distance |
|
|
| loss 定义： |
|
|
| ```text |
| loss_cls_aux = cross_entropy(pred_class_logits, cls_target) |
| loss_direction = 1 - cos(pred_direction, gt_direction) |
| loss_dist = smooth_l1(pred_distance, gt_distance) |
| |
| loss_total = |
| lambda_cls_aux * loss_cls_aux |
| + lambda_direction * loss_direction |
| + lambda_dist * loss_dist |
| ``` |
|
|
| 当前 `ov1_local_spatial` 默认权重： |
|
|
| ```text |
| lambda_cls_aux = 1.0 |
| lambda_direction = 12.0 |
| lambda_dist = 2.0 |
| ``` |
|
|
| valid metrics： |
|
|
| - `class_acc` |
| - `azi_mae_deg` |
| - `ele_mae_deg` |
| - `dist_mae` |
|
|
| ### 3.1 Active window mask |
|
|
| 虽然是单源 clip-level readout，这条线仍然会构建弱时间窗 mask： |
|
|
| - `build_primary_source_window_mask()` |
| - 根据 source start/end time 映射到 token 轴 |
| - 作为 `active_window_mask` 提供给 `LocalSpatialPredictionHeads` |
|
|
| 这意味着 pooled class/spatial token 默认更关注标注的 active window，而不是整段所有 token。 |
|
|
| ## 4. 当前训练配置 |
|
|
| 当前恢复后的 `ov1_local_spatial` preset 在： |
|
|
| - [train_spatial_beats.py](/apdcephfs_cq10/share_1603164/user/schmittzhu/code/unilm/beats/train_spatial_beats.py) |
|
|
| 关键配置： |
|
|
| ```text |
| batch_size = 8 |
| num_workers = 4 |
| num_epochs = 20 |
| learning_rate = 1e-4 |
| weight_decay = 0.05 |
| |
| freeze_trunk_in_stage1 = True |
| unfreeze_full_trunk = False |
| train_patch_embedding_in_stage1 = False |
| train_spatial_adapter_in_stage1 = False |
| freeze_projector_by_default = True |
| |
| dataset.max_clip_duration_seconds = 20.0 |
| dataset.crop_mode = "start" |
| |
| best_metric_name = "azi_mae_deg" |
| minimize_best_metric = True |
| class_finetuned_ckpt = checkpoints/beats_ov1_event_cls_head_only/best.pt |
| ``` |
|
|
| 当前最重要的初始化来源有两个： |
|
|
| 1. `BEATs pretrained trunk` |
| 2. `checkpoints/beats_ov1_event_cls_head_only/best.pt` |
|
|
| 第二个 checkpoint 的加载策略是： |
|
|
| ```text |
| beats.patch_embedding.weight -> patch_embedding.proj.weight |
| beats.patch_embedding.bias -> patch_embedding.proj.bias |
| beats.layer_norm.* -> layer_norm.* |
| beats.post_extract_proj.* -> post_extract_proj.* |
| beats.encoder.* -> encoder.* |
| classifier.weight -> local_spatial_prediction_heads.class_head.weight |
| classifier.bias -> local_spatial_prediction_heads.class_head.bias |
| ``` |
|
|
| 所以当前 `ov1_local_spatial` 的初始分类能力，并不是随机的，而是： |
|
|
| - 先来自 W-channel 事件分类 baseline 的 class head |
| - 再接到 fused temporal readout 上 |
|
|
| ## 5. 当前 checkpoint 已证明的结果 |
|
|
| 参考 checkpoint： |
|
|
| ```text |
| checkpoints/spatial_beats_ov1_local_spatial_run1/best.pt |
| ``` |
|
|
| 这条 run 的已知最佳结果是： |
|
|
| ```text |
| best epoch = 7 |
| best metric = azi_mae_deg |
| |
| train: |
| loss_total = 4.0454 |
| loss_cls_aux = 1.3232 |
| loss_direction = 0.1966 |
| loss_dist = 0.1816 |
| class_acc = 0.6184 |
| azi_mae_deg = 24.68 |
| ele_mae_deg = 10.07 |
| dist_mae = 0.465 |
| |
| valid: |
| loss_total = 5.1220 |
| loss_cls_aux = 2.5258 |
| loss_direction = 0.1856 |
| loss_dist = 0.1847 |
| class_acc = 0.3985 |
| azi_mae_deg = 23.52 |
| ele_mae_deg = 9.65 |
| dist_mae = 0.475 |
| ``` |
|
|
| 更关键的是 `epoch_0000` 的行为： |
|
|
| ```text |
| train class_acc ≈ 0.246 |
| val class_acc ≈ 0.244 |
| val azi_mae ≈ 71.49 |
| val ele_mae ≈ 71.54 |
| ``` |
|
|
| 这说明 run1 的初始状态是： |
|
|
| - class 明显高于随机 |
| - 空间一开始很差 |
|
|
| 这正是后续 0413 恢复工作所要回到的行为。 |
|
|
| ## 6. 0413 已排除掉的错误分支 |
|
|
| 为了避免后续再把这条基线改坏，下面这些都已经确认不是当前基线的一部分： |
|
|
| ### 6.1 不是 `semantic_aux_classifier` 版本 |
|
|
| 后面曾尝试： |
|
|
| - 在训练期额外挂一个完全独立的 semantic auxiliary classifier |
| - 让 class loss 不再从 fused token 读 |
|
|
| 结果： |
|
|
| - 这条线改变了初始化行为 |
| - 会让 `Epoch 0` class 接近随机 |
| - 与原始 run1 不一致 |
|
|
| 现在已经从当前基线彻底移除。 |
|
|
| ### 6.2 不是 `use_original_beats_semantic_frontend_for_local_spatial` 版本 |
| |
| 后面曾尝试： |
| |
| - 让 local_spatial 路径里的 semantic branch 改走原始 W-only Kaldi fbank + BEATs |
|
|
| 结果： |
|
|
| - 这条线会明显改变 local_spatial 的初始化分布 |
| - 也是导致后续 “空间一开始很好、class 一开始很差” 的原因之一 |
| |
| 现在已经从当前基线移除。 |
| |
| ### 6.3 不是 class/spatial 分开读不同 token 的版本 |
| |
| 后面曾尝试： |
| |
| - class 从 `semantic_tokens` 池化 |
| - spatial 从 `fused_tokens` 池化 |
|
|
| 这同样改变了 0410 run1 的行为。 |
| 当前已经恢复成： |
|
|
| - class 和 spatial 都从 `fused_tokens` 读 |
|
|
| ## 7. 当前仓库里额外存在但不属于这条基线的内容 |
|
|
| 当前仓库除了 `ov1_local_spatial` 之外，还保留了一些后续研发分支： |
|
|
| - `ov1_ast` |
| - `ov1_pretrunk_ast_*` |
| - `ov123_local_spatial_slot` |
| - `ov123_local_spatial_track` |
| - `ov123_local_spatial_accdoa` |
|
|
| 这些分支仍然在代码里，但它们不是当前这份文档关注的“恢复后的单源 local_spatial 基线”。 |
| |
| 后续如果继续研究 frame-level / slot-level 多源建模，应当： |
| |
| - 把它们视为新的实验线 |
| - 不要再直接污染 `ov1_local_spatial` |
| |
| ## 8. 当前推荐的复现命令 |
| |
| 恢复后的基线复现命令： |
| |
| ```bash |
| CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 torchrun --nproc_per_node=8 --master_port=29531 \ |
| train_spatial_beats.py \ |
| --preset ov1_local_spatial \ |
| --distributed \ |
| --batch-size 8 \ |
| --num-workers 24 \ |
| --num-epochs 20 \ |
| --output-dir checkpoints/spatial_beats_ov1_local_spatial_run1 |
| ``` |
| |
| 如果只想做行为检查，先跑 1 个 epoch 就够： |
| |
| ```bash |
| CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 torchrun --nproc_per_node=8 --master_port=29531 \ |
| train_spatial_beats.py \ |
| --preset ov1_local_spatial \ |
| --distributed \ |
| --batch-size 8 \ |
| --num-workers 24 \ |
| --num-epochs 1 \ |
| --output-dir checkpoints/spatial_beats_ov1_local_spatial_repro_check |
| ``` |
| |
| 判断是否仍在 run1 轨道上的最直接标准： |
| |
| - `Epoch 0 class_acc` 应该明显高于随机 |
| - `Epoch 0 azi/ele` 应该仍然很差 |
| |
| 而不是： |
| |
| - `Epoch 0 class` 接近 0 |
| - `Epoch 0 spatial` 一开始就很好 |
| |
| ## 9. 目前这条线的结论 |
| |
| 当前 `ov1_local_spatial` 基线已经证明： |
| |
| 1. 单路 fused token 架构是能学到空间的。 |
| 2. 这条线能在不动 trunk 的前提下，把 azimuth / elevation / distance 拉下来。 |
| 3. 但它的 class 保持能力有限，最佳 valid `class_acc` 约 `0.40`，明显低于纯 W-channel BEATs 分类 baseline。 |
| 4. 所以这条线当前更适合作为： |
| - “可工作空间基线” |
| - 后续 frame-level spatial 扩展的 warm-start |
| |
| 它还没有证明： |
| |
| 1. class 和 spatial 可以同时都做到强泛化。 |
| 2. fused token 已经足够好，可以直接无脑接 LLM。 |
| |
| ## 10. 后续继续迭代时的建议 |
| |
| 如果以后继续改，不要再直接破坏 `ov1_local_spatial` 这条基线。更稳的方式是： |
| |
| 1. 保留 `ov1_local_spatial` 不动，作为 frozen baseline。 |
| 2. 新实验单独开新 preset。 |
| 3. 新实验优先从： |
| - `checkpoints/spatial_beats_ov1_local_spatial_run1/best.pt` |
| - 或 `DEFAULT_OV1_LOCAL_SPATIAL_INIT` |
| warm-start。 |
| 4. 任何涉及下面这些点的修改，都应视为“新架构”，不要再说和 run1 一样： |
| - semantic aux classifier |
| - 原始 W-BEATs special frontend |
| - class/spatial 分离 readout |
| - 新的 frame-level supervision path |
| |
| 当前最安全的角色定位是： |
| |
| ```text |
| ov1_local_spatial = 已恢复并可复现的 0410 单源 local-spatial baseline |
| ``` |
| |
