1. 三角函数、正弦波与相位#

定义：正弦波是最基本的周期信号

• A 振幅（决定响度）；
• f 频率（Hz，决定音高）；
• φ 相位（弧度，决定”从波形的哪个位置开始”）；
• 周期 T = 1/f。

为什么重要：傅里叶变换的本质就是”用一堆不同频率、振幅、相位的正弦波去拼出任意信号”。所以”频域”就是”每个正弦分量的振幅与相位表”。

在本项目：所有的频谱、能量占比、共振峰，都是”不同频率正弦分量强度”的度量。

常见误解：以为频率只有”一个值”。真实人声是复合音：基频 + 大量谐波 + 噪声成分叠加，频域上是一整片分布。

2. 复数与欧拉公式#

定义：虚数单位 j（工程上用 j，数学上用 i）满足 j² = −1。欧拉公式：

几何直觉：e^{jθ} 是复平面单位圆上的一个点，角度为 θ。让 θ 随时间线性增长 θ = 2πft，这个点就在圆上匀速旋转，它在实轴上的投影就是一个余弦波：

为什么 DFT 用复数：用一个旋转向量 e^{-j2πkn/N} 去”套”信号的每个频率，通过内积测出该频率分量的振幅和相位——复数一部到位，比分别算 sin/cos 更优雅。因此 DFT 输出 X[k] 是复数：

• 模 |X[k]| = 该频率的幅度（这是我们最关心的）；
• 幅角 ∠X[k] = 该频率的相位（音频任务里通常丢弃）。

常见误解：以为”复数”意味着物理上有虚数能量。复数只是数学记账工具，物理量始终是实数。

3. 向量、矩阵与形状规则#

点积（内积）：a·b = Σᵢ aᵢbᵢ，衡量两个向量的”方向一致程度”。本项目物理量化的核心运算就是点积：

1
np.sum(weights * energy)   # 等价于 weights @ energy

矩阵乘法：(m, n) @ (n, p) = (m, p) —— 内维必须相等，结果取外维。这条规则是读懂深度学习报错的第一钥匙（本项目那两个 bug 都是形状不匹配）。

广播（broadcasting）：numpy/torch 允许形状不同的数组自动扩展运算，例如 (3,1) * (1,4) → (3,4)。规则是”从右往左对齐，维度为 1 或缺失可广播”。

本项目实战：报错 operands could not be broadcast together with shapes (12,) (13,) 就是”权重长度 12 与特征长度 13 无法广播”——两个维度都不为 1 且不相等，直接失败。

4. 均值、方差、协方差（含 unbiased 的坑）#

均值：μ = (1/n)Σxᵢ，数据的”重心”。

方差：σ² = (1/n)Σ(xᵢ−μ)²，数据的”分散程度”。标准差 σ = √σ²，与原数据同量纲。

关键坑：总体方差 vs 样本方差

PyTorch 的 Tensor.var() 默认 unbiased=True（分母 n−1），而本项目 FisherLoss 显式写了 unbiased=False：

1
var0 = outputs[mask0].var(unbiased=False)   # 分母用 n，batch 内统计更一致

为什么必须显式指定：batch 很小（比如每类只有 4 个样本）时，n 与 n−1 的差别高达 25%，会让损失值随 batch 大小漂移，训练不稳定。

协方差：cov(x,y) = E[(x−μx)(y−μy)]，衡量两个变量的线性相关方向。协方差矩阵 Σ（或记 S）描述多维数据的”形状”（各维方差 + 两两相关）。Fisher/LDA 的核心就是用协方差矩阵的逆去”白化”数据再找判别方向。

5. 导数、偏导、梯度与链式法则#

导数：f'(x) = lim_{h→0}(f(x+h)−f(x))/h，即”变化率”，几何上是切线斜率。

偏导：多元函数对某一个变量求导（其他视为常数），记 ∂f/∂xᵢ。

梯度：把所有偏导拼成向量 ∇f = (∂f/∂x₁, …, ∂f/∂xₙ)。梯度的方向是函数上升最快的方向，所以梯度下降要”减去”梯度：

链式法则：复合函数求导要逐层相乘

这就是反向传播的全部数学本质：从损失开始，逐层向前乘局部导数。

在本项目：frenquence_check/model.py 里作者手推了 Fisher 损失的梯度（见第 44 节），PyTorch 版本则由 autograd 自动完成。

6. 概率与分布#

• 随机变量 / 期望 E[·]：期望就是”加权平均”。
• 正态分布 N(μ, σ²)：钟形曲线，自然界最普遍。为什么深度学习假设它：中心极限定理（大量独立小因素之和趋于正态）。
• Beta 分布 Beta(a, b)：取值在 [0,1]，常用来采”混合比例 λ”。本项目 mixup 用 np.random.beta(10, 10) → 集中在 0.5 附近（a=b 越大越集中于 0.5），意思是”混合时两条音频权重差不多”；roll-mag 增强也用 np.random.beta(10,10)+0.5 生成 0.5~1.5 的幅度缩放。
• 条件概率与贝叶斯：P(A|B) = P(B|A)P(A)/P(B)。分类器输出的”概率”实质是对后验的估计。
• sigmoid（logistic）函数：

它把任意实数压到 (0,1)，当概率用；导数形式极简，是反向传播友好的原因。

• softmax：

把一组实数变成”和为 1”的分布（多分类用）。

常见误解：sigmoid 输出不是”真正的概率”，只是校准前的分数；模型置信度可能偏高，需要温度缩放等后处理，但本项目未做校准。

7. 对数与分贝#

• 对数的作用：把乘除变加减、把大动态范围压缩成小范围。
• 分贝（dB）：对功率/能量用 10·log10(P/P₀)，对幅度用 20·log10(A/A₀)（因为功率 ∝ 幅度²）。
• 为什么音频常用 dB：人耳感知近似对数（韦伯-费希纳定律），且音频动态范围极大（从耳语到摇滚可达 10⁶ 倍），用 dB 只需几十个数。
• 本项目：fbank 就是对数梅尔能量（log-mel）；librosa.amplitude_to_db 用于画频谱图；数据集的 mean=-4.2677, std=4.5690 也是对数值的统计。
• dBFS：数字音频里以满量程为 0 dB，dBFS = 20log10(A/A_max)，0 dBFS 是最大不失真电平，超过即削波（clipping）。

常见误解：把”dB 是线性单位”搞混——dB 是相对量，必须说明参考基准（dB SPL、dBFS、dBu…）。

8. 线性代数进阶：投影、特征值与广义特征值#

投影：向量 x 在方向 w 上的投影长度是 (wᵀx)/‖w‖。判别分析就是”把高维数据投影到一条直线上，让两类尽量分开”。

特征值/特征向量：若 Av = λv，则 v 是 A 的特征向量（方向在变换下不变），λ 是特征值（缩放倍数）。

广义特征值问题：

其中 S_b 是类间散度矩阵、S_w 是类内散度矩阵。解出的 w 就是 Fisher/LDA 的最优判别方向。两类情形有闭式解：

几何直觉：先用 S_w^{-1} 把数据”拉成球形”（消除各方向方差不均），再取两类中心的连线方向。

矩阵求逆的直觉：A^{-1} 是”撤销 A 的变换”。若 S_w 奇异（某方向方差为 0，常见于特征冗余或样本太少），需要加正则项 S_w + εI——本项目 FisherLoss 分母加 1e-6、sklearn 的 LDA 用 shrinkage 都是这个道理。

9. 连续信号到离散信号：采样定理与混叠#

采样：以间隔 T = 1/sr 抽取连续信号的值：

数学上等价于”乘以冲激串”：

频域后果：时域相乘 = 频域卷积。冲激串的频谱仍是冲激串（间隔 sr），与 X(f) 卷积的结果就是把原始频谱以 sr 为周期复制：

1
原始频谱:        [======X(f)======]            最高频率 f_max
2
采样后:   ...X(f-sr) |  X(f)  | X(f+sr)...     每 sr 复制一份

奈奎斯特定理：只有 f_max < sr/2，复制出来的频谱才不会互相重叠，才有可能无失真还原。 sr/2 称为奈奎斯特频率。16 kHz 采样 → 上限 8 kHz。

混叠（aliasing）：若 f > sr/2，该分量会”折叠”到 sr − f 的位置，伪装成一个低频。例：10 kHz 的信号用 16 kHz 采样，会听成 16−10 = 6 kHz。

抗混叠滤波：实际降采样前必须先低通滤波到 sr/2 以下，否则高频会折叠成假低频。librosa.load(..., sr=16000) 内部就是”低通 + 重采样”，不是简单抽点。

为什么本项目统一 16 kHz：人声中决定音色的基频、前几阶共振峰、以及区分”虚实”的噪声成分主要在 8 kHz 内；16 kHz 既够用又能省一半算力。更重要的是模型是在 16 kHz 数据上训练的，推理必须一致。

10. 量化、位深与量化噪声#

量化：把连续幅度映射到有限个离散电平。位深 B 比特 → 2^B 个电平。

量化噪声模型：把舍入误差近似为均匀分布的白噪声，其功率为 Δ²/12（Δ 为量化步长）。对满量程正弦，可推出经典结论：

• 16 bit → 约 98 dB（语音标准）；
• 8 bit → 约 50 dB（明显噪声）；
• 每个 bit 换 6 dB 动态范围。

本项目：前端转码固定写 16 bit（WAV 头偏移 34 处写 16）——够用且文件不太大（16 kHz 单声道 16 bit = 32 KB/s，10 秒 ≈ 320 KB）。

削波：若幅度超过量程被截断，会产生大量高次谐波（听感”破音”），这是录音质量问题的第一大来源，会直接污染高频特征（影响”明暗”判断）。

11. 时域与频域：傅里叶思想的直觉#

核心命题（傅里叶）：任何”足够规矩”的信号，都能写成不同频率正弦/余弦的加权和：

