2026-09-24 【音色评估】项目拆解（四）：调试改参与变式测试

0. 先把参数分成三类（这决定了”改了会不会报错”）#

调试最容易踩的坑是”以为调参就是改数字”。实际上一段成熟代码里的参数有完全不同的性质：

这张表就是本篇的路线图：策略类放心调；形状类改了立刻炸，容易发现；数值类最危险——它会给你一个”看起来正常”的错误答案。

排查顺序也由此确定：先看数值类契约（采样率/归一化），再看策略类（聚合/阈值），最后才动形状类。

1. 调试前的三件准备（否则只能凭感觉）#

三条缺一不可：没有 ① 只能猜；没有 ② 不知道改坏没；没有 ③ 结果不稳定。

2. 实验一：阈值敏感性（error_threshold 从 0 扫到 60）#

动机：第三篇说过阈值 20 是”防抖容差”。它到底保不保守？扫一遍就知道。

做法：固定维度=厚薄、模型等级=1（最容易触发跨级的分支），把阈值从 0 扫到 60。

实测结果（音频 test_input.wav，采样率模式=线上默认）：

结论（这条很关键）：

偏差 423.86 远大于任何阈值（0~60），所以阈值调多少都不改变结果——问题不在阈值大小，而在”分数尺度与阈值不匹配”。

三个维度的分数尺度实测差了 100 倍以上（厚薄 ~80，虚实 ~540，明暗 ~9400），却共用同一个 20。于是：

修法（三选一，按推荐度排序）：

1. 维度内标准化：把每个维度的分数量纲统一（例如用训练集分位数映射到 0–100），阈值 20 才恢复”防抖”语义；
2. 相对阈值：把判定条件从 |f − center| > 20 改成 |f − center| > α·(该维度分数标准差)；
3. 分维度阈值：至少给每个维度各标一个阈值（明暗的阈值不可能是 20，它一个小数点就几十）。

顺带一个发现：同一音频、同一等级，16 kHz 模式下 f=327.93，22.05 kHz 模式下 f=442.81。同一段代码只是采样率变了，分数就差了 115。这就是下面实验二的内容。

3. 实验二：采样率模式对照（把”隐含依赖”量化出来）#

动机：第三篇指出两侧采样率不一致——模型侧用原始采样率，物理侧被 librosa 默认重采样到 22050 Hz。这到底影响多大？

实测（同一音频，以线上默认 22050 为基准）：

结论：占比只差 1e-2 量级，但经过训练好的权重与线性映射（明暗模板 a≈26）后被放大成上千分。 含义：bands_weights / bands_change 这类常量必须连同采样率与重采样实现一起固定，否则等于换了一把尺子。 修法：把采样率写进常量契约（统一 16 k 或 22.05 k），并在 CI/自检里加一条”换环境后分数漂移 < 1”的回归。

4. 实验三：抗增益实验（响度到底影响多大、影响在哪）#

做法：同一段音频乘不同增益（0.05× ~ 10×），重算 12 段占比与三维分数。

这一对数字的对比就是全篇最有价值的线索：

占比几乎完全不变（说明”除以总能量”的归一化是成功的），但分数却能漂 9400 → 说明漂移不是来自占比，而是来自额外拼进去的特征。

顺着查 15 维特征向量：前 12 维是”频段能量占比”（抗增益），第 13 维是”总能量×1e-7”（绝对量，随响度线性变化）。再看六套模板谁用了它：

5. 实验四：响度 → 分数的机制与修复（本篇重点）#

1
bands_weights[5] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
2
bands_index[5]   = [0,1,2,3,4,5,6,7,8,9,10,11,12]     ← 第 12 列 = 总能量×1e-7
3
bands_change[5]  = [a=26.0197, b=-24.315, center=49.06]

1
raw = 100 × Σ(w·e) = 100 × (1 × 总能量×1e-7) = 总能量 × 1e-5
2
f   = a·raw + b    = 26.0197 × (总能量 × 1e-5) − 24.315

