2026-09-22 【音色评估】项目拆解（二）：环境搭建与跑通

0. 先把”跑通”定义清楚#

新手最大的误区是：窗口没报错 = 跑通了。这不成立。本文用的判据是三条，缺一不可：

附带一条经验：“能跑”和”能信”是两件事。第 ② 条只证明链路通了；第 ③ 条才说明你没把张量形状、采样率、标签顺序之类搞错。这就是为什么后面要用”对拍”再验一遍。

1. 摸清”到底要装什么”（不要照着 requirements 盲装）#

项目 requirements.txt 写的是声明，而实际运行取决于 import 链。做法：把代码里所有 import 抓出来。

1
# 在解压后的 html/ 目录里
2
grep -rhoE "^\s*(import|from) [A-Za-z_][A-Za-z0-9_.]*" --include=*.py . \
3
  | sed 's/^\s*//' | sort -u

这一步在本项目里抓到两个”requirements 里看不出”的关键点：

顺手做的第二件事：确认哪些依赖是”训练用”、哪些是”跑推理用”。本项目里 TimbreMask/（训练框架）与 frenquence_check/（科研脚本）都不参与 Web 运行，装环境时不要被它们的 requirements 带跑偏。

2. 建一个干净环境（不要动系统 Python）#

本机的现实：系统 Python 3.10 存在，但 pip 模块是坏的（python -m pip 报 No module named 'pip'，pip.exe 也起不来），且没有 conda / uv。所以第一个坑就是”连包管理器都没有”。

1
# 用系统 Python 造一个自带 pip 的虚拟环境（venv 会自带 ensurepip）
2
python -m venv .venv_html
3
.\.venv_html\Scripts\python.exe -m pip --version     # pip 22.0.4 ✓
4

5
# Linux/macOS
6
python3 -m venv venv && ./venv/bin/python -m pip --version

三条硬经验：

1. 虚拟环境放在项目目录内（.venv_html/）。好处：路径可预测、便于写启动脚本、删库跑路只删一个文件夹；本项目用它同时服务 html/（评估网站）和 physics_lab/（实验台）。
2. 别用系统 Python 装依赖：一旦装坏，全机项目一起坏，而且没法回滚。
3. 环境装完先跑一次 import 自检，别等到启动服务才发现少包：

1
python -c "import torch, torchaudio, librosa, soundfile, flask, timm, sklearn, numpy, scipy; print('imports OK')"

3. 装依赖：分三批，别一把梭#

按”编译依赖强度 / 下载渠道”分批，出问题好定位：

1
# 第 1 批：深度学习核心（必须走官方 CPU 索引，见 4.2）
2
pip install torch torchaudio torchvision --index-url https://download.pytorch.org/whl/cpu
3

4
# 第 2 批：音频与科学计算
5
pip install librosa soundfile numpy scipy scikit-learn numba
6

7
# 第 3 批：Web 与工具
8
pip install flask python-dotenv

本项目最终验证可用的版本组合（建议直接固化）：

4. 网络与镜像：这一步决定你是 10 分钟还是 3 小时#

1
# save as dl_wheels.py ；用法：python dl_wheels.py <index-url> <包名...>
2
import os, re, sys, time, zipfile, urllib.request
3

4
def pick(base, pkg):
5
    """从 simple 索引里挑一个匹配当前平台的 wheel（优先 cp310 win_amd64，其次 py3-none-any）"""
6
    html = urllib.request.urlopen(f'{base}/simple/{pkg}/', timeout=30).read().decode('utf-8', 'ignore')
7
    hrefs = [m.group(1).split('#')[0] for m in re.finditer(r'href="([^"]*\.whl[^"]*)"', html)]
8
    best, score = None, -1
9
    for h in hrefs:
10
        fn = h.split('/')[-1]
11
        s = 3 if 'cp310-cp310-win_amd64' in fn else (2 if 'none-any' in fn else 0)
12
        if s > score:
13
            score, best = s, h
14
    return best
15