• 时域看波形（横轴时间），频域看成分（横轴频率）；
• 两者是同一信息的两面，可以互相转换（傅里叶变换对），信息量不变（丢相位除外）。

直觉类比：一段音乐在时域是”一条抖动的线”，在频域是”一份乐器清单 + 每个乐器的音量”。音色分析关心的是”清单比例”，这正是频域更适合的原因。

12. DFT：公式、频率 bin 与单边谱#

离散傅里叶变换（DFT） 对 N 个采样点：

逆变换：

每个 k 对应什么频率：

N = n_fft = 2048、sr = 16000 时，f_k = 7.8125·k Hz；k = 128 → 1000 Hz。

对称性与单边谱：实信号的 DFT 满足共轭对称 X[N−k] = X*[k]，负频率没有新信息。所以实信号只需看前 N/2+1 个点 → 输出长度 1025（这正是本项目 librosa.stft 输出形状 (1025, 帧数) 的来源）。

单边幅度谱的正确缩放：除 DC（k=0）与奈奎斯特点外，要把幅度乘 2 才能对应真实振幅——librosa 的 stft 默认不缩放，但做”能量占比”时缩放是全局的，归一化后自动抵消，所以项目直接用 |X|² 求和再除以总和完全没问题（这是个值得理解的小细节）。

13. FFT：为什么快，快在哪#

DFT 的代价：直接算需要 O(N²) 次复数乘法。N = 2048 时约 420 万次。

FFT（快速傅里叶变换） 利用旋转因子的周期性/对称性做分治：把长度 N 的 DFT 拆成两个长度 N/2 的 DFT（偶数点、奇数点），递归下去：

其中 W_N^k = e^{-j2πk/N}。复杂度降到 O(N log N)——2048 点只需约 2.2 万次，快约 190 倍。这就是”实时频谱分析”可行的原因。

工程细节：

• n_fft 取 2 的幂（512/1024/2048）最省事；
• 补零（zero-padding） 能让频率”点更密”（插值），但不提高真实分辨率（真实分辨率由窗长决定）——很多人在这里误解；
• 实数 FFT（rFFT）只算一半，省一半算力（librosa/torch 内部都用 rFFT）。

14. 时间分辨率 vs 频率分辨率的权衡#

频率分辨率（能区分多近的两个频率）：

时间分辨率（能分辨多短的变化）：

两者反向变化：窗越长 → 频率越精细、时间越模糊。这本质上是时频不确定性原理（Δt·Δf ≥ 常数），与海森堡原理同源（数学上都是傅里叶对偶性）。

本项目的选择：n_fft=2048（≈128 ms 窗，Δf≈7.8 Hz）、hop=512（32 ms）。语音处理惯例是”25 ms 窗、10 ms 帧移”，项目的窗更长，因为音色分析关心稳定的频谱形状而不是快速的音素变化。

同类对比：深度学习侧 fbank 用 25 ms 窗、10 ms 帧移（Kaldi 默认），因为模型需要更细的时间结构。

15. 窗函数、频谱泄漏与分帧#

为什么必须加窗：DFT 隐含假设”这 N 个点是一个周期信号”，但实际取的是信号的任意一段 → 截断处不连续，相当于乘了一个矩形窗。矩形窗的频谱是 sinc 函数，会把一个纯音的能量”涂抹”到邻近频点，这叫频谱泄漏（leakage）。

窗函数的作用：让帧两端平滑衰减到 0，减小截断突变，从而压低旁瓣（泄漏）。

Hann 窗公式：

代价：加窗损失了帧边缘的信息 → 用重叠（overlap） 补偿，重叠率通常 50%~75%。

分帧与帧数公式：

• center=False（不补零）：帧数 = 1 + ⌊(L − n_fft)/hop⌋
• center=True（librosa.stft 的默认值，两端各补 n_fft/2）：帧数 = 1 + ⌊L/hop⌋

以 10 秒 16 kHz（L = 160 000）、n_fft = 2048、hop = 512 为例：

• center=False → 1 + (160000−2048)/512 = 309 帧；
• center=True（librosa 默认）→ 1 + 160000/512 = 313 帧。

Kaldi fbank 的帧数近似为 时长/帧移（16 kHz、10 ms 帧移、10 秒 → 约 1000 帧）。

16. 幅度谱 / 功率谱 / 能量谱 / 对数谱#

设 STFT 输出复数矩阵 X：

能量谱与功率谱的区别：严格来说功率谱要对时长/带宽做归一化（Pa²/Hz），但在”占比”这类比值计算里，是否归一化不影响结果（同一常数约掉）。项目代码注释里两者混用，实际计算的是 |X|² 的求和——理解这一点就不会被术语绊住。

为什么常丢掉相位：人耳对相位不敏感（对短时相位尤其如此），而幅度谱已足够支撑音色/内容判别；相位重建是另一条研究线（Griffin-Lim、神经声码器）。

17. 常用谱特征#

为什么项目只用其中几个：作者做过特征筛选实验（filter_np() 里注释保留了多套列组合），最终固化的 12 段占比 + 3 个综合量是”够用且稳定”的最小集合。复现时不要盲目加特征，加了反而可能过拟合。

18. 滤波、预加重与卷积定理#

滤波器：按频率选择性地放大/衰减。低通、高通、带通、带阻。

卷积定理（理解滤波的关键）：

即时域卷积 = 频域相乘。所以”滤波”既可以理解为时域的加权滑动平均，也可以理解为频域上乘一条曲线。

预加重（pre-emphasis）：语音频谱天然呈 −6 dB/oct 下降（高频能量低），预加重用一阶高通

把高频抬起来让频谱更平坦，便于建模；对应地，解码端要”去加重”还原。本项目 parselmouth.to_formant_burg(pre_emphasis_from=50) 里的参数就是预加重起点。

差分与倒谱：语音里常用”一阶/二阶差分”（Δ、ΔΔ）描述特征随时间的变化率；倒谱（cepstrum）是”对幅度谱再取对数、再做逆变换”，能把”声源（基频）“与”滤波器（共振峰）“分离——MFCC 就是这个思路的产物。

19. 采样率转换（重采样）与抗混叠#

降采样（downsampling）：sr 44100 → 16000。必须先低通到新奈奎斯特频率（8 kHz）以下，否则折叠。 升采样（upsampling）：插值 + 低通，填补中间样本。

librosa 的实现：librosa.load(path, sr=16000) 内部优先用 soxr（高质量、快）、其次 resampy/scipy.signal.resample_poly。不同实现会有微小数值差异，但对”能量占比”这类统计特征影响极小。

工程要点：

1. 只在最前端做一次重采样，之后全链路保持 16 kHz；
2. 不要用”每隔 k 个点取一个”这种朴素抽取（会严重混叠）；
3. 采样率是模型输入约定的一部分（fbank 的 sample_frequency 参数），改了会让梅尔滤波器对应错频率。

20. 声压、dBFS 与响度#

• 声压级（SPL）：20log10(p/p₀)，p₀ = 20 μPa；正常对话约 60 dB SPL。
• dBFS：数字域相对满量程的分贝，0 dBFS 为上限。
• 峰值电平（Peak）：瞬时最大值，防削波看它。
• RMS：均方根，反映平均能量。
• LUFS：带频率加权（K-weighting）与门限的响度标准（流媒体统一到 −14 或 −16 LUFS）。

本项目为什么绕开响度问题：特征用能量占比（归一化），等于”把响度变量除掉”，因此同一人小声/大声说同一句话，音色分数应当接近——这是设计上的抗增益优势，也是可以在汇报里强调的亮点。（但它并非完全免疫：削波、底噪、麦克风频响仍会干扰。）

21. PCM、位序与声道交错#

• PCM 数据布局：16 bit 有符号整数，小端序（低位字节在前）。写 WAV 时用 DataView.setInt16(offset, value, true)，最后的 true 就是小端。
• 声道交错（interleaved）：立体声按 L1 R1 L2 R2 … 排列。本项目转单声道（左右取平均），因为音色评估针对单一说话人，且能减少一半数据量。
• float vs int：librosa.load 默认返回 float32 且归一化到 [−1, 1]；写盘时 soundfile 会按目标格式转成 int16。

22. WAV/RIFF 文件结构逐字节#

WAV 是 RIFF 容器的一种，结构是”块（chunk）链”：

1
RIFF chunk:
2
  "RIFF" | size(4B) | "WAVE"
3
    ├─ fmt  chunk: "fmt " | size(4B)=16 | format(2B) | channels(2B) | sampleRate(4B)
4
    │              | byteRate(4B) | blockAlign(2B) | bitsPerSample(2B)
5
    └─ data chunk: "data" | size(4B) | PCM 采样数据…

规模：byteRate = sr × channels × bits/8；blockAlign = channels × bits/8（每帧字节数）；dataSize = 帧数 × blockAlign。 16 kHz 单声道 16 bit → byteRate = 32000 B/s，10 秒 = 320 000 B。

为什么常说是”44 字节头”：当 fmt 块为最简 16 字节、且后面紧跟 data 时，头部总长 = 12（RIFF）+ 8+16（fmt）+ 8（data 头）= 44。若含 LIST/fact 等扩展块，头会更长——健壮的解析器不应硬编码 44（本项目自己生成的 WAV 恰好是标准 44 字节）。

本项目代码对照（main.js::audioBufferToWavBlob）：逐字段写入的就是上表，其中 view.setUint32(4, 36 + dataSize, true) 对应”RIFF 块大小 = 文件总长 − 8”。

23. 容器与编码：MP3 / AAC / Opus 原理#

有损压缩的共同原理（心理声学）：

1. 频域掩蔽：强音附近的弱音听不见 → 可以少分配比特；
2. 同时掩蔽 / 时域掩蔽：前后短时间内的弱信号也可丢弃；
3. 听觉阈值：绝对听阈以下的成分直接丢。

各自特点：

关键工程属性：