6. 实验五：模型端调参（不能只调物理端）#

物理端调的是”规则”，模型端调的是”输入与推理策略”。用试验台「② 模型端调参」页签可直接跑，实测数据如下。

7. 断点调试：怎么把”没被走到的分支”逼出来#

第三篇那个 (12,) (13,) 的 bug，不是靠读代码读出来的，而是靠”强制构造输入”逼出来的：

1. 看分支：cal_features 里有一条只在”模型判 1 级 + 物理分显著偏高”时才走的递归分支；
2. 造输入：直接调用 speech_process(path, {'thickness':1,'solidity':1,'brightness':1})，把三个维度都压到最低级 → 必然进那条分支；
3. 看报错：ValueError: operands could not be broadcast together with shapes (12,) (13,) → 定位到”换模板但没换特征列”;
4. 修 + 固化成回归用例：修复后把这条”强制三围=1级”的调用写进脚本，以后每次改 speechprocess.py 都跑一遍。

方法论三句话：

• 覆盖率不是看”跑过多少样本”，而是看关键分支有没有被走到；
• 逼出 bug 最省力的办法是直接构造极端输入（全 1 级、静音、超短、削波、非音频文件）；
• 修完立刻写成自检脚本（本项目留下了 physics_lab/selftest.py、diag_bad_inputs.py、tuner_lab/selftest.py），否则下次改代码还会重踩。

异常输入清单（本项目实测，全部已覆盖）：

8. 改参检查清单（改之前 / 改之后）#

改之前，先回答四个问题：

1. 这个参数属于哪一类（策略 / 数值 / 形状）？
2. 它影响的是哪一层（输入特征 / 模型结构 / 物理常量 / 判定规则）？
3. 改完之后，谁需要跟着改？（例：换特征 → 必须重标定边界；换采样率 → 必须重标定权重）
4. 我有没有一个对拍基准能证明”只有预期的地方变了”？

改之后，跑三件事：

9. 本篇产出物 + 下一篇预告#

产出物：

• ✅ 调参试验台（tuner_lab/，端口 5003，明亮主题，① 物理端 / ② 模型端 / ③ 修复对照 / ④ 实验速查 四个页签，可直接点出本文每一个数字）
• ✅ 四组实验的真实数据：阈值扫描、采样率对照、抗增益、模型端 10 组参数
• ✅ “响度 → 明暗/虚实”的机制解释与修复方案（含”为什么明暗不能只删列”这一关键结论）
• ✅ 模型端参数三分类清单（可安全调 / 静默漂移 / 直接报错）
• ✅ 断点调试方法论 + 异常输入清单 + 改参检查清单
• ✅ 自检脚本：run_fix_sweep.py、run_model_sweep.py、selftest.py

启动方式：

1
cd tuner_lab
2
..\.venv_html\Scripts\python.exe app.py       # → http://127.0.0.1:5003
3
# 或双击 start_tuner.bat

**下一篇（第五篇：总结复盘与二次开发）**会把这三篇的”发现”收敛成一份可执行的改进方案：

1. 把本篇的修复方案落成一版可上线的 speechprocess.py（去能量列 + 维度内标准化 + 相对阈值），并给出前后对比；
2. 输出项目级复盘：哪些设计值得保留（占比归一化、两级融合、对拍机制）、哪些必须改（尺度不统一、采样率未固定、缺”刚柔”维度）；
3. 一份二次开发清单：加第四维度、序数建模、设备域泛化、不确定度区间，各自的工作量与依赖；
4. 把”从零复现一个项目”的方法论沉淀成可复用的模板（调研 → 跑通 → 拆解 → 改参 → 复盘）。

