2026-09-23 【音色评估】项目拆解（三）：逐行拆解代码

系列定位：5 篇走完「调研摸底 → 环境跑通 → 代码拆解 → 调试改参 → 复盘沉淀」。 本篇目标：把”能跑通的代码”变成”能讲清楚的代码”——不看源码也能说出每一步在做什么、数据形状怎么变、每个常量从哪来。与前面的衔接：第一篇给了全景（双路线融合、四模块）；第 1.5 篇给了底层知识（STFT/梅尔/fbank/Fisher/ViT）；第二篇把环境跑通了，并留下两个”跑通即暴露”的 bug。本篇顺着那条调用链往下拆。前置认知：本项目不是”一个模型 + 一个网页”，而是两条独立音频管线 + 一层融合规则。拆代码的核心就是先把这两条线分开，再各自往下读。

0. 拆代码的方法：不要从第一行读到第一千行#

我用的顺序是三步法，顺序不能换：

步骤	做什么	产出	判据
① 画调用链	从入口（`app.py`）逆推到末端，只记”谁调用谁”	一张链图	能指出任何函数的调用者
② 定数据契约	每一层的入参 / 出参 / 形状 / 单位	一张数据流表	能说出”这层的输入是多少维、什么采样率”
③ 深挖核心函数	只精读 3–5 个真正决定结果质量的函数	逐行注释	能解释为什么这么写、改了会怎样