• 有损：解码后波形 ≠ 原始波形。对”能量占比”这类统计特征影响不大，但高频截止（如 16 kbps Opus 可能只保留到 8 kHz 以下）会截断高频 → 直接影响”明暗”判断。所以评估系统最好要求上传无损 WAV，或至少中等以上码率。
• 编码延迟/前导：MP3 有约 26 ms 编码延迟，AAC/Opus 也有 framing 延迟；精确对齐分析时要注意。
• VBR/CBR：变码率音质更好但文件时长/大小关系不固定。

24. 为什么浏览器录音是 WebM+Opus，后端为什么读不了#

链路：getUserMedia 拿到麦克风流 → MediaRecorder 按浏览器默认编码录制 → Chrome/Edge/Firefox 通常选 WebM 容器 + Opus 编码（Safari 可能给 MP4/AAC）。

后端为什么失败：

• soundfile（封装 libsndfile）支持的容器有限：WAV、FLAC、OGG、AIFF、MP3（较新版本），不包括 WebM；
• WebM 是 Matroska 家族，需要解封装器 + Opus 解码器，libsndfile 都不具备 → 报 Format not recognised；
• librosa 捕获该异常后回退 audioread，而 audioread 需要外部 ffmpeg / GStreamer 可执行文件 → 服务器没装就 NoBackendError。

三种解决思路对比（本项目选了第 1 种）：

25. 录音链路与常见音质问题#

一条完整录音链路：声源 → 空气传播 → 麦克风（换能 + 频响）→ 前置放大（增益）→ ADC（采样 + 量化）→ 编码/传输 → 解码 → 分析。

这段是实验设计要写进方法论的部分：评估前应统一录音设备与距离，否则测的是”设备 + 音色”的混合量。这也是本项目在汇报/论文里必须交代的局限性。

26. 语音产生机理：声源—滤波器理论#

Source-Filter Theory（语音学最核心的模型）：

1
气流(肺) → 声带振动(声源) → 声道形状(滤波器) → 唇鼻辐射 → 语音
2
            产生基频与谐波      决定共振峰        高频提升

• 声源决定基频 F0 与谐波结构（音高、以及”嗓音是否沙哑”）；
• 滤波器（声道形状，由舌、唇、软腭等控制）决定共振峰（决定元音，也影响音色）；
• 辐射（唇端）近似一阶高通，让高频略微提升。

为什么这个模型重要：

1. 它解释了”音高（F0）“与”音色（共振峰包络 + 谐波幅度）“是可分离的两件事——同一个人唱不同音高，音色仍可辨识；
2. 它指导了特征设计：要描述音色，就看频谱包络与谐波幅度分布，而不是只看基频；
3. 倒谱/MFCC 就是”把声源与滤波器解耦”的数学手段。

清音 vs 浊音：

• 浊音（元音、鼻音、部分辅音）：声带振动，频谱有清晰谐波结构（能量集中在 F0 的整数倍）；
• 清音（s、sh、f、t、k 等）：声带不振动，气流摩擦/爆破，频谱更像宽带噪声。 本项目分析的一般是朗读/播报的长段语音，以浊音为主，因此”谐波结构强弱”是有效判别依据。

27. 基频 F0、音高与 F0 估计方法#

• 基频 F0：声带振动的基本频率，决定听感音高。男声约 80–180 Hz，女声约 160–300 Hz，儿童更高。
• **音高（pitch）**是主观感知量，F0 是物理量，两者近似成正比但不完全等同（受响度、谐波结构影响）。

F0 估计的三大类方法：

倒谱求 F0 的思路（理解 MFCC 的前置）：

1. 取对数幅度谱 log|X(f)|；
2. 对它做逆 FFT → 得到”倒谱” c[τ]；
3. 谐波在倒谱上会形成”τ = 1/F0”处的尖峰 → 找到它即得 F0。

为什么倒谱能分离声源与滤波器：对数把”相乘”变”相加”（log(声源 × 滤波) = log声源 + log滤波），声源（谐波梳状）与滤波（平滑包络）在对数谱上各占不同”节奏”，逆变换后落在不同时间/倒频率位置。

本项目：F0 没有被显式计算，但”厚薄”维度看 0–1350 Hz 的能量分布，实际上间接反映基频与低次谐波的强弱（F0 高且低频能量少 → 偏”薄”）。

28. 谐波结构与谐噪比 HNR#

谐波结构：浊音频谱的能量集中在 F0 的整数倍处，形成”梳状”谱。

谐噪比（HNR, Harmonics-to-Noise Ratio）：

估算方法（Praat 的做法，理解即可）：

1. 自相关函数 r(τ)，周期处（τ = 1/F0）出现峰；
2. HNR = 10log10(r_max/(1−r_max))。

声学含义：

本项目的实现差异（务必注意）：代码里没有真的计算 HNR，“虚实”维度用的是中高频段（50–4280 Hz）12 段能量占比的线性组合作为 HNR 的代理特征（proxy）。逻辑是：气声/噪声成分多 → 中高频（尤其非谐波位置）能量占比上升 → 加权分偏移。写论文/汇报时应当表述为”以频段能量分布作为 HNR 与声门闭合程度的代理特征”，不能声称计算了 HNR。

29. 共振峰、LPC 与 Burg 法#

共振峰（Formant）：声道作为共鸣管的谐振频率，在频谱包络上表现为峰，记作 F1、F2、F3…

元音三角：F1–F2 平面上不同元音占据不同区域（如 /i/ 高 F2 低 F1，/a/ 高 F1 低 F2），这是语音识别与病理嗓音分析的基础。

LPC（线性预测编码）推导思路：

把声道建模为全极点滤波器：

当前样本可由前 P 个样本线性预测：

最小化预测误差 e[n] = x[n] − x̂[n] 的能量，即可解出系数 a_p（一组线性方程，用 Levinson-Durbin 递推求解），再由 H(z) 的极点得到共振峰频率与带宽。

Burg 法：LPC 的一种求解方式，不显式求自相关，而是最小化前向与后向预测误差之和。优点是短数据稳定、频率估计精确，Praat 的 to_formant_burg() 就是它。

本项目参数的含义（get_fre.py::get_format）：

1
sound.to_formant_burg(time_step=0.01,        # 每 10 ms 分析一帧
2
                      max_number_of_formants=5,
3
                      maximum_formant=6000,  # 最高搜索到 6 kHz（女声/儿童需要更高）
4
                      window_length=0.025,   # 25 ms 分析窗（语音惯例）
5
                      pre_emphasis_from=50)  # 50 Hz 起做预加重

取 F1–F3 的中位数作为代表值（抗离群），并把频率与带宽各 ×1e-4 缩放后拼入特征。注意：部署版没有使用共振峰特征，它只出现在科研脚本里（return 被注释切换）——复现时别多算。

30. 声门闭合商与”虚/实”的声学机制#

• 声门：喉部两片声带之间的开口；说话时周期性开合。
• 声门闭合商（CQ, Closed Quotient）：一个振动周期中声门闭合时间所占比例。CQ 高 → 声带闭合充分、激励脉冲短而强 → 谐波丰富、听感”实”；CQ 低 → 大量漏气 → 噪声多、听感”虚”。
• 开商（OQ）= 1 − CQ；**速度商（SQ）**描述开合不对称性。
• 气流与气压：气声（breathy voice）是”声带振动 + 持续漏气”，频谱特征是中高频噪声底抬高、H1-H2 差值增大。

测量困难：CQ 需要高速喉镜或 EGG（电声门图）等专用设备，从普通录音里只能估计代理量（HNR、谐波幅度差 H1−H2、谱倾斜 spectral tilt 等）。本项目的做法（频段能量占比）就是一种代理。

可写进实验设计的建议：若条件允许，用 EGG 或至少用同一套录音设备建立基线，能把”虚实”这一维的效度（validity）说得更硬。

31. 语音的准平稳假设与分帧长度惯例#

语音是时变信号（音素切换很快），但在短时间窗内（10–30 ms）可近似认为是平稳的——这叫准平稳假设（quasi-stationarity），是所有短时分析（STFT、LPC、fbank）的前提。

为什么两套参数不同却不冲突：它们服务于不同目的——STFT 侧给”物理量化”（看重频谱形状与频段占比），fbank 侧给”神经网络”（看重时间序列模式）。理解这一点能解释”为什么同一个项目里有两套音频处理管线”，也是第 3 篇拆代码时的关键分界线。

32. 梅尔刻度的来历与公式#

问题：人耳对频率的感知不是线性的——1 kHz 以下很敏感（能分辨几 Hz 差别），高频则迟钝（几千 Hz 的差别都听不出）。用等 Hz 间隔切频段，会造成”低频分辨率不足、高频浪费”。

梅尔刻度（Mel scale）：一种模拟人耳感知的”主观音高”刻度。常用近似公式（Stevens & Volkmann，1937 / O’Shaughnessy）：

反变换（Mel → Hz，构造滤波器组时要用）：

推导思路（理解就够）：该式源于”主观音高 ≈ 临界带数量的对数”这一经验规律；700 与 2595 是拟合常数：2595 ≈ 1000/ln(2)，用来把”倍频程”换算成 mel 的尺度；在 1 kHz 处，mel 值约为 1000。

校验点：

• f = 1000 Hz → m = 2595·log10(2.4286) ≈ 999.99（果然约 1000）；
• f = 4280 Hz → m ≈ 2211；
• f = 124 Hz → m ≈ 183.7。

其它听觉刻度：Bark（临界带）、ERB（等效矩形带宽）。Mel 最常用，因为它简单；ERB 更贴近听觉生理。

33. 梅尔滤波器组的构造（5 步详解）#

深度学习侧的 fbank 特征，是把频谱通过一组三角形带通滤波器聚合而来。构造步骤：

第 1 步：确定频率范围