系列定位：5 篇走完「调研摸底 → 环境跑通 → 代码拆解 → 调试改参 → 复盘沉淀」。 本篇目标：从”看懂代码”进阶到”能改、敢改、知道改了会怎样”。所有实验不需要新数据，全部用项目自带音频即可复跑。 与前面的衔接：第三篇把两条管线的数据契约讲透了（15 维特征、六套模板、1213 位置编码）。本篇就沿着这些契约故意去改，看哪一类参数会把系统改坏、哪一类安全。 配套可运行试验台：tuner_lab/（端口 5003，明亮主题，物理端 + 模型端同一页），本文每个数字都能在页面上点出来。

0. 先把参数分成三类（这决定了”改了会不会报错”）#

调试最容易踩的坑是”以为调参就是改数字”。实际上一段成熟代码里的参数有完全不同的性质：

这张表就是本篇的路线图：策略类放心调；形状类改了立刻炸，容易发现；数值类最危险——它会给你一个”看起来正常”的错误答案。

排查顺序也由此确定：先看数值类契约（采样率/归一化），再看策略类（聚合/阈值），最后才动形状类。

1. 调试前的三件准备（否则只能凭感觉）#

三条缺一不可：没有 ① 只能猜；没有 ② 不知道改坏没；没有 ③ 结果不稳定。

2. 实验一：阈值敏感性（error_threshold 从 0 扫到 60）#

动机：第三篇说过阈值 20 是”防抖容差”。它到底保不保守？扫一遍就知道。

做法：固定维度=厚薄、模型等级=1（最容易触发跨级的分支），把阈值从 0 扫到 60。

实测结果（音频 test_input.wav，采样率模式=线上默认）：

结论（这条很关键）：

偏差 423.86 远大于任何阈值（0~60），所以阈值调多少都不改变结果——问题不在阈值大小，而在”分数尺度与阈值不匹配”。

三个维度的分数尺度实测差了 100 倍以上（厚薄 ~80，虚实 ~540，明暗 ~9400），却共用同一个 20。于是：

修法（三选一，按推荐度排序）：

1. 维度内标准化：把每个维度的分数量纲统一（例如用训练集分位数映射到 0–100），阈值 20 才恢复”防抖”语义；
2. 相对阈值：把判定条件从 |f − center| > 20 改成 |f − center| > α·(该维度分数标准差)；
3. 分维度阈值：至少给每个维度各标一个阈值（明暗的阈值不可能是 20，它一个小数点就几十）。

顺带一个发现：同一音频、同一等级，16 kHz 模式下 f=327.93，22.05 kHz 模式下 f=442.81。同一段代码只是采样率变了，分数就差了 115。这就是下面实验二的内容。

3. 实验二：采样率模式对照（把”隐含依赖”量化出来）#

动机：第三篇指出两侧采样率不一致——模型侧用原始采样率，物理侧被 librosa 默认重采样到 22050 Hz。这到底影响多大？

实测（同一音频，以线上默认 22050 为基准）：

结论：占比只差 1e-2 量级，但经过训练好的权重与线性映射（明暗模板 a≈26）后被放大成上千分。 含义：bands_weights / bands_change 这类常量必须连同采样率与重采样实现一起固定，否则等于换了一把尺子。 修法：把采样率写进常量契约（统一 16 k 或 22.05 k），并在 CI/自检里加一条”换环境后分数漂移 < 1”的回归。

4. 实验三：抗增益实验（响度到底影响多大、影响在哪）#

做法：同一段音频乘不同增益（0.05× ~ 10×），重算 12 段占比与三维分数。

这一对数字的对比就是全篇最有价值的线索：

占比几乎完全不变（说明”除以总能量”的归一化是成功的），但分数却能漂 9400 → 说明漂移不是来自占比，而是来自额外拼进去的特征。

顺着查 15 维特征向量：前 12 维是”频段能量占比”（抗增益），第 13 维是”总能量×1e-7”（绝对量，随响度线性变化）。再看六套模板谁用了它：

5. 实验四：响度 → 分数的机制与修复（本篇重点）#

1
bands_weights[5] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
2
bands_index[5]   = [0,1,2,3,4,5,6,7,8,9,10,11,12]     ← 第 12 列 = 总能量×1e-7
3
bands_change[5]  = [a=26.0197, b=-24.315, center=49.06]

