handoff for next session in GPU/CPU inter

@@ -18,3 +18,4 @@ acr-engine/configs/manifests/examples/business_asset_export_real_smoke.csv
 acr-engine/__pycache__/
 acr-engine/**/__pycache__/
 acr-engine/**/*.pyc
+best_model.pt

+# 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`
+
+已实际执行过：
+
+```bash
+/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 解释器
+
+统一使用：
+
+```bash
+/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 后续环境处理建议
+
+换环境后建议优先处理：
+
+1. 升级 NVIDIA 驱动，或
+2. 安装与现有驱动兼容的更低版本 CUDA torch
+
+建议优先目标：
+
+- 先让 `torch.cuda.is_available()` 为 `True`
+- 再继续训练验证
+
+---
+
+## 5. CPU 测试进展
+
+用户要求：
+
+- 支持降级到 CPU
+- 先用 CPU 测完整性
+
+已执行命令：
+
+```bash
+/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 环境
+
+```bash
+/usr/local/miniconda3/bin/python --version
+/usr/local/miniconda3/bin/python -m pip show torch transformers librosa soundfile audiomentations
+```
+
+### Step 2：验证 CUDA 是否正常
+
+```bash
+/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，确认完整性
+
+```bash
+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
+
+```bash
+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：再做小规模试训
+
+```bash
+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 验证与正式试训**