• 下限 f_low（通常 0 或 20 Hz；本项目 Kaldi 默认 20 Hz）；
• 上限 f_high（通常 sr/2 = 8000 Hz，或直接取 8000）。

第 2 步：转到 Mel 域并均匀取点

滤波器个数 M = 128（本项目）。需要 M + 2 个边界点：

第 3 步：转回 Hz

得到 130 个频点，相邻三个构成一个三角形：(f_{i-1}, f_i, f_{i+1})。

第 4 步：在 FFT 频点上做三角加权

第 i 个滤波器的响应（在 FFT 的频率 bin k 上）：

得到一个 (M, N/2+1) = (128, 1025)（16 kHz、n_fft 2048、25 ms 窗时为 512 点时是 257）的稀疏矩阵。

第 5 步：归一化与聚合

• 面积归一化（norm='slaney'）：让每个滤波器的面积相等，低频滤波器更窄但更高，使得各频带”总能量”可比；
• 峰值归一化：三角形峰值为 1（Kaldi 的一种选择，便于用固定比例混合）；
• 聚合：mel_energy = H @ power_spectrum；取对数（加小常数防 log(0)）→ log-mel / fbank。

为什么低频滤波器更窄：等 mel 间隔在低频对应更小的 Hz 间隔 → 低频分辨率高（符合人耳）。

在本项目：这里要特别注意区分两件事——

1. 深度学习输入用的是”128 个梅尔滤波器的 fbank”；
2. 物理量化特征用的是”12 个等梅尔间隔的频段能量占比”（直接用频段求和，不经过三角窗）。 两者都用梅尔刻度，但一个是”滤波器组特征”，一个是”分频段占比统计”，目的不同。

34. log-mel / fbank / MFCC 的关系#

DCT（离散余弦变换）：对 log-mel 做 DCT 相当于”把相邻滤波器的相关性去掉”，得到近似独立的倒谱系数。代价是丢弃了高维细节。

为什么现代音频深度学习更爱 fbank 而不是 MFCC：

1. DCT 是线性变换，会损失信息且不可逆（截断后）；
2. 神经网络自己能从 log-mel 里学出更好的表示（甚至端到端从波形学）；
3. fbank 保留了完整的梅尔频带信息，128 维比 13 维信息量大得多。

本项目 128 维的选择：AudioMAE/AST 惯例（128 mel × 1024 帧 ≈ 10 秒），高频率分辨率对区分音色细节（谐波密度、高频噪声）有利。

35. Kaldi fbank 与 librosa mel 的差异#

虽然都算 mel 特征，但细节不同，不能混用（训练用 Kaldi，推理也必须用 Kaldi）：

这解释了为什么归一化常数是 mean=-4.2677, std=4.5690：Kaldi fbank 的对数能量在 AudioSet 上统计出的均值约 −4.3，量级与”DB 相对值”完全不同。如果换成 librosa 的 mel 特征还沿用这两个常数，输入分布会完全错位，模型输出变成噪声。

实践结论：模型训练/推理的特征提取器必须逐参数一致（库、窗函数、帧移、mel 数、归一化方式、甚至库版本），这是深度学习工程里最容易踩、也最难查的一类 bug。

36. 特征归一化：AudioSet 全局均值方差与 ×2 的秘密#

代码：

1
fbank = (fbank - audio_conf['mean']) / (audio_conf['std'] * 2)
2
# audioset: mean = -4.2677393, std = 4.5689974

为什么需要归一化：

1. 让输入分布零均值、单位方差 → 优化更稳定、收敛更快；
2. 不同录音条件（设备/增益）带来的整体偏移被部分消除。

三种归一化方式对比：

为什么 ×2：AudioMAE/AST 的惯例，等价于把标准差乘以 2（即对输入做”轻度压缩”，降低异常值影响）。这在论文代码中常见，改动它会让输入分布与训练不一致。

归一化与后处理的关系：本项目物理量化侧的”能量占比”是另一种归一化（除以总能量），它带来的是”抗音量”特性；而 fbank 侧的 CMVN 带来的是”数值稳定”。两者目的不同，不要混淆。

37. 本项目核心特征：12 频段能量占比#

把前面知识串起来，完整定义本项目的物理特征：

输入：16 kHz 单声道波形 y（任意时长）

计算：

1
1) D = STFT(y, n_fft=2048, hop_length=512)        # (1025, T) 复数
2
2) E = |D|²                                        # 能量谱 (1025, T)
3
3) total = Σ_k Σ_t E[k,t]                          # 标量总能量
4
4) p[k] = Σ_t E[k,t] / total                       # 每个频点的能量占比 (1025,)
5
5) 对每个维度 d（厚薄/虚实/明暗）：
6
     对 12 个频段 [lo_i, hi_i]：
7
        band_i = Σ_{k: lo_i ≤ f_k ≤ hi_i} p[k]     # 12 个数
8
6) 综合量：total_energy×1e-7, LF/HF×0.1, spectral_centroid×1e-3
9
7) 拼接 → 该维度 15 维特征向量

性质分析（这些是可以写进论文的点）：

局限性（同样要写进论文）：

• 只用了幅度信息，丢弃相位；
• 只用 12 段，丢失段内细节（如共振峰位置）；
• 对削波/强混响敏感（频谱形状被破坏）；
• 依赖固定的频段划分（换语言/换音域可能不适配）。

38. 监督学习范式与数据划分#

标准范式：

1
数据 D = {(x_i, y_i)}
2
   │
3
   ├─ 选择假设空间  f_θ（线性模型 / 神经网络 / 树 …）
4
   ├─ 定义损失      L(f_θ(x), y)  衡量"错得有多离谱"
5
   ├─ 优化          找 θ* = argmin L  （梯度下降等）
6
   └─ 评估          在未见过的数据上衡量泛化能力

三份数据的分工：

常见错误：用验证集反复调参后再把它当测试集报告 → 结果虚高（信息泄漏）。本项目可复现的评测脚本 evaluate_thickness_accuracy.py 就是在”厚薄”目录上做整体准确率统计，若要与论文对齐，必须确认它没参与训练。

交叉验证（k-fold）：数据少时的替代方案——轮流留出 1/k 做验证，取平均。本项目数据量小（每级几百条），做 5 折交叉验证比单次划分更可信，这是复现时可以做的改进点。

39. 过拟合、欠拟合与正则化#

• 欠拟合：模型太简单/训练不足 → 训练集与验证集都差；
• 过拟合：模型记住训练样本噪声 → 训练集很好、验证集变差。

判断方法：画出训练/验证损失曲线，若验证损失先降后升，拐点即最佳停止点（早停）。

正则化手段全景（★ = 本项目用到）：

为什么 MAE 预训练算”正则”：它强迫模型学”频谱的通用结构”，微调时需要的标注数据更少，过拟合风险显著下降。

40. 损失函数总览：MSE / CE / BCE#

回归（MSE）：

梯度 ∂L/∂ŷ = 2(ŷ−y)/n，对异常值敏感。MAE（L1）更抗离群但对 0 点不可导。

多分类交叉熵（CE）：设 p = softmax(z)

关键梯度：∂L/∂z = p − y（形式极简，是 softmax+CE 的”黄金搭档”）。

二元/多标签交叉熵（BCE）：对每个标签独立做二分类，σ 是 sigmoid

梯度：∂L/∂z_i = σ(z_i) − y_i（与 CE 同款简洁形式）。

“WithLogits” 版本为什么数值更稳：log σ(z) 当 z 很负时会溢出。BCEWithLogitsLoss 内部用 log-sum-exp 恒等式合并计算：

避免先 sigmoid 再 log 的两步溢出。本项目用的正是 torch.nn.BCEWithLogitsLoss()，所以模型输出 logits（未过 sigmoid），推理时再手动 torch.sigmoid(output)。

分类 vs 回归损失的选择：本项目等级本质是”有序离散类别”，用 BCE 多标签处理（而非回归 MSE），好处是：① 每个维度独立、互不干扰；② 输出概率可用于取最大值判级与阈值分析。若改成回归直接预测 1–3 分，会丢失”概率”这一信息，也无法自然地处理”模型犹豫”的情况。

41. 优化算法：GD → SGD → Momentum → Adam → AdamW#

批量梯度下降（BGD）：用全量数据算梯度 → 准但慢。

随机梯度下降（SGD）：每次用一个样本/小批量：

Momentum（动量）：累加历史梯度方向，抑制震荡、加速收敛：

Adam（自适应学习率 + 动量）：

• m 是一阶矩（梯度均值，类似动量）；
• v 是二阶矩（梯度平方的均值，用来”每个参数自适应”）；
• 偏差校正是因为初期 m、v 被初始化为 0 而偏小；
• 默认 β₁=0.9, β₂=0.999, ε=1e-8；
• 直觉：梯度大的参数步子自动变小，梯度小的参数步子变大 → 对稀疏/尺度差异大的参数友好。

AdamW（本项目微调用）：把权重衰减从”加进梯度”改为”直接衰减参数”（decoupled weight decay）：

原版 Adam+L2 会让自适应学习率与正则耦合（大梯度参数反而被正则得更少），AdamW 解耦后正则效果与训练更稳，是现代 Transformer 训练标配。

为什么项目用 Adam/AdamW 而不是纯 SGD：Transformer 类模型参数尺度差异大、对学习率敏感，AdamW 更容易收敛；而且微调数据量小、轮数少，需要快速稳定收敛。

42. 学习率调度：warmup、cosine 与线性缩放规则#

学习率 η 是最重要的超参：太大会发散/震荡，太小收敛慢或卡在次优。

Warmup（预热）：前几个 epoch 让学习率从 0 线性升到目标值。原因：训练初期参数随机、梯度方向不可靠（尤其 Transformer 的 LayerNorm/注意力统计不稳定），直接大学习率容易”炸”。

Cosine 退火（余弦半周期）：util/lr_sched.py 的实现（本项目实测源码）：