16
def download(url, dest, chunk=4 << 20, tries=8):
17
    """按 4MB 分块下载：每块单独一个请求，断了只重试这一块"""
18
    def total():
19
        req = urllib.request.Request(url, headers={'Range': 'bytes=0-0'})
20
        with urllib.request.urlopen(req, timeout=40) as r:
21
            return int(r.headers['Content-Range'].split('/')[1])
22
    n = total(); have = os.path.getsize(dest) if os.path.exists(dest) else 0
23
    with open(dest, 'ab') as f:
24
        while have < n:
25
            end = min(have + chunk - 1, n - 1)
26
            for _ in range(tries):
27
                try:
28
                    req = urllib.request.Request(url, headers={'Range': f'bytes={have}-{end}'})
29
                    with urllib.request.urlopen(req, timeout=120) as r:
30
                        data = r.read()
31
                    f.write(data); f.flush(); have += len(data); break
32
                except Exception:
33
                    time.sleep(1.5)
34
            else:
35
                raise IOError('stuck at %d' % have)
36
    return n
37

38
if __name__ == '__main__':
39
    base, pkgs = sys.argv[1], sys.argv[2:]
40
    os.makedirs('wheels', exist_ok=True)
41
    for pkg in pkgs:
42
        h = pick(base, pkg); fn = h.split('/')[-1]
43
        url = base + '/' + h.lstrip('./').replace('../', '')
44
        dest = os.path.join('wheels', fn)
45
        print(pkg, '->', fn, download(url, dest), 'bytes')

1
import glob, os, zipfile
2
SP = r'.venv_html\Lib\site-packages'      # Linux: .venv/lib/python3.x/site-packages
3
for wh in sorted(glob.glob('wheels/*.whl')):
4
    if os.path.basename(wh).startswith(('torch-', 'torchaudio-')):   # 已装的可跳过
5
        continue
6
    zipfile.ZipFile(wh).extractall(SP)
7
    print('installed', os.path.basename(wh))

5. 版本地雷清单（全部是本项目真实踩过的）#

按”现象 → 根因 → 解决”给表，遇到直接查：

第 6 项的”垫片”方案：当 torchvision 的原生扩展与 torch CPU 构建对不上、而项目运行时并不真的调用 torchvision（只是 timm 顶层 import 需要它）时，可以放一个最小占位模块，把 import 链喂饱即可：

1
__version__ = '0.0.0-shim'
2
# ops/misc.py 里提供 timm 需要的符号
3
class FrozenBatchNorm2d:  # timm.layers.create_norm 只在本项目不走的路径上引用它
4
    def __init__(self, num_features, eps=1e-5): ...
5
# datasets/__init__.py 里给 timm.data.dataset_factory 需要的桩类
6
CIFAR10 = CIFAR100 = MNIST = KMNIST = FashionMNIST = ImageFolder = object
7
# transforms/functional.py 里提供 InterpolationMode 枚举

这不是”最佳实践”，而是”在受限环境下让 import 链通起来的止血方案”；能装配套 torchvision 时优先装配套。关键是：要清楚自己在绕什么，并在文档里写清楚。

6. 数据与资源准备（跑通前必须核对的两件事）#

1
stat -c%s html/model/checkpoint-300.pth      # Linux
2
(Get-Item html\model\checkpoint-300.pth).Length   # Windows
3
# 期望：1024918304

