| # v13_B + v13_C 设计文档 |
|
|
| > 日期：2026-05-01 |
| > 作者：Claude + user |
| > 目标：在 v12（F20=0.378）基础上，分两个正交实验把 F20 推到 0.45+，合并实验 v14 目标 0.55~0.62 |
| > 设计原则：**所有改动增量式**，通过 cfg flag 控制，默认全关 → 不破坏任何现有实验（v7/v11/v12 全可正常复现） |
|
|
| --- |
|
|
| ## 0. 背景与瓶颈诊断（摘自 v12 per-subset 分析） |
|
|
| v12 best.pt (F20=0.3779 聚合) 按子集拆分： |
|
|
| ``` |
| 子集 N F20 ER20 LE_CD LR_CD o_cls o_azi aP aR |
| ov1_sim 4800 0.386 0.686 26.8° 0.640 0.796 25.5° 0.950 0.046 |
| ov2_sim 1718 0.299 0.926 29.6° 0.546 0.653 30.0° 0.916 0.151 |
| ov3_sim 1612 0.270 0.917 30.5° 0.499 0.599 31.8° 0.888 0.165 |
| ov1_real 3374 0.140 0.924 117.7° 0.232 0.809 27.4° 0.767 0.144 |
| ov2_real 2230 0.098 0.866 121.1° 0.198 0.747 38.3° 0.655 0.227 |
| ov3_real 740 0.052 0.766 146.8° 0.125 0.624 51.5° 0.612 0.232 |
| dcase_starss 4560 0.071 1.171 130.3° 0.185 0.698 36.0° 0.625 0.176 |
| unified 35021 (~0.40, 推算) |
| ``` |
|
|
| **三大诊断**： |
|
|
| 1. **瓶颈是 activity_recall (0.13)，不是 cls 也不是 spatial。** oracle_class_acc 在 real 上仍有 0.80，oracle_azi_mae_deg 27-51°，说明表征是健康的，被 activity gate 挡住了。 |
| 2. **Real/Sim gap 极大**：同 ov 级别下 real F20 比 sim 低 64~81%。原因是 train 里 dcase_real 只占 6%。 |
| 3. **Overlap 惩罚显著**：sim ov3 F20 比 ov1 低 30%（0.27 vs 0.39），K=4 track head 在 overlap 下 slot 分配混乱。 |
| |
| --- |
| |
| ## 1. 实验切分：B 和 C 是正交维度 |
| |
| | 维度 | v13_B | v13_C | |
| |---|---|---| |
| | 改 loss / head 输出接口 | ✅ | ❌（沿用 v12 loss） | |
| | 改数据比例 / augment | 仅 augment | ✅ replication | |
| | 改主干架构 / 容量 | ❌ | ✅ refinement + adapter V3 | |
| | 热启动 | v12 best.pt (strict=False) | v12 best.pt (strict=False) | |
| | 能解的子集 | sim + real 的 activity 瓶颈 | ov2/ov3 overlap + real gap | |
| |
| 理由：让 B 的收益和 C 的收益互不污染，便于 ablation。v14 = B + C 合并。 |
| |
| --- |
| |
| ## 2. 共同约束（关键：不破坏现有实验） |
| |
| 所有 B/C 改动都要遵守： |
| |
| ### 2.1 Cfg flag 默认全关 |
| |
| 每条新改动对应一个 `SpatialBEATsConfig` / `SpatialLossConfig` / `TrainSpatialBEATsConfig` 字段，**默认值就是"这条改动不启用"**。 |
| |
| ```python |
| # spatial_modules 侧 |
| self.use_class_activity_bias: bool = False # [B-1] |
| self.use_class_conditional_gate: bool = False # [B-3] |
| self.use_track_refinement: bool = False # [C-2] |
| self.track_refinement_layers: int = 2 |
| self.patch_adapter_version: str = "v1" # "v1"/"v2"/"v3" [C-3] 加 v3 |
| self.use_log_distance_head: bool = False # [C-4] |
| |
| # spatial_loss 侧 |
| self.activity_loss_type: str = "bce" # "bce"/"asymmetric" [B-2] |
| self.asl_gamma_neg: float = 4.0 |
| self.asl_gamma_pos: float = 0.0 |
| self.asl_probability_margin: float = 0.05 |
| self.soft_f1_weight: float = 0.0 # 0 = disabled [B-4] |
| self.distance_loss_type: str = "l1" # "l1"/"laplace_nll" [C-4] |
| |
| # dataset 侧 |
| self.use_spec_augment: bool = False # [B-5] |
| self.spec_augment_time_mask_ratio: float = 0.0 |
| self.spec_augment_freq_mask_ratio: float = 0.0 |
| self.random_gain_db: float = 0.0 |
| self.channel_dropout_prob: float = 0.0 |
| self.lowpass_sim_real_prob: float = 0.0 |
| ``` |
| |
| `ov1_unified_v12` preset 和之前所有 preset 都**不动**，因为它们没设置这些 flag → 新代码分支不走。 |
| |
| ### 2.2 热启动安全 |
| |
| 新加的 `nn.Module` / `nn.Parameter` 全部**零初始化**或**identity 等价初始化**： |
| |
| - `class_activity_bias`：`torch.zeros(num_classes)` → logit 不变 |
| - `GatingMLP` 最后一层 bias/weight zero-init → gate_logit = 0 |
| - `TrackRefinementDecoder`：`layer_scale = zeros(num_layers)` → 残差 x + 0 = x |
| - `log_distance_head`：bias 初始化为 `log(mean_distance_v12) ≈ log(1.5)` |
| |
| 从 v12 best.pt `strict=False` 加载时： |
| - 不存在的 key → 走零初始化 |
| - 存在的 key（所有 v12 组件）→ 正常加载 |
| - ep0 forward 输出应与 v12 best.pt 完全一致（或数值上差 < 1e-5） |
| |
| ### 2.3 完全向后兼容 |
| |
| 任何旧脚本跑起来（比如 `run_ov1_unified_v12.sh`）**不需要改一行**，因为所有新字段都有默认值且默认 disabled。 |
| |
| ### 2.4 Preset 命名 |
| |
| - `ov1_unified_v13b`：启用所有 B 相关 flag |
| - `ov1_unified_v13c`：启用所有 C 相关 flag |
| - `ov1_unified_v14`：B + C 全开，热启动 max(v13b.best, v13c.best) |
| |
| --- |
| |
| ## 3. v13_B 详细设计：Loss + Decision 全面重写 |
| |
| ### [B-1] Per-class learnable logit bias |
| |
| **为什么**：全局阈值 0.5 对所有类别一视同仁不合理。稀有类（jackhammer）和常见类（singing）的 activity 先验差异巨大，应当让模型自己学各类的 logit bias（等价于 per-class threshold）。 |
| |
| **实现点**： |
| - 文件：`spatial_modules.py` |
| - 类：`FrameTrackPredictionHeads`（定位：`class_logits` 和 `activity_logits` 的出口处） |
| - 新增 parameter：`self.class_activity_bias = nn.Parameter(torch.zeros(num_classes))` |
| - 新增 buffer：`self.use_class_activity_bias: bool` |
| - Forward 改动： |
| |
| ```python |
| # 原： |
| activity_logit = self.activity_head(token) # [B, K, T, 1] |
| |
| # 新： |
| activity_logit_raw = self.activity_head(token) # [B, K, T, 1] |
| if self.use_class_activity_bias: |
| class_probs = F.softmax(class_logits, dim=-1) # [B, K, T, C] |
| # 用 class_probs 作为加权软分配（避免 argmax 阻断梯度） |
| expected_bias = torch.einsum('bktc,c->bkt', class_probs, self.class_activity_bias) |
| activity_logit = activity_logit_raw + expected_bias.unsqueeze(-1) |
| else: |
| activity_logit = activity_logit_raw |
| ``` |
| |
| **训练/推理一致性**：bias 在训练的 BCE loss 和推理的 sigmoid 里都是**同一个量**，因此不需要 threshold sweep。推理时 threshold 始终 = 0.0（logit 空间）或 0.5（prob 空间），完全等价。 |
| |
| **参数量**：63 个标量，忽略不计。 |
| |
| ### [B-2] Asymmetric Loss 替换 BCE |
| |
| **为什么**：BCE 把 FN 和 FP 等权重。当前 activity_recall=0.13 说明 FN 惩罚严重不够。ASL 对 easy negatives 用 `(1-p)^γ-` 下压，对 positives 用弱 `γ+=0`，正负不均衡下表现显著好于 BCE。 |
| |
| **实现点**： |
| - 文件：`spatial_loss.py` |
| - 新增函数：`asymmetric_loss_with_logits(logits, targets, gamma_neg=4, gamma_pos=0, margin=0.05)` |
| - 在 `compute_frame_track_losses`（或同名函数）里根据 `config.activity_loss_type` 分支： |
| |
| ```python |
| if config.activity_loss_type == "asymmetric": |
| loss_act = asymmetric_loss_with_logits( |
| activity_logit, target_active, |
| gamma_neg=config.asl_gamma_neg, |
| gamma_pos=config.asl_gamma_pos, |
| margin=config.asl_probability_margin, |
| ) |
| else: # "bce" |
| loss_act = F.binary_cross_entropy_with_logits(activity_logit, target_active, ...) |
| ``` |
| |
| **数学**： |
| ``` |
| p = sigmoid(logit) |
| positive: -( (1-p)**γ+ ) * log(p) |
| negative: p_shifted = max(p - m, 0) |
| -( p_shifted**γ- ) * log(1 - p_shifted) |
| ``` |
| |
| **参数**：`γ+ = 0`, `γ- = 4`, `margin = 0.05`（ASL paper 推荐起点） |
| |
| ### [B-3] Class-conditional gating MLP |
| |
| **为什么**：activity 当前只看 token embedding。应该让 activity 也依赖 class/DOA 的确信度 —— class softmax 尖锐、DOA 稳定时更大胆判 active。 |
| |
| **实现点**： |
| - 文件：`spatial_modules.py` |
| - 新增类：`ClassConditionalGate(embed_dim, num_classes, hidden_dim=128)` |
| - 输入：`fused_token [B, K, T, D]`, `class_logits [B, K, T, C]`, `pred_dir [B, K, T, 3]` |
| - 融合：`gate_input = concat(token, class_emb_avg, dir_vec)` → MLP → `gate_logit [B, K, T, 1]` |
| - class_emb 用 `class_logits.softmax()` 加权的 class embedding（新增 `nn.Embedding(C, 32)`） |
| - 在 FrameTrackPredictionHeads 里： |
| |
| ```python |
| if self.use_class_conditional_gate: |
| gate_logit = self.class_conditional_gate(token, class_logits, pred_dir) |
| activity_logit = activity_logit + self.gate_scale * gate_logit |
| ``` |
| |
| **初始化**：MLP 最后一层 `weight=zero, bias=zero` → gate_logit = 0 → ep0 等价 v12。 |
| |
| **参数量**：~80K。 |
| |
| ### [B-4] Soft-F1 auxiliary loss |
| |
| **为什么**：BCE/ASL 仍是 per-sample 损失，优化目标和 macro-F20 评测有 gap。Soft-F1 直接按类聚合，和 DCASE 评估同构。 |
| |
| **实现点**： |
| - 文件：`spatial_loss.py` |
| - 新增函数：`soft_macro_f1_loss(activity_logits, class_logits, target_active, target_class)` |
| - 对每个类 `c`： |
| - `p_c = sigmoid(act_logit) * softmax(class)[c]` （class-c 的软 activity） |
| - `y_c = (target_active and target_class==c)` |
| - `tp_c = sum(p_c * y_c)`, `fp_c = sum(p_c * (1-y_c))`, `fn_c = sum((1-p_c) * y_c)` |
| - `f1_c = 2 tp_c / (2 tp_c + fp_c + fn_c + eps)` |
| - `loss = 1 - mean(f1_c)` |
| - 在总 loss 里： |
| |
| ```python |
| if config.soft_f1_weight > 0: |
| total_loss = total_loss + config.soft_f1_weight * soft_macro_f1_loss(...) |
| ``` |
| |
| **warmup**（已确认采用）：前 3 ep `soft_f1_weight=0.1`，第 3 ep 起硬切到 `0.3`。 |
| |
| 实现方式：在 `train_spatial_beats.py` 的 epoch 循环里根据 `epoch >= soft_f1_warmup_epochs` 动态设置 `train_cfg.loss.soft_f1_weight`，新增 config 字段： |
| ```python |
| cfg.loss.soft_f1_weight_warmup: float = 0.1 # ep < warmup_epochs 时使用 |
| cfg.loss.soft_f1_weight: float = 0.3 # ep >= warmup_epochs |
| cfg.loss.soft_f1_warmup_epochs: int = 3 |
| ``` |
| |
| ### [B-5] Real-distribution augment |
| |
| **为什么**：sim_static 混响干净，模型学到的 activity 判据在低 SNR 下崩溃。augment 让模型见到各种"污染"的 spec，对 real 数据更鲁棒。 |
| |
| **实现点**： |
| - 文件：`spatial_dataset.py` |
| - 在 `SpatialDataset.__getitem__` 或 collate 里加 augment pipeline |
| - 只在训练集（`split='train'`）启用，valid/test 不启用 |
| - 新增 config flag： |
| - `use_spec_augment`（默认 False） |
| - `spec_augment_time_mask_ratio`（0.2 = 20% time 长度） |
| - `spec_augment_freq_mask_ratio`（0.15） |
| - `random_gain_db`（±8） |
| - `channel_dropout_prob`（0.1） |
| - `lowpass_sim_real_prob`（0.1，cutoff ∈ U[4000, 8000] Hz） |
| |
| **顺序**：waveform-level augment（gain, lowpass, channel_dropout）→ feature-level augment（SpecAugment）。 |
| |
| **重要**：augment 只作用在 FOA 4 通道 waveform / delta feature 上，**target labels 不变**。 |
| |
| ### B 实验 preset: `make_ov1_unified_v13b_config` |
| |
| 热启动：`v12_best.pt` (strict=False) |
| 开关： |
| ```python |
| cfg.model.use_class_activity_bias = True # [B-1] |
| cfg.model.use_class_conditional_gate = True # [B-3] |
| cfg.loss.activity_loss_type = "asymmetric" # [B-2] |
| cfg.loss.asl_gamma_neg = 4.0 |
| cfg.loss.asl_probability_margin = 0.05 |
| cfg.loss.soft_f1_weight = 0.3 # [B-4] |
| cfg.dataset.use_spec_augment = True # [B-5] |
| cfg.dataset.spec_augment_time_mask_ratio = 0.2 |
| cfg.dataset.spec_augment_freq_mask_ratio = 0.15 |
| cfg.dataset.random_gain_db = 8.0 |
| cfg.dataset.channel_dropout_prob = 0.1 |
| cfg.dataset.lowpass_sim_real_prob = 0.1 |
| cfg.learning_rate = 1e-5 |
| cfg.num_epochs = 15 |
| cfg.output_dir = "checkpoints/spatial_beats_ov1_unified_v13b_exp/03_ov123_top4" |
| ``` |
| |
| **数据 manifest 完全复用 v12**：unified train/valid + old ov1/2/3 sim/real + dcase_starss 作为 val。 |
| |
| --- |
| |
| ## 4. v13_C 详细设计：Data + Architecture 全面重写 |
| |
| ### [C-1] Real data upsampling (replication) |
| |
| **为什么**：real (dcase_real) 在 train 里占 6%，梯度感受不到。DCASE 社区标准做法是 20-30% real。 |
| |
| **实现点**： |
| - 预处理脚本：`scripts/split_unified_train_by_source.py` |
| - 读 `unified_spatial_foa_fsd63_all/train.jsonl` |
| - 按 `data_source` 字段拆成三份： |
| - `train_sim_static.jsonl` |
| - `train_qa_sim.jsonl` |
| - `train_dcase_real.jsonl` |
| - 写到 `unified_spatial_foa_fsd63_all/` 同目录下 |
| - Preset： |
| |
| ```python |
| cfg.train_manifest_paths = ( |
| unified_root / "train_sim_static.jsonl", |
| unified_root / "train_qa_sim.jsonl", |
| unified_root / "train_dcase_real.jsonl", |
| ) |
| cfg.train_manifest_replication = (1, 1, 6) |
| ``` |
| |
| **影响估算**（基于 v12 已知分布）： |
| - sim_static 304K × 1 = 304K |
| - qa_sim ~? × 1 = ~? |
| - dcase_real 20K × 6 = 120K |
| - real 占比从 6% → ~25% （取决于 qa_sim 规模） |
| |
| **兼容性**：`train_manifest_replication` 机制在 `train_spatial_beats.py` 已经存在（v7j 用过），不需要新加框架代码。只改 preset。 |
| |
| ### [C-2] Track-wise Refinement Transformer（2 layers） |
| |
| **为什么**：K=4 track slots 之间互相不知道对方在干嘛，overlap 时同一源被多个 slot 抢，或同一 slot 被多个源抢。引入 self-attention 让 slot 互相"排斥"。 |
| |
| **实现点**： |
| - 文件：`spatial_modules.py` |
| - 新增类： |
| |
| ```python |
| class TrackRefinementDecoder(nn.Module): |
| def __init__(self, num_tracks=4, embed_dim=768, num_layers=2, |
| num_heads=8, dim_feedforward=2048, dropout=0.0): |
| self.track_queries = nn.Parameter(torch.randn(num_tracks, embed_dim) * 0.02) |
| self.layers = nn.ModuleList([ |
| nn.TransformerDecoderLayer( |
| d_model=embed_dim, nhead=num_heads, |
| dim_feedforward=dim_feedforward, dropout=dropout, |
| activation='gelu', norm_first=True, batch_first=True, |
| ) for _ in range(num_layers) |
| ]) |
| # Zero-init layer scale: ep0 refinement = identity |
| self.layer_scale = nn.Parameter(torch.zeros(num_layers)) |
| |
| def forward(self, memory): |
| # memory: fused_spatial_embeddings [B, T, D] |
| # 输出：refined track tokens [B, K, T, D] |
| B, T, D = memory.shape |
| K = self.track_queries.size(0) |
| # 复制 K queries 到时间维度：[B, K, T, D] |
| q = self.track_queries[None, :, None, :].expand(B, K, T, D) |
| # 每个时间步独立做 decoder |
| # 为简化，把 T 维 flatten 进 batch：[B*T, K, D] cross-attn with [B*T, 1, D] |
| q_flat = q.permute(0, 2, 1, 3).reshape(B * T, K, D) |
| mem_flat = memory.reshape(B * T, 1, D) |
| for i, layer in enumerate(self.layers): |
| out = layer(q_flat, mem_flat) |
| q_flat = q_flat + self.layer_scale[i] * (out - q_flat) |
| # reshape 回 [B, K, T, D] |
| refined = q_flat.reshape(B, T, K, D).permute(0, 2, 1, 3).contiguous() |
| return refined |
| ``` |
| |
| - 在 `SpatialBEATs` 里： |
| |
| ```python |
| if cfg.use_track_refinement: |
| self.track_refinement = TrackRefinementDecoder( |
| num_tracks=cfg.num_tracks, |
| embed_dim=cfg.encoder_embed_dim, |
| num_layers=cfg.track_refinement_layers, |
| ) |
| |
| # encode_patches 之后、送入 head 之前： |
| if self.track_refinement is not None: |
| track_tokens = self.track_refinement(encoder_memory) # [B, K, T, D] |
| # 传给 FrameTrackPredictionHeads 的输入从 [B, T, D] 改成 [B, K, T, D] |
| else: |
| track_tokens = None # head 沿用旧 expand 逻辑 |
| ``` |
| |
| - `FrameTrackPredictionHeads` 的 forward 加个 `track_tokens: Optional[Tensor]` 参数： |
| - 传入 None → 沿用现有的"[B,T,D] 复制到 K slots" |
| - 传入 `[B,K,T,D]` → 用 refined tokens 走 head |
| |
| **参数量**：2 layer × (self_attn + cross_attn + FFN) ≈ 2 × 2M = 4M。 |
| |
| **Zero-init 校验**：`layer_scale = zeros(2)` + 残差公式 `q + scale * (out - q)` → ep0 输出 = `track_queries`（静态，和 memory 无关）。但这会丢掉时间信息 —— **修正**：改用 `q + scale * layer_out`，并且把 track_queries 初始化成 `memory` 投影： |
| |
| 实际更安全的等价初始化： |
| |
| ```python |
| # Zero-init 方案：layer 不改 query，query 本身先吸收 memory 信息 |
| # 思路：在 refine 前先做一次 "identity fallback"：如果 scale=0，输出 = memory 广播到 K |
| def forward(self, memory): |
| B, T, D = memory.shape |
| K = ... |
| # 初始 track_tokens = memory 广播到 K（+ 一个很小的 query 偏移） |
| track_tokens = memory[:, None, :, :].expand(B, K, T, D).contiguous() |
| track_tokens = track_tokens + 0.02 * self.track_queries[None, :, None, :] |
| # refine |
| for i, layer in enumerate(self.layers): |
| ... |
| track_tokens = track_tokens + self.layer_scale[i] * delta |
| return track_tokens |
| ``` |
| |
| 这样 `layer_scale=0` 时 refinement 输出 ≈ `memory` 广播到 K，和 v12 "把 [B,T,D] 复制到 [B,K,T,D]" 等价。热启动安全。 |
| |
| ### [C-3] Multi-scale Patch Adapter V3 |
| |
| **为什么**：v12 用的 V2 adapter 只看 3 个时间 bin（30 ms），抓不到房间冲激响应的 early reflection (50-150ms)。V3 加多尺度 + dilated conv。 |
| |
| **实现点**： |
| - 文件：`spatial_modules.py` |
| - 新增类：`SpatialDeltaPatchAdapterV3` |
| - 三路 branch： |
| - branch_3x3: `Conv2d(C, H, kernel=3, padding=1)` (同 V2) |
| - branch_5x5: `Conv2d(C, H, kernel=5, padding=2)` (中尺度) |
| - branch_dilated: `Conv2d(C, H, kernel=3, padding=2, dilation=2)` (长时) |
| - fuse: `torch.cat` along channel → `Conv2d(3H, H, kernel=1)` |
| - 接现有 V2 的 SE block + residual + patchify |
| - cfg：`patch_adapter_version: str = "v1"` 增加选项 `"v3"` |
| |
| **参数量**：比 V2 多 ~1M。 |
| |
| ### [C-4] Log-distance head + Laplace NLL loss |
| |
| **为什么**：dist_mae=0.57 很差。距离分布长尾，log 后近似高斯。加 uncertainty 头允许模型对不确信的距离给大 variance，减少高 bias 样本的损失。 |
| |
| **实现点**： |
| - 文件：`spatial_modules.py`, 类 `FrameTrackPredictionHeads` |
| - 把现有 `distance_head: Linear(D, 1)` 升级为 `distance_head: Linear(D, 2)` 输出 `[log_dist, log_var]` |
| - 初始化：`bias[0] = log(1.5)`（v12 平均距离附近），`bias[1] = log(0.2^2)`（var=0.04 起点） |
| - cfg：`use_log_distance_head: bool = False`, `distance_loss_type: str = "l1" / "laplace_nll"` |
| |
| - 文件：`spatial_loss.py`, Laplace NLL: |
| |
| ```python |
| def laplace_nll_loss(pred_log_dist, pred_log_var, target_dist, mask): |
| # target_dist > 0 的位置才算 loss |
| pred_dist = pred_log_dist.exp() |
| pred_b = (0.5 * pred_log_var).exp() # Laplace scale |
| nll = (target_dist - pred_dist).abs() / pred_b + pred_log_var * 0.5 |
| return (nll * mask).sum() / mask.sum().clamp(min=1) |
| ``` |
| |
| 推理时 `pred_distance = exp(pred_log_dist)`。 |
| |
| **初期稳定性**（已确认）：v13c 从第 0 ep 就切 Laplace NLL（不做 L1 warmup）。如果训练前期 loss_dist 不稳，再回来调。 |
| |
| ### C 实验 preset: `make_ov1_unified_v13c_config` |
| |
| 热启动：`v12_best.pt` (strict=False) |
| 开关： |
| ```python |
| cfg.model.use_track_refinement = True # [C-2] |
| cfg.model.track_refinement_layers = 2 |
| cfg.model.patch_adapter_version = "v3" # [C-3] |
| cfg.model.use_log_distance_head = True # [C-4] |
| cfg.loss.distance_loss_type = "laplace_nll" # [C-4] |
| |
| cfg.train_manifest_paths = (sim_static, qa_sim, dcase_real) # [C-1] |
| cfg.train_manifest_replication = (1, 1, 6) |
| |
| cfg.learning_rate = 1e-5 |
| cfg.num_epochs = 20 |
| cfg.output_dir = "checkpoints/spatial_beats_ov1_unified_v13c_exp/03_ov123_top4" |
| ``` |
| |
| **loss 完全沿用 v12 默认**（BCE + L1 → Laplace），`soft_f1_weight=0`, `activity_loss_type="bce"`。 |
| |
| --- |
| |
| ## 5. v14 合并实验（后续） |
| |
| 在 B 和 C 都验证有效（F20 > 0.42）后启动： |
| |
| - 热启动：`max(v13b.best, v13c.best).pt` |
| - 所有 B 和 C 的 flag 全开 |
| - LR = 5e-6（更保守，防止双改动发散） |
| - epochs = 20 |
| |
| 预期 F20 = 0.55~0.62。 |
| |
| --- |
| |
| ## 6. 预期结果 & 风险矩阵 |
| |
| ### B 预期 |
| - 聚合 F20: 0.378 → **0.45~0.52** |
| - sim ov1: 0.386 → 0.50~0.55 |
| - real ov1: 0.140 → 0.22~0.28 |
| - dcase: 0.071 → 0.15~0.20 |
| - activity_recall: 0.13 → 0.40~0.55 |
| |
| ### C 预期 |
| - 聚合 F20: 0.378 → **0.44~0.50** |
| - ov3_sim: 0.270 → 0.38~0.42 |
| - real ov1: 0.140 → 0.20~0.26 |
| - dcase: 0.071 → 0.14~0.19 |
| - dist_mae: 0.566 → 0.38~0.42 |
| |
| ### 风险 |
| |
| | 风险 | 发生概率 | 兜底 | |
| |---|---|---| |
| | B-2 ASL γ- 太大发散 | 中 | 先 γ-=2 跑 1 ep 验证，再拉到 4 | |
| | B-3 gate 挡掉好样本 | 低 | gate_scale 从 0.5 改 0.2 重跑 | |
| | B-4 soft-F1 和 ASL 冲突 | 中 | soft_f1_weight 从 0.3 降到 0.1 | |
| | B-5 augment 太强 sim 掉点 | 中 | 减半 augment 比例重跑 | |
| | C-1 real 6× 导致 sim 掉点 | 中 | 降到 4× | |
| | C-2 refinement 不学 | 中 | 手动设 layer_scale warmup | |
| | C-3 多尺度显存爆 | 低 | 去掉 dilated branch | |
| | C-4 log-dist 初期不稳 | 中 | 前 3 ep 用 L1 再切 | |
| | v14 合并发散 | 高 | 降 LR 到 3e-6，freeze trunk 前半段 | |
| |
| --- |
| |
| ## 7. 落地文件清单 |
| |
| | 文件 | 改动类型 | B/C | |
| |---|---|---| |
| | `spatial_modules.py` | 新增 3 个类 + 现有类加 forward 分支 | B+C | |
| | `spatial_loss.py` | 新增 2 个 loss 函数 + config 分支 | B+C | |
| | `spatial_dataset.py` | 新增 augment 逻辑 + config 字段 | B | |
| | `spatial_beats.py` | config 字段 + 可选模块构造 + forward 分支 | B+C | |
| | `train_spatial_beats.py` | 新增 2 个 preset 工厂 + CLI dispatch + choices | B+C | |
| | `scripts/split_unified_train_by_source.py` | 新文件，预处理脚本 | C | |
| | `run_ov1_unified_v13b.sh` | 新文件 | B | |
| | `run_ov1_unified_v13c.sh` | 新文件 | C | |
| | `docs/v13_spatial_beats_design.md` | 本文档 | — | |
|
|
| 所有现有文件的改动都是**新增分支**，不删除/修改任何现有逻辑。 |
|
|
| --- |
|
|
| ## 8. 验证步骤 |
|
|
| 每完成一步，按顺序验证： |
|
|
| 1. **语法检查**：`python -c "import ast; ast.parse(open(path).read())"` |
| 2. **旧 preset 回归**：`python train_spatial_beats.py --preset ov1_unified_v12 --dry-run`（或者 ep=1 跑到第一个 batch），确认 F20 和 v12 一致 |
| 3. **新模块零初始化等价**：在 `v13b_config` / `v13c_config` 下跑 ep=0 valid，确认和 v12 best.pt 的 valid 指标差异 < 1% |
| 4. **B/C 训练**：完整跑 15/20 ep，观察 F20 曲线 |
| 5. **per-subset eval**：用 `eval_v12_per_subset.py --preset ov1_unified_v13b --checkpoint ...` 看每个子集涨点 |
| 6. **test eval**：用同脚本加 `--split test` 跑最终测试 |
|
|