其中 w = warmup_epochs、E = epochs。特点：前期降得快、后期平缓，训练末期”精修”效果好。

线性缩放规则（Linear Scaling Rule）：批大小变大 → 梯度噪声变小 → 可以把学习率按比例放大。本项目微调源码：

1
args.lr = args.blr * eff_batch_size / 256     # eff_batch = batch × accum × GPU数

即”基础学习率 blr 对应 256 的有效批大小”，其他批大小按比例缩放。这解释了为什么脚本里写 --blr 1e-3 而不是直接给 --lr。

逐层学习率衰减（Layer-wise LR Decay）：util/lr_decay.py

layer_decay=0.75、L=12 时，第 0 层学习率是浅层的 0.75¹² ≈ 0.032 倍——浅层（通用频谱特征）几乎不动，深层（任务相关）大步学习。这是从 MAE 权重微调时的标准技巧。

43. 特征缩放与标准化#

为什么必须缩放：若两个特征量级差 1000 倍（如”总能量 1e6”与”能量占比 0.01”），梯度下降会变成”狭长峡谷”里的锯齿下降，收敛极慢；神经网络里还会导致激活饱和。

方式对比：

项目里的两处缩放细节（都为了数值量级对齐，不含信息）：

1
array.append(total_energy*0.0000001)     # 1e-7
2
array.append(features['lfhf_ratio_proportion']*0.1)
3
array.append(features['spectral_centroid_proportion']*0.001)

这些常数会被后续线性权重与 a,b 映射吸收，但必须在训练与推理时保持一致（改了就要重训权重）。

44. 判别分析：Fisher / LDA 完整推导与项目实现对照#

这是本项目物理量化的理论核心，值得完整走一遍。

1
return (var0 + var1) / ((mu1 - mu0).pow(2) + 1e-6)

1
gra1 = np.power(np.mean(y_pred3)-np.mean(y_pred2), -3)   # Δ^{-3}
2
a    = x3_s/x3.shape[0] - x2_s/x2.shape[0]                # x̄3 - x̄2
3
return -2*gra1*a                                          # Direction == 2

45. 逻辑回归、线性分类边界与 sigmoid#

逻辑回归：p(y=1|x) = σ(wᵀx + b)，决策边界 wᵀx + b = 0 是一条超平面。

与 Fisher 的关系：

• 若两类协方差相同（S_0 = S_1），逻辑回归的最大似然解方向与 Fisher 判别方向一致（都正比于 S_w^{-1}(μ1−μ0)）；
• 差别在于：Fisher 只关心”分开”，逻辑回归关心”概率校准”；Fisher 有闭式解，逻辑回归需要迭代。

多标签里的 sigmoid：11 个输出各自过 sigmoid → 11 个独立概率。注意：这些概率之和不为 1（多标签的正常现象），所以不能”取最大概率当唯一答案”来解释全部输出——但本项目在单个维度组内（如 [0<3>]）确实取最大值判级，因为组内三级是互斥的（一条语音的厚薄只能是 C/B/A 之一）。这是多标签框架里嵌”组内单标签”语义的典型用法，也是 group_acc 指标的依据。

46. 评价指标：从混淆矩阵到 mAP 与 d-prime#

1
avg_precision = metrics.average_precision_score(target[:, k], output[:, k], average=None)
2
mAP = np.mean([stat['AP'] for stat in stats])

1
def d_prime(auc):
2
    standard_normal = stats.norm()
3
    return standard_normal.ppf(auc) * np.sqrt(2.0)

1
label_groups = {'thick':[0,1,2], 'real':[3,4,5], 'bright':[6,7,8], 'sex':[9,10]}
2
group_acc[g] = accuracy_score(target[:, g], one_hot(argmax(output[:, g])))

47. 阈值、边界与分位数过滤#

为什么机器学习最后总要有”阈值”：

• 概率输出 → 需要阈值才变”决策”（本项目取组内 argmax，等价于相对阈值）；
• 连续分数 → 需要边界才映射成等级（本项目 bands_change 的中心分）；
• 两套系统融合 → 需要”偏差多大才允许改判”（本项目 error_threshold = 20）。

阈值/边界的三种确定方式：

为什么必须过滤分位数：极端样本（录音异常、标注错误）会把分数轴拉得很长，导致网格搜索出的”最优阈值”落在无效区域；先裁掉两端 → 边界更稳。代价是：真实使用中遇到极端样本会落到边界之外，行为需定义（本项目里就是”物理分极大/极小” → 触发跨级修正或保持原级）。

error_threshold=20 的定位：它不是分类阈值，而是融合修正的容差（0–100 尺度上）。逻辑上类似”避免频繁抖动”的滞回（hysteresis）设计：

• 偏差 ≤ 20 → 认为”模型与物理一致，不改判”，仅打标记（C+/B−）；
• 偏差 > 20 → 认为”分歧显著”，采纳物理分改判一级。

调参方向（第 4 篇要做的实验）：把 20 改成 10/30，观察改判率与（若有标注）准确率变化，就能画出”容差–准确率”曲线，说明这个值是经验折中。

48. 从感知机到 MLP#

感知机：y = step(wᵀx + b)，只能线性分类（连 XOR 都解不了）。 MLP（多层感知机）：叠加”线性层 + 非线性激活”

万能近似定理：足够宽的单隐层网络可逼近任意连续函数（存在性，不代表可训练/可泛化）。这给了”神经网络什么都能拟合”的底气，但实践中真正的关键是归纳偏置（卷积的局部性、注意力的全局交互、掩码预训练的结构先验）。

本项目：主干是 Transformer（注意力替代了卷积的先验），最终接一个线性头，与”MLP + sigmoid”在分类那一层是相通的。

49. 反向传播与计算图（手推一遍）#

计算图：把复合运算拆成节点，前向算值、反向用链式法则传梯度。

两层网络示例：z₁ = W₁x，a₁ = φ(z₁)，z₂ = W₂a₁，L = ℓ(z₂, y)

工程要点：

1. 梯度累加：loss.backward() 会累加而非覆盖 → 必须每步 optimizer.zero_grad()（写错会导致梯度爆炸）；
2. 梯度消失/爆炸：深层网络连乘导致 → 用残差、LayerNorm、合理初始化、梯度裁剪（--clip_grad）；
3. torch.no_grad()：推理时关掉计算图，省显存与时间（本项目推理全程 @torch.no_grad()）。

50. 激活函数与梯度问题#

在 ViT 里：MLP 中间层用 GELU（timm 默认），注意力里没有激活（softmax 除外）。激活函数的非线性是网络表达能力的来源——如果全是线性层，多层也等价于一层。

51. 卷积与感受野#

二维卷积：用卷积核在输入上滑动做加权求和（严格说是互相关）。

输出尺寸公式：

K 核大小、S 步长、P 填充。

本项目核心用例：PatchEmbed_new 用 Conv2d(1, 768, kernel=16, stride=10) 把 (1,1024,128) 变成 patch 序列：

• 时间轴：(1024 + 0 − 16)/10 + 1 = 101
• 频率轴：(128 + 0 − 16)/10 + 1 = 12
• 共 101 × 12 = 1212 个 patch，每个 768 维

关键概念：

为什么 patch embedding 用卷积实现：等价于”切块 + 展平 + 线性投影”，但实现更简洁、可复用高效卷积实现。这是 ViT 的通用做法。

与 CNN 的区别：CNN 的局部性先验强、数据需求小；ViT 的注意力是全局的、先验弱，需要更多数据或自监督预训练（这正是本项目用 MAE 预训练的原因）。

52. 归一化层：BatchNorm vs LayerNorm#

BatchNorm（BN）：对一个 batch 内、每个通道做归一化

• 训练时用 batch 统计量，推理时用滑动平均；
• 缺点：依赖 batch 大小（小 batch 不稳）、对变长序列/RCNN 不友好、分布式训练需同步统计量。

LayerNorm（LN）：对单个样本、整个特征维做归一化

• 与 batch 无关 → 适合变长序列与 Transformer；
• 与 batch size 解耦 → 小批量也稳定；
• ViT/MAE 的每个 block 里都用 LN（norm_layer=partial(nn.LayerNorm, eps=1e-6)）。

其它：GroupNorm（按通道分组）、RMSNorm（省去均值，LLM 常用）、FrozenBatchNorm（冻结统计量，检测模型常用；timm 会从 torchvision 引入它，这也是本项目”timm 依赖 torchvision”的根源）。

Pre-LN vs Post-LN：原版 Transformer 是 Post-LN（x = LN(x + Attn(x))），ViT 普遍用 Pre-LN（x = x + Attn(LN(x))），训练更稳、可不用 warmup 太多。

53. 残差连接与初始化#

残差（Residual）：

• 反向传播时梯度里含恒等项 1，梯度不会消失；
• 网络可理解为”学习相对于恒等的增量”，训练更容易；
• 使深层网络（ViT 12 层、Transformer 数十层）可训。

DropPath（随机深度）：训练时以概率 p 整个跳过残差分支：

相当于”随机用不同深度的子网络”，是 ViT 的重要正则（本项目 --drop_path 0.1）。

初始化：

• 全零 → 对称性破缺失败，学不动；
• 过大 → 激活爆炸；过小 → 信号衰减；
• Xavier/Glorot：Var(W) = 1/fan_in（适合 tanh/sigmoid）；
• He/Kaiming：Var(W) = 2/fan_in（适合 ReLU）；
• trunc_normal_（截断正态，std=0.02）：Transformer 标配，本项目 models_vit 导入它用于 ViT 权重初始化；
• pos_embed 特殊处理：先用正弦余弦函数初始化，再按尺寸插值（model_utils/pos_embed.py）。

54. 正则化与数据增强#

Dropout：训练时随机置零一部分激活，推理时关闭（等价于集成）。Transformer 常用 drop_rate/attn_drop。

Mixup（本项目用了，且在波形层）：