优先级很重要：入口 > 数据形状 > 常量来源 > 工具函数。工具函数（model_utils/*）最后看，因为它们基本是”从上游仓库搬来的”，不影响业务正确性。

1. 目录结构：先分清”主链路 / 工具 / 一次性脚本”#

html/ 解压后看着文件不少，但按角色其实只有四类：

角色	文件	说明
入口	`app.py`	Flask 应用，唯一定义 `/api/evaluate` 的地方
主链路（核心）	`talk.py`、`inference.py`、`speechcheck/speechprocess.py`	三层：编排 → 模型推理 → 物理量化与融合
模型与工具	`model/models_vit.py`、`model/dataset.py`、`model/model_utils/*`、`model/labels/class_labels_indices.csv`、`model/checkpoint-300.pth`	模型定义与权重；`model_utils` 是从上游 AudioMAE 搬来的工具
前端	`templates/index.html`、`static/main.js`、`static/style.css`	录音/上传、图表渲染
运行期目录	`audio_data_analysis/`、`output_dir/`、`temp/`	上传音频落盘（数据回流的雏形）、输出、临时
非主链路脚本	`evaluate_thickness_accuracy.py`、`create_photo.py`、`model/inference.py`	离线评测（macOS 路径写死）、用 LLM 生成雷达图（含硬编码 key）、另一份推理脚本副本

三个容易误解的点：

inference.py 有两份（根级与 model/ 内）。主链路用的是根级那份——它默认的 label_csv / checkpoint 指向 model/labels/...、model/checkpoint-300.pth，与 app.py 运行时的工作目录一致；model/inference.py 是按”在 model/ 目录内执行”写的副本，属历史遗留。
model_utils/stat.py 里不仅有指标函数，还硬编码了标签分组（{'thick':[0,1,2], 'real':[3,4,5], 'bright':[6,7,8], 'sex':[9,10]}）——它同时是”标签顺序的唯一书面证据”。
timbre-deploy 之外的一切（TimbreMask/、frenquence_check/、art_audio/）都不参与 Web 运行，拆代码时先放一边（它们的作用在第五节讲）。

2. 完整调用链与”数据契约表”#

主链路只有四层，但每一层都在改变数据的形态：

1
HTTP 请求(multipart)
2
  └─ app.py        /api/evaluate
3
       └─ talk.py        model_evaluation(path)
4
            ├─ inference.py        run_inference(path)      ← 模型侧管线
5
            └─ speechcheck/speechprocess.py  speech_process(path, scores)  ← 物理侧管线 + 融合
6
  └─ JSON 响应 → static/main.js 渲染

把”形状变化”列成表，这张表就是本篇的核心：

层	输入	处理	输出（形状/单位）
app.py	multipart 文件	落盘临时文件 → `librosa.load(sr=16000)` → `sf.write` 16 kHz WAV	文件路径 + 16 kHz 单声道 WAV
inference.py	WAV 路径	`torchaudio.load` → 去直流 → Kaldi fbank（128 mel，10 ms 帧移）	`(帧数, 128)` 对数梅尔
同上	`(帧数,128)`	切 1024 帧片段（不足补零）→ `(x-mean)/(std*2)` → 加 batch/channel 维	每片段 `(1, 1, 1024, 128)`
同上	`(1,1,1024,128)`	PatchEmbed：`Conv2d(kernel=16, stride=10)`	101 × 12 = 1212 个 patch（每个 768 维）
同上	1212 patch + 1 cls	ViT-B 12 层 → global pool → 线性头	11 维 logits
同上	11 维 logits	逐片段 `sigmoid` → 多片段 `mean` 聚合	11 维概率（0–1）
talk.py	11 维概率	组内取最大：`[0:3]`→厚薄、`[3:6]`→虚实、`[6:9]`→明暗	三维等级 1/2/3 + change
speechprocess.py	WAV 路径 + 等级	STFT(2048/512) → 能量谱 → 频点能量占比 → 12 段求和（+3 综合量）	每维 15 维特征向量
同上	15 维 + 等级	选模板 → `raw = 100·Σ(w·e)` → `f = a·raw + b`	每维一个映射分 `f`
同上	`f` 与 `center`	偏差 > 20 → 跨级 ±1（最多一级）	修正后等级 + `scores_change`
最终	—	组装	`scores / scores_change / weights_scores / _features / _band_name / evaluation`

这张表能回答 90% 的追问。比如”为什么明暗的分数能到几千”——因为第 12 个特征量纲特殊再被 a≈26 放大；“为什么必须是 10 秒切片”——因为 pos_embed 固定为 1213。

3. `app.py`：只有 6 步，但每步都有原因#

1
app.config["MAX_CONTENT_LENGTH"] = 50 * 1024 * 1024        # 上传上限 50MB
2

3
@app.route("/api/evaluate", methods=["POST"])
4
def evaluate():
5
    audio_file = request.files.get("audio")                  # ① 取 multipart 文件
6
    ...
7
    temp_path = os.path.join(saved_dir, f"temp_{timestamp}_{uid}_{original_filename}")
8
    open(temp_path, "wb").write(audio_bytes)                 # ② 先写原始文件（librosa 需要路径）
9
    y, sr = librosa.load(temp_path, sr=16000)                # ③ 统一重采样到 16 kHz
10
    os.remove(temp_path)                                     # ④ 删临时
11
    sf.write(wav_save_path, y, 16000)                        # ⑤ 存标准 16k WAV
12
    result = model_evaluation(wav_save_path)                 # ⑥ 交给 talk.py
13
    return jsonify(result)

逐条解读：

步骤	为什么这么写	潜在问题
① 取文件	字段名固定 `audio`，前端 `FormData.append('audio', ...)` 必须对齐	字段名不一致 → 400
② 落原始文件	`librosa.load` 接受路径，比内存流省事；也便于事后排查	异常路径不会清理 temp 文件（会慢慢堆积）
③ `sr=16000`	与后续物理链路的采样率约定相关（见第 7 节的反直觉点）	该重采样只对保存的 WAV 生效，物理链路内部还会再转一次
④⑤ 删临时 + 存标准 WAV	统一成”16 kHz 单声道 WAV”这一种输入，向后兼容所有格式	用户上传的原始格式信息在这一步丢失
⑥ 调 `model_evaluation`	业务编排放在 `talk.py`，`app.py` 只做 IO	整个推理串行，无并发与队列
异常处理	`except` 里 `traceback.print_exc()` + 返回 500	`debug=True` 只适合开发；生产要关（见第二篇部署部分）

4. `talk.py`：30 行编排，藏着”标签顺序”这个致命约定#

1
def model_evaluation(audio_path):
2
    result = run_inference(audio_path)                       # ① 模型推理
3
    if not result['success']:
4
        return _fallback_evaluation()                        # ② 失败兜底（随机分数 + 模板文字）
5
    raw = result['raw_outputs']                              # ③ 11 维概率
6
    scores = {
7
        "thickness":  max_index(raw[0:3]),                   # ④ 组内取最大 → 1/2/3
8
        "solidity":   max_index(raw[3:6]),
9
        "brightness": max_index(raw[6:9]),
10
    }
11
    speech_features = speech_process(audio_path, scores)     # ⑤ 物理量化 + 跨级修正
12
    speech_features["evaluation"] = evaluation
13
    return speech_features

关键点：raw[0:3] / [3:6] / [6:9] 这个切法不是随便写的，它必须与 model/labels/class_labels_indices.csv 的行序一致：

下标	CSV `mid`	`display_name`	语义
0–2	`/t/5e5a0 …`	thick1/2/3	厚薄 C/B/A
3–5	`/r/f4c29 …`	real1/2/3	虚实 C/B/A
6–8	`/b/03acc …`	bright1/2/3	明暗 C/B/A
9–10	`/s/07cf4 …`	male / female	性别（推理未用，训练时的辅助标签）

这是全项目最脆弱的一处约定：改 CSV 行序、或在训练时换了标签顺序，raw[0:3] 就会静默错位——不报错，只是”厚薄”变成”明暗”。而 stat.py 里那份硬编码分组是唯一能交叉验证的地方。

另外两点：

文件里有一大段被注释掉的 dashscope(Qwen) 调用：原本想让大模型写评价文字。现在 evaluation 是固定模板字符串，所以评价文字与分数无关——汇报时别说成”AI 生成报告”。
_fallback_evaluation() 在推理失败时返回随机分数。它的存在意味着：接口返回 200 不代表模型真的跑了，必须看 success 或看日志。

5. `inference.py`：模型侧管线（参数即契约）#

5.1 默认参数就是”部署契约”#

1
parser.add_argument('--nb_classes', default=11)                      # 11 类，与 CSV 行数一致
2
parser.add_argument('--model', default='vit_base_patch16')
3
parser.add_argument('--device', default='cpu')                       # 默认 CPU 推理
4
parser.add_argument('--checkpoint', default=.../model/checkpoint-300.pth)
5
parser.add_argument('--label_csv',  default=.../model/labels/class_labels_indices.csv)
6
parser.add_argument('--threshold', default=0.5)                      # 只影响 predictions 列表
7
parser.add_argument('--aggregate', default='mean', choices=['mean','max'])

5.2 Patch Embedding：1212 个 patch 是怎么来的#

1
class PatchEmbed_new(nn.Module):
2
    def __init__(self, img_size=224, patch_size=16, in_chans=3, embed_dim=768, stride=10):
3
        self.proj = nn.Conv2d(in_chans, embed_dim, kernel_size=patch_size, stride=stride)

输入 (1, 1024, 128)（时间帧 × 梅尔带）时：

1
时间方向：(1024 − 16) / 10 + 1 = 101
2
频率方向：(128  − 16) / 10 + 1 = 12
3
patch 总数 = 101 × 12 = 1212        →  pos_embed = 1212 + 1(cls) = 1213

两个设计选择值得记住：stride=10 < kernel=16 让 patch 在时间轴重叠（补偿 10 ms 帧移下的时间信息）；1212 这个数字锁死了输入长度，所以长音频必须切 10.24 秒的片段。

5.3 特征与切片：所有常数都必须与训练一致#

1
waveform, sr = torchaudio.load(audio_file)
2
waveform = waveform - waveform.mean()                                  # 去直流
3
fbank = torchaudio.compliance.kaldi.fbank(
4
    waveform, htk_compat=True, sample_frequency=sr, use_energy=False,
5
    window_type='hanning', num_mel_bins=128, dither=0.0, frame_shift=10)   # 128 mel / 10ms
6
...
7
chunk = (chunk - mean) / (std * 2)          # audioset: mean=-4.2677393, std=4.5689974
8
chunk = chunk.unsqueeze(0).unsqueeze(0)     # → (1, 1, 1024, 128)

细节	为什么不能改
`num_mel_bins=128` / `frame_shift=10`	与训练时完全绑定；改了输入分布就变
`mean/std` 用 AudioSet 统计值、且 `std*2`	训练时的归一化常量，推理必须照抄；`×2` 是 AudioMAE/AST 惯例
不足 1024 帧用 `ZeroPad2d` 补零	与训练时的 padding 方式一致（不能换成长度自适应）
`dither=0.0`	推理必须确定，抖动是训练时才用的

5.4 推理与聚合：`sigmoid` 而非 `softmax`#

1
output = model(chunk)
2
output = torch.sigmoid(output).cpu().numpy()[0]     # 多标签 → 逐维独立概率
3
...
4
aggregated = np.mean(all_outputs, axis=0)           # 多片段 mean 聚合

多标签（一条音频同时有厚薄等级 + 虚实等级 + 明暗等级 + 性别）→ 用 sigmoid；用 softmax 会强制 11 类竞争，语义就错了；
聚合方式 mean（默认）vs max：这是推理策略，换它结果会变，但不改模型；
阈值 0.5 只用于生成 predictions 列表，talk.py 用的是 raw_outputs 取最大，不依赖阈值。

5.5 装载权重：两行代码，两个坑#

1
checkpoint = torch.load(checkpoint_path, map_location='cpu', weights_only=False)   # 坑 1
2
model.load_state_dict(checkpoint['model'] if 'model' in checkpoint else checkpoint,
3
                      strict=False)                                                # 坑 2

坑 1：PyTorch ≥2.6 默认 weights_only=True，加载旧 checkpoint 会报错 → 必须显式 False；
坑 2：strict=False 允许键不匹配（因为 patch_embed/pos_embed 被替换过）。风险是它会静默丢弃权重——如果结构真的对不上，程序照样”跑得通”，但输出就是随机噪声。工程上应当打印并检查返回的 missing_keys。

顺带一个由体积反推的结论：checkpoint-300.pth ≈ 1.02 GB，而 ViT-B 约 86M 参数（fp32 ≈ 345 MB）→ 文件里约 2/3 是 AdamW 优化器状态。这就是加载要 10–20 秒的原因，也说明发布时可以只存 model 把体积压到 1/3。

6. `speechprocess.py`：物理侧管线 + 融合规则（全项目最”值钱”的文件）#

6.1 常量区 = 六套模板 + 三套频段#

1
error_threshold = 20
2
check_bands = [ [12 段厚薄频段], [12 段虚实频段], [12 段明暗频段] ]   # 3×12，等梅尔间隔
3
bands_weights = [6 行权重]        # 长度 13 / 12 / 15 / 13 / 13 / 13
4
bands_index   = [6 行列索引]      # 决定每套模板用 15 维里的哪几维
5
bands_change  = [6 行 [a, b, center]]

维度	频段范围	两套模板	是否含”总能量”列
厚薄	0–1350 Hz	#0（C 级边界）/ #1（B-A 边界）	#0 含、#1 不含
虚实	50–4280 Hz	#2 / #3	#2 含（15 维全用）、#3 含（权重 4.85）
明暗	0–4280 Hz	#4 / #5	#5 只有这一列，权重=1

6.2 `get_energy_pro`：把波形压成 15 个数字#

1
D = librosa.stft(y, n_fft=2048, hop_length=512)      # ① 时频分析
2
E = np.abs(D) ** 2                                   # ② 能量谱
3
p = E.sum(axis=1) / E.sum()                          # ③ 频点能量占比（抗增益的来源）
4
frefeature = comprehensive_frequency_analysis(y, sr) # ④ 总能量 / LF-HF 比 / 谱质心
5
for bands in check_bands:
6
    band_energy_array.append(np.concatenate([band_props, frefeature]))   # ⑤ 12+3=15 维

四个关键理解：

n_fft=2048 → 频率分辨率 ≈ 7.8 Hz；hop=512 → 32 ms 帧移；输出 (1025, 帧数)；
第 ③ 步是”抗音量”的根源：除以总能量后，整体增益被约掉，只剩频谱形状；
12 段边界是等梅尔间隔换算回 Hz 的（m = 2595·log10(1+f/700)），可用明暗维度自检：0–4280 Hz 的梅尔总量 ≈ 2211，2211/12 ≈ 184.3 → 首段边界 ≈ 124 Hz，与代码一致；
后 3 维是”综合量”：总能量（×1e-7）、LF/HF（×0.1）、谱质心（×1e-3），缩放只为量级对齐。

6.3 `cal_features`：一个”防抖”状态机#

1
weights = bands_weights[tpl]; energy = energy_full[bands_index[tpl]]
2
raw = np.sum(weights * energy) * 100
3
f = a * raw + b                                    # 线性映射
4
if level == 1:                                     # C 级
5
    if f > center:
6
        if |f - center| > 20:  → 递归用 #1 模板重算，等级升为 2（is_score_change = 1）
7
        else:                  → 只标记 C+（change = 1）
8
elif level == 2:                                   # B 级
9
    if f > center: 偏差>20 → 升 A；否则 B+
10
    elif f < 0:    偏差>20 → 降 C；否则 B-
11
else:                                              # A 级
12
    if f < center 且 f < 0 且偏差>20 → 降 B；否则 A-

三条设计逻辑（面试/汇报常问）：

逻辑	含义
阈值 20 是防抖容差	物理分与模型判断接近时不动等级，避免抖动
只调一级	防止物理分异常导致离谱结果（例如从 A 直接掉到 C）
`change` 与 `is_score_change` 不同	前者是给前端看的记号（C+/B-/A-），后者才真的改等级

注意 elif f < 0 这个分支——负分在这里是被”合法使用”的信号（B→C 降级条件），所以内部不能简单 clamp；但把它当”0–100 权重分”展示给用户是错的（第四篇会专门拆这件事）。

6.4 那个形状 bug：为什么 `(12,) (13,)`#

模型判 C 级、且物理分显著偏高时，代码会换用下一套模板重算（#0 → #1）。而两套模板的列集不同：

1
#0 用 bands_index[0] = [0..12]  → 13 个特征，权重 13 个  ✓
2
#1 用 bands_index[1] = [0..11]  → 12 个特征，权重 12 个  ✓

原实现在递归时把已经切好的 13 维向量传给了需要 12 维的模板 → weights(12) * energy(13) 直接报 operands could not be broadcast together。

修法：让 cal_features 始终接收完整的 15 维向量，在函数内部按当前模板的 bands_index 现切：

1
def cal_features(tpl, energy_full, level):
2
    idx = bands_index[tpl]
3
    energy = np.asarray(energy_full)[idx]        # 每个模板切自己的列
4
    raw = np.sum(bands_weights[tpl] * energy) * 100
5
    ...
6
    # 递归时同样传 energy_full，列集自动跟随模板

这个 bug 的教训比 bug 本身更值钱：当一个函数”能跑通大部分样本”时，最危险的是未被覆盖的分支。我当时用”强制三围都=1 级”专门去踩这条分支，才把它逼出来。

6.5 `speech_process`：按等级选模板并汇总#

1
for i, name in enumerate(["thickness", "solidity", "brightness"]):
2
    tpl = i*2 if scores[name] == 1 else i*2 + 1      # C 级用偶数模板，B/A 用奇数模板
3
    f, change, is_change = cal_features(tpl, energy_pro[i], scores[name])
4
    scores[name] += is_change                         # 跨级修正

返回值（也就是前端拿到的字段）：scores（修正后等级）、scores_change、weights_scores（映射分）、thick/solidity/brightness_features（所用模板的特征向量）、*_band_name（频段名，前端柱状图 X 轴）。

7. 两条音频管线为什么要分开（本篇最重要的认知）#

同一个项目里，音频被处理了两次，参数完全不同：

对比项	模型侧（`inference.py`）	物理侧（`speechprocess.py`）
采样率	`torchaudio.load` 原始采样率	`librosa.load(path)` → 默认 22050 Hz
特征	Kaldi fbank：128 维对数梅尔	STFT 后 12 段能量占比 + 3 综合量
时间尺度	10.24 秒切片，逐片推理再 mean	整段平均（无切片）
归一化	`(x-mean)/(std*2)`（AudioSet 常量）	除以总能量（抗增益）
输出	11 维概率 → 等级	15 维 → 0–100 映射分
目的	判别力（黑盒但准）	可解释 + 连续 + 抗音量

为什么要分开而不是统一：

模型侧参数被 checkpoint 锁死（fbank 参数、归一化常量、切片长度），改任一项都等于换模型；
物理侧要的是可解释性与抗增益：必须用”占比 + 可命名的频段”，否则前端柱状图无法标注、也没法解释”为什么是这个分”；
两者互补：模型给离散等级，物理分给连续刻度并在分歧大时修正等级。

复刻提醒：这两条线的采样率并不一致（模型侧用原始，物理侧被 librosa 默认为 22050 Hz）。这不是 bug，但是一个从未被记录的隐含依赖——第四篇会用它做实验（同一音频换采样率，分数能差上千）。

8. 常量迁移链：从科研脚本 → 线上常量（本项目最漂亮的一条线）#

线上那六个常量不是拍脑袋定的，而是从 frenquence_check/ 里的科研脚本”抄”过来的。把链条对上，你才算真的读懂了这套系统：

线上常量	来源脚本/函数	具体做法
`check_bands`（3×12）	`get_fre.py::get_energy_pro`	代码里保留了多套备选 bands，最终固化为三维各自的等梅尔 12 段
`bands_index`（6 行）	`scatterplot.py::cal_value` 的 `t_band_index`、`model.py::filter_np`	决定”用 15 维里的哪几维”——即科研阶段挑出来的特征组合
`bands_weights`（6 行）	`torchmodel.py`（FisherLoss）与 `model.py`（手推梯度）	在专家分级语音上学出的线性判别权重：`loss = (σ₀²+σ₁²)/(μ₁−μ₀)²`
`bands_change`（6 行 `[a,b,center]`）	`scatterplot.py::calbaseline` + `calbound.py`	网格搜索最优分级边界 → 用 `a = 100/(max−min)`、`b = −min·a` 线性映射到 0–100
`error_threshold = 20`	人工经验值	0–100 尺度上的”防抖”容差

可验证的对应关系（拿 #5 模板做例子）：

1
calbound.py 里的区间 : raw ∈ (0.9345, 4.7778)，边界值 line = 2.82
2
线上 bands_change[5] : a = 26.0197, b = −24.315, center = 49.06
3

4
自检：f(raw) = a·raw + b   →  f(0.9345) = 0，f(4.7778) = 100   ✓
5
      center = a·(line − raw_min) = 26.0197 × (2.82 − 0.9345) = 49.06  ✓

由此得到一个非常重要的认知（第四篇的实验全建立在这上面）：

f = a·raw + b = a·(raw − raw_min) —— 分数其实是”原始加权分相对训练集标定区间的线性刻度”。所以：低于区间下界 → 负分；高于上界 → 远超 100（实测 9400）。所谓”0–100 分”只在标定区间内成立。

这条链的工程含义：bands_weights / bands_change 是冻结的实验结果。改采样率、改频段、改特征缩放 → 常量就失效了 → 必须回科研脚本重新标定。常量不是配置，是模型的一部分。

9. 给核心代码加注释的四个”注释位”#

加注释不是把代码翻译成中文，而是把作者没说但你知道的东西写下来。我固定写四类：

注释位	写什么	例子
契约注释	入参/出参/形状/单位	`# 输入 (帧数,128) 对数梅尔；输出 11 维概率（0-1），顺序见 labels CSV`
为什么注释	设计意图（否则后人会”优化”掉）	`# stride=10 < kernel=16：让 patch 在时间轴重叠，补偿 10ms 帧移的时间信息`
坑注释	不能改 / 改了会静默出错	`# strict=False 会静默丢权重；若 missing_keys 非空，输出等于随机噪声`
对拍注释	与谁一致 / 依据是什么	`# 常量值取自 frenquence_check/calbound.py；center = a·(line - raw_min)`

示例（get_energy_pro 加注释后的样子）：

1
def get_energy_pro(path):
2
    """提取一条音频的三维 15 维特征。
3

4
    输入：音频路径（任意格式/采样率，内部按 librosa 默认 22050 Hz 加载）
5
    输出：list[3] —— 每个元素是 [12 段能量占比 + 总能量/LF-HF/谱质心]（15 维）
6
    注意：① 用"能量占比"而非绝对能量，保证抗音量；
7
          ② 12 段边界是等梅尔间隔，与 get_fre.py 的 bands 一致（改动需重标权重）。
8
    """
9
    y, sr = librosa.load(path)                 # 与原项目一致：librosa 默认 22050 Hz（勿改成 16k）
10
    D = librosa.stft(y, n_fft=2048, hop_length=512)   # 频率分辨率 ≈7.8 Hz
11
    E = np.abs(D) ** 2                                # 能量谱
12
    p = E.sum(axis=1) / E.sum()                       # 频点能量占比 → 抗增益的关键
13
    ...

判断注释是否合格的唯一标准：半年后你自己回来看，能不能不查资料就改对。

10. 拆完后应当建立的”认知检查清单”#

能不看代码回答下面 12 个问题，说明本篇真的吃透了：

请求进来后依次经过哪几个文件？各自的入口函数名？
raw_outputs 的 11 个维度分别对应什么？为什么是 11？
1212 这个数字怎么来的？为什么它决定了”必须切 10 秒”？
为什么推理默认 device='cpu'、threshold=0.5 却又不影响判级？
strict=False 有什么风险？怎么自检？
checkpoint 为什么有 1 GB 而参数只占 1/3？
物理侧的 15 维分别是什么？后 3 维各是什么、缩放多少？
为什么用”能量占比”而不是绝对能量？
六套模板是怎么分工的？为什么每维要两套？
error_threshold=20 控制什么？调大调小会怎样？
[a, b, center] 三个数各是什么？能用公式自检吗？
模型侧与物理侧的采样率为什么不同？这会带来什么后果？

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

产出物：

✅ 一张调用链图 + 一张数据契约表（第 2 节）——所有后续讨论的地图；
✅ 四个核心文件的逐段解读（app.py / talk.py / inference.py / speechprocess.py）；
✅ 两条音频管线的对比表与”为什么分开”的结论（第 7 节）；
✅ 常量迁移链：线上六个常量的来源与可自检的数值对应（第 8 节）；
✅ 一个被修复的真实 bug（跨级模板形状不匹配）的完整分析；
✅ 四类注释法与一段”注释前/注释后”示例（第 9 节）。

**下一篇（第四篇：调试改参与变式测试）**将把本篇的”认知”变成”实验”，全部不需要新数据：

阈值扫描：把 error_threshold 从 0 扫到 60，看判定翻转点 —— 验证”20 到底保不保守”；
采样率模式对照：同一音频在 16 k / 22.05 k / 32 k / 44.1 k 下重算，量化”隐含采样率依赖”能让分数差多少；
抗增益实验：乘 0.05×–10× 增益，区分”占比几乎不变”与”分数漂移 9401”，并定位到”哪套模板用了总能量列”；
聚合方式对照：mean vs max 对长音频判级的影响；
断点调试实操：怎么用最小复现定位”未覆盖分支”，并写一条能长期守护它的回归用例。

音乐

音乐

0. 拆代码的方法：不要从第一行读到第一千行#

1. 目录结构：先分清”主链路 / 工具 / 一次性脚本”#

2. 完整调用链与”数据契约表”#

3. `app.py`：只有 6 步，但每步都有原因#

4. `talk.py`：30 行编排，藏着”标签顺序”这个致命约定#

5. `inference.py`：模型侧管线（参数即契约）#

5.1 默认参数就是”部署契约”#

5.2 Patch Embedding：1212 个 patch 是怎么来的#

5.3 特征与切片：所有常数都必须与训练一致#

5.4 推理与聚合：`sigmoid` 而非 `softmax`#

5.5 装载权重：两行代码，两个坑#

6. `speechprocess.py`：物理侧管线 + 融合规则（全项目最”值钱”的文件）#

6.1 常量区 = 六套模板 + 三套频段#

6.2 `get_energy_pro`：把波形压成 15 个数字#

6.3 `cal_features`：一个”防抖”状态机#

6.4 那个形状 bug：为什么 `(12,) (13,)`#

6.5 `speech_process`：按等级选模板并汇总#

7. 两条音频管线为什么要分开（本篇最重要的认知）#

8. 常量迁移链：从科研脚本 → 线上常量（本项目最漂亮的一条线）#

9. 给核心代码加注释的四个”注释位”#

10. 拆完后应当建立的”认知检查清单”#

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

文章分享

评论区

一起讨论，一起进步

音乐

音乐

2026-09-23 【音色评估】项目拆解（三）：逐行拆解代码

0. 拆代码的方法：不要从第一行读到第一千行#

1. 目录结构：先分清”主链路 / 工具 / 一次性脚本”#

2. 完整调用链与”数据契约表”#

3. app.py：只有 6 步，但每步都有原因#

4. talk.py：30 行编排，藏着”标签顺序”这个致命约定#

5. inference.py：模型侧管线（参数即契约）#

5.1 默认参数就是”部署契约”#

5.2 Patch Embedding：1212 个 patch 是怎么来的#

5.3 特征与切片：所有常数都必须与训练一致#

5.4 推理与聚合：sigmoid 而非 softmax#

5.5 装载权重：两行代码，两个坑#

6. speechprocess.py：物理侧管线 + 融合规则（全项目最”值钱”的文件）#

6.1 常量区 = 六套模板 + 三套频段#

6.2 get_energy_pro：把波形压成 15 个数字#

6.3 cal_features：一个”防抖”状态机#

6.4 那个形状 bug：为什么 (12,) (13,)#

6.5 speech_process：按等级选模板并汇总#

7. 两条音频管线为什么要分开（本篇最重要的认知）#

8. 常量迁移链：从科研脚本 → 线上常量（本项目最漂亮的一条线）#

9. 给核心代码加注释的四个”注释位”#

10. 拆完后应当建立的”认知检查清单”#

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

文章分享

评论区

一起讨论，一起进步

讨论区

3. `app.py`：只有 6 步，但每步都有原因#

4. `talk.py`：30 行编排，藏着”标签顺序”这个致命约定#

5. `inference.py`：模型侧管线（参数即契约）#

5.4 推理与聚合：`sigmoid` 而非 `softmax`#

6. `speechprocess.py`：物理侧管线 + 融合规则（全项目最”值钱”的文件）#

6.2 `get_energy_pro`：把波形压成 15 个数字#

6.3 `cal_features`：一个”防抖”状态机#

6.4 那个形状 bug：为什么 `(12,) (13,)`#

6.5 `speech_process`：按等级选模板并汇总#