coverhunter_handoff.md 9.81 KB

Raw Blame History Permalink



CoverHunter 训练专题交接文档


1. 当前目标与状态

本轮工作目标是把 CoverHunter 微调链路整理为一个可扩展的专题，并完成：


双流结构落地
训练配置整理
4GB GPU 轻量配置
环境安装自动化
CPU 降级路径验证
专题文档沉淀


当前结论：


专题文档已完成
双流训练代码已基本接通
环境依赖已自动安装

GPU 仍不可用（驱动与当前 torch/cu130 不兼容）
CPU 路径已验证到 dry-run 深层阶段，但仍有未完成修复
需要换环境后继续测试


2. 已完成的核心内容


2.1 训练专题与流程文档

已新增/维护：


docs/coverhunter_finetune_topic.md
docs/coverhunter_training_process.md
docs/coverhunter_env_setup.md


说明：


coverhunter_finetune_topic.md：专题总方案，详细描述当前音源、训练计划、阶段目标、权重用途

coverhunter_training_process.md：标准训练流程

coverhunter_env_setup.md：环境安装、验证、阻塞点说明


2.2 双流训练结构

当前已按“双流”方向改造：


流 A：MERT + melody/chroma 分支
流 B：ECAPA 分支
双流融合：DualStreamFusion

检索头：CoverHunterHead

损失：InfoNCE + AAMSoftmax


主要文件：


acr-engine/src/models/ecapa_tdnn.py
acr-engine/src/models/losses.py
acr-engine/src/data/dataset.py
acr-engine/train.py


2.3 数据增强

已在 acr-engine/src/utils/augment.py 中接入专题所需增强：


伪造录音：


AddGaussianNoise
AddBackgroundNoise
BandPassFilter
Mp3Compression


伪造翻唱：


PitchShift
TimeStretch

Frequency Masking（作用于 mel）


并增加了缺少可选依赖时的降级处理，避免直接崩溃。


2.4 训练配置

当前主要配置：


acr-engine/configs/default.yaml
acr-engine/configs/coverhunter_finetune.yaml
acr-engine/configs/coverhunter_finetune_4gb.yaml


其中：


coverhunter_finetune_4gb.yaml 是面向 Quadro P1000 4GB 的轻量配置

acr-engine/scripts/run_coverhunter_finetune.py 默认已切到该配置


2.5 环境自动化

已新增环境安装脚本：


acr-engine/scripts/setup_coverhunter_env.py


已实际执行过：

/usr/local/miniconda3/bin/python acr-engine/scripts/setup_coverhunter_env.py


报告文件：


acr-engine/reports/coverhunter_env_setup_report.json


依赖安装已成功，包括：


torch
torchaudio
transformers
huggingface_hub
librosa
soundfile
audiomentations


3. 当前已有音源与数据资产

当前直接可用于训练和链路验证的数据：