• 标签线性混合——这要求损失支持软标签，所以必须用 BCEWithLogitsLoss（多标签）而不是需要整数标签的 CrossEntropyLoss；
• 在波形层做（_wav2fbank 里先混波形再算 fbank）比在频谱层更自然，能保留相位一致性（虽然相位最终被丢弃，但混合方式更接近物理叠加）；
• Beta(10,10) 使 λ 集中在 0.5，混合后的样本”像两个都像、又都不完全像”。

SpecAugment（本项目 freqm/timem）：在频谱上随机遮挡若干频带/时间段。作用：让模型不依赖某单一频段（提升鲁棒性），同时等价于数据扩充。注意：freqm/timem 只在训练时开启，推理必须置 0（本项目 audio_conf 里显式写 freqm=0, timem=0）。

Roll-mag 增强（本项目 _roll_mag_aug）：

1
idx = np.random.randint(len(waveform))
2
rolled = np.roll(waveform, idx)              # 循环移位：等价"从任意时刻开始"
3
mag = np.random.beta(10,10) + 0.5            # 0.5~1.5 幅度缩放

作用：模拟”裁切起点不同”和”音量不同”，成本几乎为零。

其它可加但项目未用的增强：加性噪声（提升抗噪）、房间冲激响应卷积（模拟混响）、速度/音高扰动（sox/librosa.effects）、SpecMix。注意：音高扰动会改变 F0，对”厚薄”可能有副作用，需实验验证。

55. 注意力机制与位置编码#

自注意力（Self-Attention）：把每个 token 映射成 Query、Key、Value 三组向量

逐步理解：

1. QKᵀ：每个 token 与所有 token 的相似度（点积越大越相关）；
2. /√d_k：缩放。若不缩放，点积随维度增大而方差变大 → softmax 饱和 → 梯度消失；
3. softmax：相似度变成”权重分布”（每行和为 1）；
4. ×V：按权重加权求和 → 每个 token 得到”全局上下文聚合”的结果。

多头（Multi-Head）：把 d=768 拆成 h=12 个 64 维子空间并行做注意力，再拼接：

不同头可以关注不同模式（如某些头关注低频谐波、某些关注高频噪声）。头数、维度、层数是 ViT-B 的固定配置：12 层、12 头、768 维。

复杂度：O(n²d)（n 为 token 数）。本项目 n = 1212，1212² ≈ 1.47M 的注意力矩阵——可接受；若 token 数上万（长音频不切片）就会爆显存，这也是”切片处理”的原因之一。

位置编码（ViT 用可学习 + 正弦余弦初始化）：正弦余弦形式

性质：不同频率的正弦组合使”相对位移”可以被线性表示（PE(pos+k) 可由 PE(pos) 线性变换得到），因此有利于表达相对位置。注意本项目 models_vit 里 pos_embed 尺寸固定为 1×1213×768，输入长度变了必须插值——这就是”10 秒切片”的硬约束来源。

2D 位置信息：音频 patch 是 101(时间)×12(频率) 的网格，AudioMAE 用 2D 正弦余弦位置编码（get_2d_sincos_pos_embed），让模型感知”第几帧、第几个频带”。

56. Transformer 与 ViT#

Transformer Encoder Block（Pre-LN 版）：

1
x = x + MHA(LN(x))          # 自注意力子层 + 残差
2
x = x + MLP(LN(x))          # 前馈子层 + 残差  (768 → 3072 → 768, GELU)

ViT 完整前向（对照 models_vit.py::forward_features）：

1
1) x = patch_embed(输入 (B,1,1024,128))            → (B,1212,768)
2
2) x = x + pos_embed[:,1:,:]                       # 加位置编码（丢掉第 0 个，那是给 cls 的）
3
3) cls = cls_token + pos_embed[:,:1,:] → 拼在最前   → (B,1213,768)
4
4) 12 × Block（Pre-LN + MHA + MLP）                 → (B,1213,768)
5
5) global_pool=True：
6
      x = x[:,1:,:].mean(dim=1)   # 丢掉 cls，对 1212 个 patch 平均
7
      out = fc_norm(x)            # LayerNorm
8
   global_pool=False：用 x[:,0] 即 cls token
9
6) head: Linear(768 → 11) → logits

ViT-B 参数量手算（能算说明真懂）：

这解释了 checkpoint 的 1.02 GB：微调时保存的通常包含 AdamW 状态（每个参数 exp_avg、exp_avg_sq 两份）：

与实测 1,024,918,304 字节吻合 → 文件里约 2/3 是优化器状态，推理只用到 1/3，这也是加载要 9–20 秒的原因。（工程优化建议：发布时只保存 model 权重，可把文件缩到 ~345 MB。）

57. Swin 与窗口注意力#

Swin Transformer：把注意力限制在局部窗口内（如 7×7），并在相邻层之间做窗口偏移（shifted window），使信息能跨窗口传播。

优势：复杂度从 O(n²) 降到 O(n)（与图像大小线性），且局部性先验更适合图像/频谱。

本项目用途：MAE 的解码器（decoder_mode=1 → SwinTransformerBlock）。原因：重建任务需要处理全部 1212 个 patch（含 80% mask token），用全局注意力代价太高；Swin 的局部窗口既省算力又擅长恢复局部结构（频谱的局部纹理）。

decoder_mode 取值：0 = 全局注意力（原版 MAE），1 = Swin 局部（本项目用），>3 为其它扩展（源码里有条件分支）。

58. 自监督学习与 MAE#

自监督的核心思想：不依赖人工标签，从数据本身构造监督信号（“预测被遮住的部分”、“判断是否同一段”等）。

主要流派：

BERT 与 MAE 的类比：BERT 遮 15% 的词让模型填空；MAE 遮 80% 的 patch 让模型重建。为什么 MAE 敢遮这么多：图像/频谱的空间冗余远高于语言（邻近像素/频点高度相关），遮 80% 仍有足够信息；且高掩码率让任务变难，模型被迫学”语义级”表示而非局部插值。

MAE 的数学细节（对照 models_mae.py）：

1. 分块：patchify 把 (B,1,1024,128) → (B,1212,256)（每 patch 16×16×1=256 个像素值）；

2. 随机掩码：

   1
   len_keep = int(L * (1 - mask_ratio))        # L=1212, ratio=0.8 → 保留 242
   2
   ids_shuffle = argsort(noise)                 # 随机排列
   3
   x_visible = gather(x, ids_shuffle[:, :len_keep])
   4
   mask = 1 表示被遮（按 ids_restore 还原顺序）

3. 编码：只把可见的 242 个 patch 送进 encoder（省 ~80% 算力）；

4. 解码：把 242 个编码结果与 970 个 mask_token 按 ids_restore 拼回完整序列 → 加 decoder_pos_embed → 8 层 Swin 解码器；

5. 重建：decoder_pred: Linear(512 → 256)，输出每个 patch 的 256 个像素值；

6. 损失（只在被遮 patch 上算）：

若 norm_pix_loss=True（本项目开启），先对每个 patch 做归一化：

再算 MSE。为什么归一化：不同 patch 的能量差异很大（低频强、高频弱），不归一化会让损失被高能量 patch 主导；归一化后每个 patch 权重均衡，重建质量更均匀。

非对称设计的三个好处：① 编码器只算 20% → 训练快；② 解码器可以很浅（8 层 / 512 维 vs 编码器 12 层 / 768 维）；③ mask token 只在解码器出现 → 编码器学的表示更”干净”（不含占位符信息）。

微调时怎么用预训练权重：把 encoder 权重载入 vit_base_patch16，丢弃 decoder（它的任务已完成）。本项目 main_finetune_as.py --finetune 就是这个流程。

59. 微调策略与逐层学习率衰减#

微调的学习率通常比预训练小 1–2 个数量级，且逐层衰减（第 42 节）：浅层学的是通用频谱结构，改动越小越不容易灾难性遗忘。

原型（prototype）思路与本项目的对照：本项目的物理量化权重本质是一个”线性原型方向”，可与深度特征做后期融合（late fusion）——这与”早期融合（把物理特征拼进模型输入）“是两种可选设计；本项目选了后期融合，好处是模块解耦、可独立迭代（这也是为什么”物理常量”可以手工更新而不必重训模型）。

60. 混合精度训练（AMP）#

动机：fp32 占 4 字节、算力需求大；fp16/bf16 占 2 字节，在支持 Tensor Core 的 GPU 上可提速 2–3 倍、省一半显存。

格式对比：

Loss Scaling 原理（fp16 必需）：梯度可能小到 1e-8 → fp16 下溢成 0 → 参数不更新。解决：先把 loss 放大 S 倍，反传得到放大 S 倍的梯度，更新前再除以 S：

NativeScaler（本项目 loss_scaler = NativeScaler()）还会动态调整 S：若出现 inf/nan 就减小 S 并跳过该步。

本项目代码：

1
with torch.cuda.amp.autocast():          # 前向用 fp16（部分算子保持 fp32）
2
    output = model(images)
3
    loss = criterion(output, target)
4
loss_scaler(loss, optimizer, ...)        # 缩放后的反向与更新

CPU 上的行为：torch.cuda.amp.autocast() 在无 CUDA 时会打印警告并自动禁用（本项目日志里那句 User provided device_type of 'cuda', but CUDA is not available. Disabling 就是它）——不影响数值正确性，只是没有加速。

61. 分布式训练 DDP#

为什么需要：ViT-B 在 ImageNet/AudioSet 规模上单卡训不完；且大 batch 通常带来更稳的梯度估计。

DDP（DistributedDataParallel）原理：

1
每张卡一份模型副本（参数相同）
2
  ├─ 各自读不同的数据子集（DistributedSampler 按 rank 切分）
3
  ├─ 各自前向 + 反向，得到本地梯度
4
  ├─ all-reduce 求平均梯度  ← 关键通信
5
  └─ 各自用同一梯度更新参数（因此参数始终保持一致）