1
import numpy as np, soundfile as sf
2
sr, dur = 16000, 12
3
t = np.arange(sr * dur) / sr
4
seg = (t // 2 % 3) + 0.5                     # 每 2 秒换一个基频
5
f0 = 110 * seg * (1 + 0.03 * np.sin(2 * np.pi * 5 * t))
6
y = sum((1.0 / h) * np.sin(2 * np.pi * f0 * h * t + 0.5 * h) for h in range(1, 7))
7
y = 0.35 * y + 0.06 * np.random.default_rng(42).normal(size=len(t))
8
sf.write('test_input.wav', np.clip(y, -1, 1).astype('float32'), sr, subtype='PCM_16')

7. 首次运行：“跑通三判据”逐条验#

1
cd html
2
..\.venv_html\Scripts\python.exe app.py       # 或 python app.py
3
# 控制台出现：Running on http://127.0.0.1:5001

1
# 判据 ① 首页
2
curl -s -o /dev/null -w "首页 HTTP %{http_code}\n" http://127.0.0.1:5001/
3
# → 首页 HTTP 200
4

5
# 判据 ②③ 核心接口（multipart 传音频）
6
curl -s -X POST http://127.0.0.1:5001/api/evaluate -F "audio=@../test_input.wav" | head -c 400

本项目实测返回（片段）：

1
{"scores": {"thickness": 3, "solidity": 3, "brightness": 3},
2
 "scores_change": {"thickness": 0, "solidity": 0, "brightness": 0},
3
 "weights_scores": {"thickness": 80.29, "solidity": 541.92, "brightness": 9400.03},
4
 "thick_features": [ ... 12 维 ... ]}

首请求耗时：模型加载 + 第一次推理约 9.7 秒（CPU），之后的请求快得多。把这个数字记下来 —— 它是你判断”环境是否正常”的基准线。

顺手记两条”跑通即暴露”的问题，它们在这一步才会出现（第三篇会详细拆）：

1. 浏览器录音上传必 500：MediaRecorder 录出的是 WebM/Opus，而 librosa/libsndfile 不认这个容器 → 需要在前端转成 WAV再上传；
2. 物理链路在某个分支崩：模型判 C 级且物理分偏高时会进”C→B 跨级”分支，两组权重与特征长度不匹配 → ValueError: operands could not be broadcast together with shapes (12,) (13,)。

这正是”跑通”的边界：能跑 ≠ 所有分支都跑得通。第三篇拆代码、第四篇做调试，都是在补这个差。

8. 环境固化：让”下次还能量出来”#

1
pip freeze > requirements.lock.txt

1
@echo off
2
chcp 65001 >nul
3
cd /d "%~dp0"
4
set "PY=%~dp0..\.venv_html\Scripts\python.exe"
5
set PYTHONUTF8=1
6
if not exist "%PY%" (
7
  echo [ERROR] venv python not found: "%PY%"
8
  pause
9
  exit /b 1
10
)
11
echo Open in browser: http://127.0.0.1:5001
12
"%PY%" app.py
13
pause >nul

9. 本篇产出物（可直接复用的东西）#

• ✅ 一个 100% 可运行版本：html/ + .venv_html/（已验证版本组合）
• ✅ 环境搭建手册：第 3、5 节（分三批安装 + 15 条地雷清单）
• ✅ 离线安装资产：wheels/ 目录（全部依赖 wheel，断网也能装）
• ✅ 可复用下载器：dl_wheels.py（分块 + 断点续传）
• ✅ 测试资产：test_input.wav（确定性合成音频）
• ✅ 启动器：启动音色评估网站.bat / 启动物理链路实验台.bat（纯 ASCII + 绝对路径 + UTF-8 控制台）
• ✅ 自检与异常清单脚本：selftest.py / diag_bad_inputs.py

10. 报错速查（按症状索引）#

11. 本篇收尾与下一篇预告#

收尾目标达成：项目从”压缩包”变成了「有环境、有版本锁定、有一键启动、有自检脚本、有验证记录」的可运行版本；同时明确了”跑通”的边界 —— 接口通了，但某些分支还没被覆盖（浏览器录音、跨级修正）。

**下一篇（第三篇：逐行拆解代码）**会顺着本篇留下的两个”未覆盖分支”往下挖：

1. 从 app.py → talk.py → inference.py → speechprocess.py 的完整调用链，每段的入参/出参/形状变化；
2. 两条”同一项目里并存”的音频管线（推理侧 fbank vs 物理侧 STFT 频段占比）为什么要分开；
3. 物理链路的六套模板与 bands_change 常量，到底是从哪几个科研脚本”抄”过来的；
4. 给核心文件加中文注释的方法：“把别人的代码变成自己能讲出来的代码”。