1
raw = 100 × Σ(w·e) = 100 × (1 × 总能量×1e-7) = 总能量 × 1e-5
2
f   = a·raw + b    = 26.0197 × (总能量 × 1e-5) − 24.315

6. 实验五：模型端调参（不能只调物理端）#

物理端调的是”规则”，模型端调的是”输入与推理策略”。用试验台「② 模型端调参」页签可直接跑，实测数据如下。

7. 断点调试：怎么把”没被走到的分支”逼出来#

第三篇那个 (12,) (13,) 的 bug，不是靠读代码读出来的，而是靠”强制构造输入”逼出来的：

1. 看分支：cal_features 里有一条只在”模型判 1 级 + 物理分显著偏高”时才走的递归分支；
2. 造输入：直接调用 speech_process(path, {'thickness':1,'solidity':1,'brightness':1})，把三个维度都压到最低级 → 必然进那条分支；
3. 看报错：ValueError: operands could not be broadcast together with shapes (12,) (13,) → 定位到”换模板但没换特征列”;
4. 修 + 固化成回归用例：修复后把这条”强制三围=1级”的调用写进脚本，以后每次改 speechprocess.py 都跑一遍。

方法论三句话：

• 覆盖率不是看”跑过多少样本”，而是看关键分支有没有被走到；
• 逼出 bug 最省力的办法是直接构造极端输入（全 1 级、静音、超短、削波、非音频文件）；
• 修完立刻写成自检脚本（本项目留下了 physics_lab/selftest.py、diag_bad_inputs.py、tuner_lab/selftest.py），否则下次改代码还会重踩。

异常输入清单（本项目实测，全部已覆盖）：

8. 改参检查清单（改之前 / 改之后）#

改之前，先回答四个问题：

1. 这个参数属于哪一类（策略 / 数值 / 形状）？
2. 它影响的是哪一层（输入特征 / 模型结构 / 物理常量 / 判定规则）？
3. 改完之后，谁需要跟着改？（例：换特征 → 必须重标定边界；换采样率 → 必须重标定权重）
4. 我有没有一个对拍基准能证明”只有预期的地方变了”？

改之后，跑三件事：

9. 本篇产出物 + 下一篇预告#

产出物：

• ✅ 调参试验台（tuner_lab/，端口 5003，明亮主题，① 物理端 / ② 模型端 / ③ 修复对照 / ④ 实验速查 四个页签，可直接点出本文每一个数字）
• ✅ 四组实验的真实数据：阈值扫描、采样率对照、抗增益、模型端 10 组参数
• ✅ “响度 → 明暗/虚实”的机制解释与修复方案（含”为什么明暗不能只删列”这一关键结论）
• ✅ 模型端参数三分类清单（可安全调 / 静默漂移 / 直接报错）
• ✅ 断点调试方法论 + 异常输入清单 + 改参检查清单
• ✅ 自检脚本：run_fix_sweep.py、run_model_sweep.py、selftest.py

启动方式：

1
cd tuner_lab
2
..\.venv_html\Scripts\python.exe app.py       # → http://127.0.0.1:5003
3
# 或双击 start_tuner.bat

**下一篇（第五篇：总结复盘与二次开发）**会把这三篇的”发现”收敛成一份可执行的改进方案：

1. 把本篇的修复方案落成一版可上线的 speechprocess.py（去能量列 + 维度内标准化 + 相对阈值），并给出前后对比；
2. 输出项目级复盘：哪些设计值得保留（占比归一化、两级融合、对拍机制）、哪些必须改（尺度不统一、采样率未固定、缺”刚柔”维度）；
3. 一份二次开发清单：加第四维度、序数建模、设备域泛化、不确定度区间，各自的工作量与依赖；
4. 把”从零复现一个项目”的方法论沉淀成可复用的模板（调研 → 跑通 → 拆解 → 改参 → 复盘）。