相关 API（本项目用到）：

有效批大小（effective batch size）：

梯度累积（accum_iter）是”显存不够时用小步数凑大 batch”的手段：多次前向累积梯度、到 accum_iter 次再更新一次。学习率按 eff_batch 缩放（第 42 节）。

单卡如何跑：去掉 torch.distributed.launch，加 --dist_eval 关闭，并把 --batch_size 调小即可（本项目 inf.sh 里就是 --nproc_per_node=1）。

注意：DDP 下 BatchNorm 需要 SyncBatchNorm 才能跨卡统计（本项目用 LayerNorm，无此问题——这也是 Transformer 对分布式更友好的一个原因）。

62. 音频表示的选择#

音频进神经网络有四条路，各有取舍：

本项目的选择逻辑：

• 主干是视觉 Transformer（ViT），天然吃”图像” → 需要二维表示 → 选 fbank（128 mel × 1024 帧）；
• 数据规模不足以支撑从波形端到端训 ViT → 用 log-mel 降低输入复杂度；
• 与上游 AudioMAE/AST 代码兼容（同款 fbank 管线）→ 可直接复用预训练权重。

取舍核心：fbank 是”人为设计的归纳偏置”（梅尔刻度 + 对数压缩），在数据有限时比”让网络自己学”更稳。

63. AST 与 AudioMAE#

AST（Audio Spectrogram Transformer）：

• 首个纯注意力（无卷积）的音频分类模型；
• 把 128×1024 的 log-mel 频谱切成 16×16 patch（stride 10，重叠），送 ViT；
• 输出多标签（AudioSet 527 类），用 BCE + mAP 评估；
• 在 AudioSet 上超过 CNN 模型，证明”频谱图 = 图像”这条路可行。

AudioMAE：

• 在 AST 的思路上引入 MAE 自监督预训练：先用海量无标注音频学通用频谱表示，再微调；
• 保留 AST 的输入格式与 ViT 主干，因此预训练权重可以迁移到 AST 风格的分类任务；
• 关键改进：2D 时频掩码（同时遮时间段与频带段）、Swin 局部注意力解码器、norm_pix_loss。

本项目的继承关系（读代码时的定位依据）：

1
AudioMAE (facebookresearch)
2
   ├─ models_mae.py  ──► TimbreMask/models_mae.py（几乎原样，加 decoder_mode / roll_mag_aug）
3
   ├─ models_vit.py  ──► TimbreMask/models_vit.py 与 html/model/models_vit.py（分类用）
4
   ├─ dataset.py     ──► 同款 AudiosetDataset（AST 格式 JSON + class_labels_indices.csv）
5
   └─ 数据格式       ──► {"wav":..., "labels":"/mid/1,/mid/2"}（AST 风格）

项目在 AudioMAE 之上做的三处定制（这是”复用而不是照抄”的证据）：

1. 自定义标签集：把 AudioSet 的 527 类换成 11 类自定义音色标签（/t/…、/r/…、/b/…、/s/…）；
2. 评估指标：stat.py 里加上 group_acc（按厚薄/虚实/明暗/性别分组算组内准确率）；
3. 工程简化：html/model/inference.py 把训练框架里的推理逻辑抽成 run_inference()，供 Flask 调用。

64. 2D 时频掩码#

一维掩码（原版 MAE）：随机遮住序列中的若干 patch。 2D 时频掩码（AudioMAE，本项目微调也开）：

1
# models_vit.py::random_masking_2d（use_custom_patch=True 时）
2
T, F = 101, 12                      # 时间 × 频率 的 patch 网格
3
len_keep_T = int(T * (1 - mask_t_prob))    # 按时间轴遮 20%
4
len_keep_F = int(F * (1 - mask_f_prob))    # 再按频率轴遮 20%

为什么要在两个方向分别遮：

1. 时间方向遮挡 → 迫使模型用上下文推断缺失时间段（学时间连续性）；
2. 频率方向遮挡 → 迫使用其它频带推断被遮频带（学频带间相关性，例如”低频谐波缺失时如何从高频推断音色”）；
3. 二者分别施加，比”随机散点遮挡”更接近真实损坏（真实的音频缺失常是”整段静音”或”某频段被滤波掉”）。

参数含义：mask_t_prob=0.2 表示遮 20% 的时间 patch（约 20 帧 ≈ 200 ms 的段落），mask_f_prob=0.2 表示遮 20% 的频带（约 2.4 个 16-wide 频带）。

注意：掩码是训练技巧。本项目推理时 audio_conf 里 freqm=0, timem=0，且 mask_t_prob=mask_f_prob=0.0，即”不遮”——保证推理确定性。

65. 片段切分与聚合、多标签与多任务#

片段（chunk）切分：因为 pos_embed 固定（1213），模型只能吃 1024 帧（≈10.24 秒）：

1
num_chunks = n_frames // target_length       # 完整片段数
2
# 不足一个片段 → ZeroPad2d 补零成一个片段

聚合（aggregation）：

注意：聚合是推理策略，不影响模型本身；但它会改变结果分布（max 更激进、mean 更保守），第 4 篇可以把它当作实验变量。

多标签（multi-label）：一条语音同时拥有多个标签（厚薄 2 且 虚实 3 且 明暗 1 且 女声）→ 11 维输出用 sigmoid + BCE。

多任务（multi-task）与辅助标签：11 类中的性别（male/female）不是评估目标，而是辅助任务。它带来三个好处：

1. 共享层得到额外监督：模型为了学好性别，必须提取与声学相关的特征（如基频范围），这些特征对音色判断也有用；
2. 缓解过拟合：更多监督信号 = 更强的约束；
3. 实用副产品：系统可顺带报告性别。

多任务损失：本项目其实是把多任务当成”多标签”统一用一个 BCE 处理（无任务权重）；更精细的做法是给不同任务加权（如 L = L_thick + L_real + L_bright + 0.3·L_sex），是可选改进点。

66. 评估口径：mAP vs 组内准确率#

为什么要补做”两路线一致率”：融合逻辑假设”模型与物理分在多数样本上一致，仅在少数疑难样本上分歧”。若实测一致率很低，说明融合规则（阈值 20）不成立——这是复现中最有价值的验证性实验之一。

67. HTTP 协议与 multipart/form-data#

HTTP 请求结构：

1
POST /api/evaluate HTTP/1.1          ← 请求行：方法 + 路径 + 版本
2
Host: example.com                    ← 头部
3
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryXXXX
4
Content-Length: 12345
5

6
<二进制/文本请求体>                   ← 实体

常用方法：GET（取）、POST（创建/提交）、PUT/PATCH（更新）、DELETE（删）。 状态码：2xx 成功（200）、3xx 重定向、4xx 客户端错（400 参数错、413 太大、404 不存在）、5xx 服务端错（500 内部错误）。本项目录音报错时前端收到 500。

multipart/form-data 详解（文件上传的标准格式）：请求体被 boundary 分隔成多个”部件”，每个部件有自己的头部：

1
------WebKitFormBoundaryXXXX
2
Content-Disposition: form-data; name="audio"; filename="recording.wav"
3
Content-Type: audio/wav
4

5
<文件二进制数据>
6
------WebKitFormBoundaryXXXX--

• boundary 是分隔字符串（浏览器自动生成）；
• 前端用 FormData.append('audio', blob, 'recording.wav') 构造；
• 后端 Flask 用 request.files.get('audio') 取出（name 必须一致）；
• 注意：Content-Type 边界与 Content-Length 必须由客户端正确设置（用了 fetch + FormData 就自动处理）。

其它常见 Content-Type：application/json（JSON 体）、application/x-www-form-urlencoded（表单）、audio/wav（裸音频）。

68. 同源策略、CORS 与安全上下文#

同源：协议 + 域名 + 端口三者完全相同。

同源策略：浏览器默认禁止页面用 JS 读取”跨源”响应（防 CSRF/信息泄露）。本项目前后端同源（都用 http://127.0.0.1:5001 提供），所以不需要 CORS。

CORS（跨域资源共享）：如果前端部署在 a.com、后端在 b.com，后端要返回：

1
Access-Control-Allow-Origin: https://a.com

并在预检请求（OPTIONS）中允许相应方法与头部。本项目若拆分部署（前端静态托管 + 后端 API）就需要加 CORS。

安全上下文（Secure Context）：浏览器规定只有 HTTPS 或 localhost 才允许 getUserMedia（麦克风）。这是为什么部署到域名时必须配 HTTPS——否则页面上”录音”按钮会直接失败（连权限弹窗都不会出现）。

HTTPS 要点：TLS 握手 → 非对称加密协商会话密钥 → 对称加密传输；证书由 CA 签发，验证域名归属。部署时 Nginx 终结 TLS（证书装在 Nginx），后端仍走 HTTP 内网通信。

69. Flask、WSGI 与请求生命周期#

WSGI：Python Web 服务器与应用的接口标准（app(environ, start_response)）。Flask 应用是 WSGI 应用，gunicorn/uwsgi 是 WSGI 服务器。

Flask 请求生命周期：

1
请求 → WSGI 服务器 → Flask App
2
   ├─ URL 路由匹配（@app.route）
3
   ├─ 进入请求上下文（request / session 可见）
4
   ├─ 执行视图函数 → 返回响应对象（字符串/JSON/模板渲染结果）
5
   └─ 响应返回 → 中间件/after_request → 客户端

本项目用到的 Flask 概念：

为什么生产不能用 debug=True：调试器允许从浏览器执行任意 Python 代码（Werkzeug 调试页的经典漏洞），app.run 单线程也不够用。

70. gunicorn 与反向代理#

gunicorn 工作模型：

1
gunicorn（master 进程）
2
   ├─ worker 1（同步/gevent，独立进程）
3
   ├─ worker 2
4
   └─ …