acr-engine/data/synthetic_v2/train.json
acr-engine/data/synthetic_v2/test.json
acr-engine/data/synthetic_v2/segments/*.wav


已统计结果：


样本数：96


song_id：16

类型分布：


reference: 16

clean: 32

augmented: 16

humming_like: 16

confused: 16


结论：


适合做：


训练链路验证
双流结构验证
参数/显存调优
产物结构验证


不适合直接做最终生产权重定版


后续专题仍需补充：


更多 reference / clean 原曲
真实录音与环境噪声样本
更多真实 cover
难负样本
更多 humming_like 语料


4. 环境现状与阻塞点


4.1 Python 解释器

统一使用：

/usr/local/miniconda3/bin/python


4.2 GPU 状态

系统可见 GPU，但当前 PyTorch 不可用：


nvidia-smi 可见设备

torch.cuda.is_available() 返回 False


环境报告中明确告警：


当前驱动版本过旧
与当前安装的 torch 2.12.0+cu130 不兼容


即：


不是代码问题
是 驱动 / CUDA / torch 版本组合问题


4.3 后续环境处理建议

换环境后建议优先处理：


升级 NVIDIA 驱动，或
安装与现有驱动兼容的更低版本 CUDA torch


建议优先目标：


先让 torch.cuda.is_available() 为 True

再继续训练验证


5. CPU 测试进展

用户要求：


支持降级到 CPU
先用 CPU 测完整性


已执行命令：

/usr/local/miniconda3/bin/python /mnt/e/hikoon-ACR/acr-engine/scripts/run_coverhunter_finetune.py \
  --python /usr/local/miniconda3/bin/python \
  --config configs/coverhunter_finetune_4gb.yaml \
  --data data/synthetic_v2 \
  --device cpu \
  --segment-strategy hybrid \
  --dry-run


5.1 已修复的问题


问题 1：librosa.hz_to_midi 参数错误

报错：


hz_to_midi() got an unexpected keyword argument 'bins_per_octave'


已修复：


文件：acr-engine/src/data/dataset.py

去掉了不兼容参数


问题 2：audiomentations 可选依赖引发噪声提示/潜在中断

已处理：


文件：acr-engine/src/utils/augment.py

增加导入保护与降级逻辑
缺少可选增强时不应直接崩溃


5.2 CPU dry-run 当前推进到哪里

最新一次 CPU dry-run 已经推进到：


成功读取数据
成功构建 batch
成功进入模型 forward 前阶段
控制台输出：


Device: cpu
Dry batch shape: torch.Size([6, 96, 501]) torch.Size([6])
Classes: 16
Train songs: 64
Dry run: running one batch through forward/backward...


说明：


数据加载链路已经基本通了
collate 基本通了
配置能读
训练入口能走到 forward/backward 前后深层位置


5.3 CPU dry-run 仍未完成的阻塞

最新可见报错来自：


acr-engine/src/models/ecapa_tdnn.py
FrozenMERTFeatureExtractor


报错现象（上一轮日志中）：


网络不可达，HuggingFace MERT 拉取失败
fallback 逻辑仍存在未完全闭合情况
具体表现为：


TypeError: 'NoneType' object is not callable


我已经做过一次修正：


在 FrozenMERTFeatureExtractor 中先初始化本地 fallback proj

如果 AutoModel.from_pretrained(model_name) 失败，就回退到本地 frozen projection 路径


但是最后一次工具调用被中断，没有拿到新的完整 stderr 日志来最终确认这一修复是否完全生效。

因此当前状态应认定为：


CPU fallback 已显著推进
但尚未拿到一次完全成功的 dry-run 结果
下一环境中需要先继续补跑一次 CPU dry-run


6. 已生成的重要运行痕迹


6.1 环境安装报告


acr-engine/reports/coverhunter_env_setup_report.json


6.2 CPU dry-run 目录

已知 CPU 相关运行目录：


/mnt/e/hikoon-ACR/data/training_runs/coverhunter_finetune_20260608T130103Z/
/mnt/e/hikoon-ACR/data/training_runs/coverhunter_finetune_20260608T130306Z/
/mnt/e/hikoon-ACR/data/training_runs/coverhunter_finetune_20260608T130514Z/


里面可参考：


stdout.log
stderr.log
run_request.json
run_summary.json


说明：


注意这些目录是在 /mnt/e/hikoon-ACR/data/training_runs/，不是 acr-engine/data/training_runs/

这是因为运行时是从仓库根触发脚本，输出路径使用了相对路径


7. 下次换环境后的建议恢复步骤

建议按这个顺序继续：


Step 1：先验证 Python 环境

/usr/local/miniconda3/bin/python --version
/usr/local/miniconda3/bin/python -m pip show torch transformers librosa soundfile audiomentations


Step 2：验证 CUDA 是否正常

/usr/local/miniconda3/bin/python - <<'PY'
import torch
print(torch.__version__)
print(torch.cuda.is_available())
if torch.cuda.is_available():
    print(torch.cuda.device_count())
    for i in range(torch.cuda.device_count()):
        print(i, torch.cuda.get_device_name(i))
PY


Step 3：先补跑 CPU dry-run，确认完整性

cd /mnt/e/hikoon-ACR/acr-engine && \
/usr/local/miniconda3/bin/python scripts/run_coverhunter_finetune.py \
  --python /usr/local/miniconda3/bin/python \
  --config configs/coverhunter_finetune_4gb.yaml \
  --data data/synthetic_v2 \
  --device cpu \
  --segment-strategy hybrid \
  --dry-run


如果仍失败，优先检查：


acr-engine/src/models/ecapa_tdnn.py
FrozenMERTFeatureExtractor
MERT 下载失败时的 fallback 是否还存在空路径


Step 4：CPU 通了之后，再跑 GPU dry-run

cd /mnt/e/hikoon-ACR/acr-engine && \
/usr/local/miniconda3/bin/python scripts/run_coverhunter_finetune.py \
  --python /usr/local/miniconda3/bin/python \
  --config configs/coverhunter_finetune_4gb.yaml \
  --data data/synthetic_v2 \
  --device cuda \
  --segment-strategy hybrid \
  --dry-run


Step 5：再做小规模试训

cd /mnt/e/hikoon-ACR/acr-engine && \
/usr/local/miniconda3/bin/python train.py \
  --config configs/coverhunter_finetune_4gb.yaml \
  --data data/synthetic_v2 \
  --output data/training_runs/coverhunter_4gb_trial \
  --device cuda \
  --segment-strategy hybrid \
  --batch-size 2 \
  --epochs 2


8. 重点文件清单


模型与训练


acr-engine/src/models/ecapa_tdnn.py
acr-engine/src/models/losses.py
acr-engine/src/data/dataset.py
acr-engine/src/utils/augment.py
acr-engine/train.py
acr-engine/scripts/run_coverhunter_finetune.py


环境


acr-engine/scripts/setup_coverhunter_env.py
acr-engine/reports/coverhunter_env_setup_report.json


配置


acr-engine/configs/default.yaml
acr-engine/configs/coverhunter_finetune.yaml
acr-engine/configs/coverhunter_finetune_4gb.yaml


文档


docs/coverhunter_finetune_topic.md
docs/coverhunter_training_process.md
docs/coverhunter_env_setup.md
docs/coverhunter_handoff.md


9. 一句话交接结论

当前专题已经完成了结构、配置、环境自动化和文档沉淀，但由于 GPU 驱动与 torch CUDA 不兼容、以及 CPU fallback 尚未拿到最终成功 dry-run，所以本轮最佳交接点是：


保留当前代码与文档成果
换环境后先继续补跑 CPU dry-run
再恢复 GPU 验证与正式试训