• 同步 worker：一次处理一个请求，模型推理是 CPU 密集的，够用；
• worker 数建议：2×CPU + 1（但本项目必须为 1：每个 worker 会各自加载约 1 GB 模型 → 内存 N × 1 GB，且推理本身 CPU 占满）；
• --timeout 900：请求超时（首次加载模型 + 长音频推理很慢）；
• 预加载（--preload）可让所有 worker 共享一份模型内存（复制写时技术），但本项目 -w 1 已无必要。

Nginx 反向代理的作用：

本项目关键配置（否则会 502/413）：

1
client_max_body_size 60m;        # ≥ 后端 50MB
2
proxy_read_timeout 900s;         # 推理慢，不能沿用默认 60s

SELinux：RHEL 系默认禁止 Nginx 主动连后端端口，需要 setsebool -P httpd_can_network_connect 1。

71. 前端录音：getUserMedia / MediaRecorder#

流程：

1
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });  // 请求麦克风
2
const rec = new MediaRecorder(stream, { mimeType: 'audio/webm;codecs=opus' }); // 选择编码容器
3
const chunks = [];
4
rec.ondataavailable = e => { if (e.data.size > 0) chunks.push(e.data); };     // 分片回调
5
rec.onstop = () => { const blob = new Blob(chunks, { type: rec.mimeType }); }; // 合成 Blob
6
rec.start(250);   // 每 250ms 抛一次数据（timeslice）
7
rec.stop();

关键概念：

常见坑：

• 忘写 stream.getTracks().forEach(t => t.stop()) → 麦克风一直占用（指示灯不灭）；
• audioChunks 未清空 → 第二次录音混入第一次数据；
• 用 ondataavailable 的 e.data.size === 0 检查空片（本项目就做了）；
• 移动端与 Safari 的 MIME 兼容性（要 fallback）。

72. Web Audio API 与音频解码#

核心对象：

本项目用它解决了什么：浏览器能解 Opus/AAC/MP3，于是”解码 → 重编码 WAV”在前端完成，后端彻底不需要 ffmpeg（第 24 节）。

注意：decodeAudioData 需要 ArrayBuffer（不是 Blob），所以要 await blob.arrayBuffer()；解码是异步的，必须 await。

73. Blob / ArrayBuffer / TypedArray#

互转：

1
const buf = await blob.arrayBuffer();            // Blob → ArrayBuffer
2
const view = new DataView(buf);                  // 读写视图
3
const blob2 = new Blob([buf], {type:'audio/wav'}); // ArrayBuffer → Blob

本项目：audioBufferToWavBlob 用 ArrayBuffer 建 44 + dataSize 字节 → DataView 写头 → 循环写 int16 样本 → new Blob([buffer], {type:'audio/wav'})。

74. JS 异步与 fetch#

事件循环（Event Loop）：JS 单线程，通过”任务队列 + 微任务队列”实现并发。关键影响：任何耗时操作（解码、网络、大循环）都会冻结 UI；因此解码用异步 API，requestAnimationFrame 用于动画。

Promise 与 async/await：

1
async function evaluateAudio() {
2
    const res = await fetch('/api/evaluate', { method: 'POST', body: formData });
3
    if (!res.ok) throw new Error(`Server error: ${res.status}`);
4
    const data = await res.json();
5
    showResults(data);
6
}

• fetch 返回 Promise<Response>，只有网络错误才 reject；HTTP 4xx/5xx 需要手动检查 res.ok（本项目就得处理 500）；
• async 函数返回 Promise，await 暂停该函数直到 Promise 完成；
• 异常必须 try/catch，否则未捕获的 Promise 拒绝会导致静默失败（本项目 catch 里 alert 提示并复位）。

阻塞陷阱（复现时可能遇到）：前端把几 MB 的 WAV 用 JS 循环逐样本编码时，若是 10 秒以上录音可能造成几百毫秒卡顿（本项目 12 秒 ≈ 384K 样本，可接受；若要录几分钟，应改 Web Worker）。

75. Canvas 与 Chart.js#

Canvas：位图绘制上下文（getContext('2d')），适合逐帧绘制（本项目画录音波形）。常用 API：clearRect / beginPath / moveTo / lineTo / stroke / fillRect。

Chart.js（本项目用 4.4.4，CDN 引入）：

1
new Chart(ctx, {
2
  type: 'radar',
3
  data: {
4
    labels: ['厚薄', '明暗', '虚实'],
5
    datasets: [{ data: [scores.thickness, scores.brightness, scores.solidity] }]
6
  },
7
  options: { scales: { r: { min: 0, max: 3, ticks: { stepSize: 1 } } } }
8
});

• type：radar（雷达图）、bar（柱状图）、line 等；
• data.labels / data.datasets[].data 是核心数据结构；
• options 控制轴范围、刻度、动画、tooltip；
• 仪表盘常用套路：固定 min/max 才能让不同样本可直接对比（本项目雷达图 0–3 级）。

离线部署注意：CDN 引入在纯内网会白屏 → 需把 chart.umd.min.js 下到 static/ 并改 <script src>。

响应式细节：canvas 需要容器有明确高度，否则图表高度为 0（常见”图表不显示”原因）。

76. 进程、线程、GIL 与并发#

• 进程：独立内存空间；线程：共享内存、切换开销小；
• GIL（全局解释器锁）：CPython 同一时刻只允许一个线程执行 Python 字节码 → CPU 密集型任务多线程无加速（但 numpy/PyTorch 的底层 C 运算会释放 GIL，所以矩阵运算仍能并行）；
• 因此 CPU 密集的 Python 服务常多进程扩展（gunicorn 多 worker）；
• 本项目的内存约束：Torch 模型常驻内存约 1 GB/进程，所以 -w 1；若要并发更多请求，可以：① 队列排队（当前行为）；② 用 GPU 提升单请求速度；③ 模型量化/ONNX 减小内存后适度加 worker。

并发与队列的直觉：CPU 推理 1030 秒/条 → 单 worker 吞吐约 26 条/分钟。10 人同时提交 → 后面的人等待时间线性增长。生产环境应设置请求队列上限 + 前端提示预计等待时间（这是可以写进改进清单的工程点）。

77. 虚拟环境、wheel 与依赖管理#

为什么”锁版本”重要：深度学习生态版本耦合极强（torch↔torchaudio↔torchvision↔timm↔numpy↔numba），不锁版本 → 半年后重装就跑不起来。本项目实测可用组合已记录在文档里（torch 2.8.0+cpu 等），建议直接固化为 requirements.lock.txt。

78. 依赖版本坑的完整回溯（本项目实测）#

方法论：遇到依赖问题按”库→版本→源→二进制依赖”四层排查：① 报错说缺哪个库；② 版本是否与配套库匹配；③ 包源是否给对了构建（CPU/CUDA）；④ 该库是否还需要系统级动态库（DLL/so）。

79. systemd、日志与排错方法论#

systemd 服务最小模板：

1
[Unit]
2
Description=Voice Timbre Evaluation
3
After=network.target
4

5
[Service]
6
WorkingDirectory=/opt/timbre/html
7
ExecStart=/opt/timbre/venv/bin/gunicorn -w 1 -b 127.0.0.1:5001 --timeout 900 app:app
8
Restart=always
9
RestartSec=5
10
Environment=OMP_NUM_THREADS=4
11

12
[Install]
13
WantedBy=multi-user.target

• systemctl daemon-reload && systemctl enable --now timbre；
• systemctl status timbre、journalctl -u timbre -f 看日志；
• Restart=always 保证崩溃自动拉起；
• Environment= 可注入环境变量（如线程数、API Key）。

排错五步法（本项目实战总结）：

1. 读 traceback 的最后几行：File "x.py", line N, in func → 精确定位；
2. 区分环境错与逻辑错：
   • 环境错：ModuleNotFoundError、NoBackendError、cannot load library、Format not recognised；
   • 逻辑错：ValueError: shapes ... not aligned、IndexError、KeyError；
3. 最小复现：把可疑函数单独拿出来喂一条已知音频（本项目两个 bug 都靠这招定位）；
4. 形状即真相：数值/深度学习报错先 print(x.shape)，90% 是形状问题；
5. 改完必回归：跑”通过用例 + 曾经失败用例”（本项目修完 speechprocess 后专测”强制三围 level=1”以覆盖原盲区）。

日志分级建议：INFO 记请求与结果摘要、WARNING 记可疑输入（短音频/削波）、ERROR 记异常与堆栈、DEBUG 记形状与中间值（生产关掉）。

80. 资源估算（会算才敢上线）#

部署建议汇总：CPU 4 核 / 8 GB 内存 / ≥5 GB 磁盘可满足小规模演示；并发需求高时上 GPU + 队列。

实验 1：观察混叠（10 kHz 用 16 kHz 采样会变成 6 kHz）#

1
import numpy as np
2
sr_high, sr_low, dur = 100000, 16000, 0.02
3
t = np.arange(int(sr_high*dur))/sr_high
4
x = np.sin(2*np.pi*10000*t)                     # 真实 10 kHz
5
xs = x[::int(sr_high/sr_low)]                   # 朴素抽取（无抗混叠）
6
f = np.fft.rfftfreq(len(xs), 1/sr_low)
7
spec = np.abs(np.fft.rfft(xs))
8
print('峰值频率 ≈', f[np.argmax(spec)], 'Hz  ← 应为 6000 (16000-10000)')

实验 2：验证量化 SNR 公式（每个 bit 约 6 dB）#

1
import numpy as np
2
for bits in [8, 12, 16]:
3
    q = 2.0/(2**bits)                            # 满量程 2.0 的量化步长
4
    x = np.sin(2*np.pi*440*np.arange(16000)/16000)
5
    xq = np.round(x/q)*q
6
    noise = x-xq
7
    snr = 10*np.log10(np.mean(x**2)/np.mean(noise**2))
8
    print(f'{bits} bit: SNR={snr:5.1f} dB  (理论 {6.02*bits+1.76:5.1f} dB)')