Changelog

2026-06-02

Stage: 文档浓缩与相对链接跳转

完成项：

• 重构 docs/README.md 为 4 组主文档入口
• 将多处相对路径从反引号文本改为 Markdown 可点击链接
• 收拢“数据接入”阅读入口，降低文档数量感知
• 修正文档内对脚本、manifest、关联文档的跳转方式

验证结果：

• 入口文档现在按：
  • 项目与架构
  • 数据与评测
  • 服务与工程
  • 研究与路线 进行分组
• dataset-spec.md / dataset-sources-and-licensing.md / industrialization-roadmap.md / service-api.md / industrial-benchmark-spec.md 已使用相对链接替代部分反引号路径

结论：

• 文档入口已明显浓缩
• 读者不再需要先面对大量平铺文件名
• 相对路径现在更适合直接跳转

Stage: 开放数据单页工作流

完成项：

• 新增 docs/open-dataset-workflow.md
• 把开放数据接入流程浓缩为：
  • inspect-local / inspect-batch
  • prepare-local
  • validate-local
• 将该工作流挂到 docs/README.md 的“数据与评测”组下

验证结果：

• /usr/local/miniconda3/bin/python src/data/external_adapters.py inspect-local fma data/synthetic_v2/songs --eval-ratio 0.2 --query-duration 5.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/synthetic_v2/songs --output-root data/external_ingested/synthetic_as_open --eval-ratio 0.2 --query-duration 5.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/synthetic_as_open/fma/manifests 成功
• 当前结果：
  • num_audio_files=24
  • catalog=24
  • train_queries=16
  • test_queries=8
  • ok=true

结论：

• 现在开放数据接入路径已经浓缩成单页可执行工作流
• 后续接真实 FMA / MTG-Jamendo 本地目录时，上手成本更低

Stage: 开放数据 manifests 直连训练

完成项：

• 修复 src/data/manifest_tools.py 生成的开放数据 manifests 路径自洽性
• 让开放数据音频复制到输出根下的 audio/
• 修复 src/data/dataset.py 对 .../manifests 目录布局的路径解析
• 打通 prepare-local -> validate-local -> train.py --dry-run

验证结果：

• /usr/local/miniconda3/bin/python src/data/external_adapters.py prepare-local fma data/synthetic_v2/songs --output-root data/external_ingested/synthetic_as_open_fixed --eval-ratio 0.2 --query-duration 5.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py validate-local fma data/external_ingested/synthetic_as_open_fixed/fma/manifests 成功
• /usr/local/miniconda3/bin/python train.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --output data/models_open_smoke_fixed --device cpu --epochs 1 --batch-size 2 --dry-run 成功
• 当前结果：
  • catalog=24
  • train_queries=16
  • test_queries=8
  • Dry run passed!

结论：

• 开放数据路径现在不仅能生成 manifests，还能真正进入训练
• 后续接入真实 FMA / MTG-Jamendo 时，可以直接走同一链路

Stage: 开放数据完整 smoke 闭环（train/index/eval）

完成项：

• 修复 run_demo.py 对开放数据自包含布局的索引入口假设
• 修复 src/engines/ecapa_embedder.py / src/engines/chromaprint_matcher.py 对 reference 路径的硬编码筛选
• 修复 evaluate.py 对开放数据 query 与 manifests 根路径的解析
• 打通开放数据 prepare-local -> validate-local -> train -> build-index -> evaluate

验证结果：

• /usr/local/miniconda3/bin/python train.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --output data/models_open_smoke_fixed --device cpu --epochs 1 --batch-size 2 成功
• /usr/local/miniconda3/bin/python run_demo.py build-index --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --model data/models_open_smoke_fixed/best_model.pt --output data/index_open_smoke_fixed --device cpu 成功
• /usr/local/miniconda3/bin/python evaluate.py --data data/external_ingested/synthetic_as_open_fixed/fma/manifests --model data/models_open_smoke_fixed/best_model.pt --index-prefix data/index_open_smoke_fixed/reference --split test --device cpu --fast-eval --output-json reports/open-smoke-fixed/fma/eval.json 成功
• 当前结果：
  • num_queries=8
  • top1=1.0
  • topk=1.0

结论：

• 开放数据接入链路现在已经完整闭环
• 真实 FMA / MTG-Jamendo 本地目录接入时，可直接复用同一流程

Stage: 开放数据 smoke 发布制品

完成项：

• 为 reports/open-smoke-fixed/fma/ 补充 config.json
• 用 scripts/generate_artifacts.py 生成开放数据 smoke 的：
  • benchmark report
  • model card
  • release checklist
  • artifact manifest

验证结果：

• /usr/local/miniconda3/bin/python scripts/generate_artifacts.py --eval-json reports/open-smoke-fixed/fma/eval.json --config-json reports/open-smoke-fixed/fma/config.json --output-dir reports/open-smoke-fixed/fma --model-version open-smoke-fixed --data-version synthetic_as_open_fixed_fma 成功
• 产物存在：
  • reports/open-smoke-fixed/fma/benchmark-report.md
  • reports/open-smoke-fixed/fma/model-card.md
  • reports/open-smoke-fixed/fma/release-checklist.md
  • reports/open-smoke-fixed/fma/artifact-manifest.json

结论：

• 现在开放数据链路已经不只是“能跑”，还具备基础发布/汇报产物
• 下一步替换成真实 FMA / MTG-Jamendo 本地目录后，可直接复用同一 release 流程

Stage: 一键 open-dataset smoke

完成项：

• 扩展 src/data/external_adapters.py
• 新增 smoke-local
• 一条命令自动执行：
  • inspect-local
  • prepare-local
  • validate-local
  • train
  • build-index
  • evaluate
  • generate_artifacts

验证结果：

• /usr/local/miniconda3/bin/python src/data/external_adapters.py smoke-local fma data/synthetic_v2/songs --output-root data/external_smoke --eval-ratio 0.2 --query-duration 5.0 --train-epochs 1 --batch-size 2 成功
• 当前结果：
  • num_audio_files=24
  • catalog=24
  • train_queries=16
  • test_queries=8
  • top1=1.0
  • topk=1.0
  • 产物目录：data/external_smoke/fma_reports_smoke

结论：

• 现在只要替换 input_dir，就能对真实 FMA / MTG-Jamendo 本地目录跑完整 smoke
• 这显著降低了真实开放数据集接入和验证成本

Stage: 真实开放数据落点目录模板

完成项：

• 新增 acr-engine/data/raw/README.md
• 新建本地开放数据落点目录：
  • acr-engine/data/raw/fma_small_audio/
  • acr-engine/data/raw/mtg_jamendo_audio/
• 将这些目录入口链接接入开放数据工作流与 docs 总入口

验证结果：

• 本地目录已创建：
  • data/raw/
  • data/raw/fma_small_audio/
  • data/raw/mtg_jamendo_audio/
• data/raw/README.md 已包含可直接执行的下一条 smoke 命令模板

结论：

• 现在真实开放数据只需要放进明确目录即可
• 后续替换真实 FMA / MTG-Jamendo 本地音频时无需再猜目录结构

Stage: 新 session 首次启动清单

完成项：

• 新增 acr-engine/FIRST_RUN_CHECKLIST.md
• 把最常用启动检查命令与读文档顺序固化到 repo
• 将 checklist 接入 docs/README.md 与 docs/session-handoff.md

验证结果：

• FIRST_RUN_CHECKLIST.md 已创建
• docs 入口已挂接 checklist

结论：

• 新 session 现在可以更快进入有效开发状态
• 启动成本和漏看关键文档/命令的风险进一步下降

Stage: 状态快照脚本

完成项：

• 新增 acr-engine/scripts/status_snapshot.py
• 统一输出：
  • latest commit
  • 核心 docs 路径
  • 真实数据 drop zones
  • 已验证 smoke 目录
  • 下一步推荐命令
• 将脚本接入 handoff 文档与 first-run checklist

验证结果：

• /usr/local/miniconda3/bin/python scripts/status_snapshot.py 成功
• 输出已正确指向：
  • /workspace/docs/README.md
  • /workspace/docs/session-handoff.md
  • /workspace/docs/open-dataset-workflow.md

结论：

• 新 session 现在不只靠静态文档，也可以直接读取当前仓库状态快照
• 持续开发交接更稳

Stage: 状态快照落盘

完成项：

• 扩展 acr-engine/scripts/status_snapshot.py
• 新增 --output
• 可直接写入 .omx/latest_status_snapshot.json

验证结果：

• /usr/local/miniconda3/bin/python scripts/status_snapshot.py --output .omx/latest_status_snapshot.json 成功
• 已验证：
  • 文件存在
  • JSON 可解析
  • 包含 latest_commit
  • 包含 next_commands

结论：

• 新 session 现在可以直接读取最近一次状态快照文件
• 交接信息更适合自动化和长期持续开发

Stage: FMA 下载器模块调用修复

完成项：

• 修复 acr-engine/scripts/fetch_fma_subset.py 的 yt-dlp 检测方式
• 从 shell 可执行查找改为优先支持：
  • yt-dlp 可执行文件
  • /usr/local/miniconda3/bin/python -m yt_dlp 模块调用
• 重新执行真实 FMA bounded 下载验证

验证结果：

• which yt-dlp 仍为空
• /usr/local/miniconda3/bin/python -m yt_dlp --version 成功，版本 2026.03.17
• /usr/local/miniconda3/bin/python scripts/fetch_fma_subset.py --report reports/fma_fetch_subset_report.json 成功执行
• 当前结果：
  • ytdlp_cmd=["/usr/local/miniconda3/bin/python", "-m", "yt_dlp"]
  • 8/8 请求均失败
  • 失败原因已从“工具缺失”收敛为 freemusicarchive.org/music/track/<id> 返回 HTTP 404

结论：

• 下载脚本的模块调用问题已经修复
• 当前真实阻塞不再是本地环境，而是 FMA 历史页面 URL 路径已不可用
• 下一步应转向官方整包或稳定镜像，而不是继续重试旧页面 URL

Stage: FMA 真实下载脚手架

完成项：

• 新增 acr-engine/scripts/fetch_fma_subset.py
• 先验证了旧版 FMA 文件直链抓取路径
• 再切换为页面级抓取脚手架，并显式输出阻塞原因
• 将当前真实 FMA 下载状态记录进：
  • docs/open-dataset-workflow.md
  • docs/session-handoff.md

验证结果：

• /usr/local/miniconda3/bin/python scripts/fetch_fma_subset.py --report reports/fma_fetch_subset_report.json 已执行两轮验证
• 第一轮结果：8 个 track id 全部 HTTP 403
• 第二轮结果：yt-dlp not found，脚本返回结构化 blocked JSON

结论：

• 真实 FMA 下载自动化入口已具备
• 但当前环境下仍缺稳定可用下载通道，尚不能宣称真实 FMA 已成功落地
• 该阻塞已经被显式固化到交接文档中，避免新 session 重复踩坑

Stage: 原始开放数据 LFS 治理

完成项：

• 新增根目录 /.gitattributes
• 为 acr-engine/data/raw/ 下的大文件与音频配置 Git LFS 跟踪策略
• 重写 acr-engine/data/raw/README.md，补充：
  • 数据落点职责表
  • check-local-ready -> smoke-local 最短路径
  • 原始数据下载 / LFS 治理策略
• 补充 docs/dataset-sources-and-licensing.md 的下载 / LFS 治理说明

验证结果：

• git lfs version 成功
• git check-attr filter -- acr-engine/data/raw/fma_small_audio/example.wav 返回 filter: lfs
• git check-attr filter -- acr-engine/data/raw/archive.zip 返回 filter: lfs
• 文档已明确区分：
  • 工程可用性
  • benchmark 适用性
  • 商用可部署性

结论：

• 仓库现在具备承接真实开放音频和压缩包的 LFS 基础设施
• 后续下载真实数据时，不会直接把大文件塞进普通 git 历史

Stage: 真实数据就绪度守门

完成项：

• 为 acr-engine/src/data/external_adapters.py 新增 check-local-ready
• 为 smoke-local 增加前置就绪度守门，避免对空目录直接进入训练链路
• 增强 acr-engine/scripts/status_snapshot.py，输出：
  • dataset_readiness
  • capability_map 文档入口
  • check-local-ready 下一步命令
• 补充 docs/open-dataset-workflow.md 与 docs/session-handoff.md 的真实数据检查说明

验证结果：

• /usr/local/miniconda3/bin/python -m py_compile src/data/external_adapters.py scripts/status_snapshot.py 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready fma data/raw/fma_small_audio --eval-ratio 0.2 --query-duration 8.0 成功
• /usr/local/miniconda3/bin/python src/data/external_adapters.py check-local-ready mtg_jamendo data/raw/mtg_jamendo_audio --eval-ratio 0.2 --query-duration 8.0 成功
• /usr/local/miniconda3/bin/python scripts/status_snapshot.py --output .omx/latest_status_snapshot.json 成功
• 当前结果：
  • fma.ready_for_smoke=false
  • mtg_jamendo.ready_for_smoke=false
  • 原因均为音频文件数与可切 query 文件数不足

结论：

• 真实开放数据现在有了明确的“进入 smoke 前门槛”
• 新 session 和自动化脚本可以立刻识别空目录，而不是误以为真实数据已经准备完成

Stage: 当前能力地图

完成项：

• 新增 docs/current-capability-map.md
• 明确区分：
  • 已完整闭环
  • 已打通但仍是 smoke 级
  • 仍待真实数据/更大规模验证
• 将能力地图接入 docs 总入口与交接文档

验证结果：

• docs/current-capability-map.md 已创建
• docs/README.md 已挂接
• docs/session-handoff.md 已挂接

结论：

• 新 session 现在更容易快速判断“什么是真的完成了，什么还只是 smoke 级能力”
• 能显著减少误判项目状态的风险

Stage: confused 定向优化 v6（sample-level weighting）

完成项：

• 将 hard-case loss 从 batch 级平均权重改为 sample-level weighting
• SongPairDataset 改为对 confused / humming_like 区分采样强度
• confused 样本权重提高到更高优先级
• 重训 models_v6、重建 index_v6、重跑 smoke-v6 评测
• 生成 reports/smoke-v6/synthetic_v2/ 发布制品
• 补充 docs/dataset-spec.md 中的 hard-case 输入规范说明
• 补充 docs/sota-research-2026.md 中的 v4/v5/v6 对比结论

验证结果：

• train.py --dry-run 成功
• py_compile 成功
• run_demo.py build-index 成功
• evaluate.py --fast-eval --output-json reports/smoke-v6/synthetic_v2/eval.json 成功
• 当前结果：
  • overall top1=0.65, top5=0.95
  • humming_like top1=0.25
  • confused top1=0.25

结论：

• 相比 smoke-v5，overall top1 从 0.60 提升到 0.65
• confused top1 从 0.00 提升到 0.25，说明 sample-level 权重有效
• humming_like top1 从 0.50 回落到 0.25，说明两类 hard case 需要分治，而不能只靠单轴加权

Stage: v7 平衡采样试验（未保留）

完成项：

• 尝试降低 confused 偏置并提高 humming_like 采样强度
• 重跑 smoke-v7 全链路验证
• 基于失败样本回查 residual hard case 的 segment 分布

验证结果：

• smoke-v7 结果退化为：
  • overall top1=0.55, top5=0.80
  • humming_like top1=0.00
  • confused top1=0.00
• 因结果明显回退，已回滚该试验，不作为主线版本保留

结论：

• 单纯重调全局采样比率不稳定
• 当前最优保留点仍是 smoke-v6
• residual confused failure 主要落在 intro 片段，下一轮应改做 segment_type-aware hard negatives

Stage: 检索融合权重参数化 + fast-eval 调优

完成项：

• evaluate.py 新增融合参数：
  • --chroma-weight
  • --ecapa-weight
  • --melody-weight
• 在稳定的 models_v6 + index_v6 资产上做 fresh fast-eval 对比
• 验证 retrieval-time fusion 调优是否比继续改训练权重更有效

验证结果：

• 默认 fast-eval：
  • overall top1=0.65
  • humming_like top1=0.25
  • confused top1=0.25
• 调整为 chroma=0.2 / ecapa=0.55 / melody=0.25 后：
  • overall top1=0.70
  • humming_like top1=0.50
  • confused top1=0.25

结论：

• 在当前阶段，检索融合调优 比继续调训练侧权重更稳定、更划算
• ecapa 权重略升、chroma 略降能恢复 humming_like，同时保持 confused
• 下一阶段应继续把外部开源数据集真正接成 train/eval manifests，而不是只停在 bootstrap

Stage: 开源数据集 ingestion（train/eval manifests）

完成项：

• 扩展 src/data/manifest_tools.py
• 新增 audio-dir-to-splits CLI
• 支持从本地开放音频目录自动生成：
  • catalog.json
  • train.json
  • test.json
  • val.json
• 新增小数据集保护，确保个人使用场景下也能同时有 train/test queries

验证结果：

• python -m py_compile src/data/manifest_tools.py 成功
• 使用本地 demo 音频目录成功生成真实 manifests
• 修正后小样本结果：
  • catalog=2
  • train_queries=1
  • test_queries=1

结论：

• 项目现在不再只停留在 external bootstrap
• 已经具备把开源音乐数据目录直接切成训练/评估输入的能力
• 下一阶段可以继续对接真实 FMA / MTG-Jamendo 下载目录

Stage: adapter-level 本地开源目录接入

完成项：

• 扩展 src/data/external_adapters.py
• 新增 prepare-local 命令
• 支持通过 adapter 入口直接把本地开源音频目录转成：
  • catalog.json
  • train.json
  • test.json
  • val.json

验证结果：

• python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py 成功
• python src/data/external_adapters.py prepare-local fma tmp/open_music_demo --output-root data/external_ingested/demo_via_adapter --eval-ratio 0.5 --query-duration 5.0 成功
• 输出结果：
  • catalog=2
  • train_queries=1
  • test_queries=1

结论：

• 现在接入真实 FMA / MTG-Jamendo 目录时，不需要再手动拼 manifests
• adapter 已经能作为统一入口管理开放数据集的训练/评估切分

Stage: 开源目录规模扫描（inspect-local）

完成项：

• 扩展 src/data/manifest_tools.py
• 新增 inspect-audio-dir
• 扩展 src/data/external_adapters.py
• 新增 inspect-local
• 在真正生成 manifests 之前，可以先报告：
  • 音频文件数量
  • 可切 query 的文件数
  • 推荐 train/test query 数
  • 基础时长统计

验证结果：

• python -m py_compile src/data/manifest_tools.py src/data/external_adapters.py 成功
• python src/data/manifest_tools.py inspect-audio-dir tmp/open_music_demo --query-duration 5.0 --eval-ratio 0.5 成功
• python src/data/external_adapters.py inspect-local fma tmp/open_music_demo --eval-ratio 0.5 --query-duration 5.0 成功
• 返回结果：
  • num_audio_files=2
  • eligible_query_files=2
  • recommended_train_queries=1
  • recommended_test_queries=1

结论：

• 现在真实 FMA / MTG-Jamendo 目录在导入前就能先做规模预估
• 这对个人使用下的快速数据准备非常有帮助

Stage: 多目录批量 inventory（inspect-batch）

完成项：

• 扩展 src/data/external_adapters.py
• 新增 inspect-batch
• 支持一次性检查多个开放数据目录，例如：
  • fma=<dir>
  • mtg_jamendo=<dir>

验证结果：

• python -m py_compile src/data/external_adapters.py src/data/manifest_tools.py 成功
• python src/data/external_adapters.py inspect-batch fma=tmp/open_music_demo_fma mtg_jamendo=tmp/open_music_demo_jamendo --eval-ratio 0.5 --query-duration 5.0 成功
• 返回：
  • count=2
  • 每个数据源均给出 num_audio_files / eligible_query_files / recommended_train_queries / recommended_test_queries

结论：

• 现在可以批量对比多个候选开放数据目录的可用规模
• 这让后续接入真实 FMA / MTG-Jamendo / 其他音乐集更高效

2026-06-02

Stage: 文档补全 + ACR 最小可运行链路

完成项：

• 补充项目职责图：docs/project-responsibility-map.md
• 补充系统架构图：docs/acr-architecture.md
• 补充阶段路线图：docs/roadmap.md
• 补充运行手册：docs/runbook.md
• 补充引擎说明：acr-engine/README.md
• 新增依赖清单：acr-engine/requirements.txt
• 新增 demo CLI：acr-engine/run_demo.py
• 修复数据集读取路径问题：acr-engine/src/data/dataset.py
• 修复首次训练不落 best checkpoint 的问题：acr-engine/train.py

验证结果：

• 已生成 synthetic dataset
• 已通过 train.py --dry-run
• 已完成 1 epoch CPU 训练并生成 best_model.pt
• 已完成指纹索引与 embedding 索引构建
• 已完成识别命令并输出 JSON 候选结果

2026-06-02

Stage: 准确率优化 v2（128 Mel / band-split / retrieval 评测 / dataset 规范 / SOTA 调研）

完成项：

• 补充 dataset / 输入输出规范：docs/dataset-spec.md
• 补充开源数据集接入计划：docs/open-dataset-plan.md
• 补充 2026 SOTA 研究说明：docs/sota-research-2026.md
• 输入特征从低维说话人风格配置改为 128 Mel
• 新增频带分割模块 BandSplitBlock
• 引入 pro-WGAN 风格工程近似平衡策略（针对困难样本的更强增广）
• 合成数据新增 confused / humming_like 样本类型
• 引入 catalog.json 作为可搜索 reference 清单
• 索引从整曲单向量改为 window-level embedding index
• 新增 evaluate.py 做 retrieval 评测
• 训练逻辑改为更 retrieval-oriented 的 song-pair 训练输入

验证结果：

• synthetic_v2 端到端重新跑通
• build-index 成功
• evaluate 成功
• test split 指标：top1=0.65, top5=0.95
• 分类型指标：
  • clean top1=1.00
  • augmented top1=0.75
  • humming_like top1=0.25
  • confused top1=0.25

结论：

• 结构性错误（catalog/index/fusion/评测缺失）已明显改善
• 当前主要剩余短板是 humming_like / confused 的鲁棒识别

2026-06-02

Stage: 工业化服务骨架 + 外部 manifest 转换模板

完成项：

• 新增 FastAPI 服务骨架：acr-engine/src/service/app.py
• 新增 manifest 转换工具：acr-engine/src/data/manifest_tools.py
• 新增工业 benchmark 文档：docs/industrial-benchmark-spec.md
• 扩展外部 dataset adapter CLI：acr-engine/src/data/external_adapters.py
• 新增服务 API 文档：docs/service-api.md
• requirements 增加 FastAPI / uvicorn / pydantic

验证结果：

• external_adapters.py registry 成功
• external_adapters.py describe ccmusic 成功
• external_adapters.py init modelscope_music 成功
• manifest_tools.py csv-to-catalog 成功生成 catalog
• service.app health() 返回 {"status":"ok"}
• API build_index(...) 成功返回 reference window 数量
• API recognize(...) 成功返回候选结果
• train.py --dry-run 成功

2026-06-02

Stage: 文档治理闭环（导航 / 引用 / 模板）

完成项：

• 新增 docs/README.md 作为文档总入口
• 新增 docs/references-and-sources.md 作为引用来源总图
• 新增 docs/benchmark-report-template.md
• 新增 docs/model-card-template.md
• 新增 docs/release-checklist.md
• 核心文档统一补充 Sources 小节
• 核心文档统一补齐 executive summary / mermaid / table / appendix 风格

验证结果：

• docs 总入口结构检查通过
• references map 结构检查通过
• 核心 docs 存在性检查通过
• benchmark/model/release 模板结构检查通过
• 所有核心文档均具备 Sources；SOTA 文档已补齐 Mermaid 图

2026-06-02

Stage: 真实评测到发布产物链路打通

完成项：

• evaluate.py 支持 --output-json
• 新增 docs/report-layout.md
• 新增 scripts/generate_artifacts.py
• 打通 eval.json -> benchmark-report.md / model-card.md / release-checklist.md / artifact-manifest.json
• 为快速发布链路新增 --fast-eval（关闭 melody 重排以加快报告生成）

验证结果：

• synthetic_v2 重建、训练、建索引成功
• evaluate.py --fast-eval --output-json ... 成功输出 JSON
• artifact generator 成功输出 4 类发布产物
• reports/smoke-v2/synthetic_v2/ 目录产物存在性检查通过
• 当前 fast-eval 指标：top1=0.60, top5=0.75，hard-case 仍需继续优化

2026-06-02

Stage: 外部数据集 bootstrap + hard-case 过采样试验

完成项：

• 新增 src/data/bootstrap_external.py
• 可自动为 fma / ccmusic 生成 bootstrap catalog manifest
• 在 SongPairDataset 中加入困难样本过采样试验（confused / humming_like）
• 重新训练 models_v4、重建 index_v4、重跑 smoke-v4 评测

验证结果：

• data/external_bootstrap/fma/manifests/catalog.bootstrap.json 成功生成
• data/external_bootstrap/ccmusic/manifests/catalog.bootstrap.json 成功生成
• reports/smoke-v4/synthetic_v2/eval.json 成功生成
• 当前试验结果：top1=0.40, top5=0.80
• hard-case 结果未改善：
  • humming_like top1=0.00
  • confused top1=0.00

结论：

• 该轮简单过采样策略无效，且整体精度下降
• 下一轮应改用更细粒度 hard-negative / melody-aware 正则，而不是继续放大样本重复权重

2026-06-02

Stage: MTG-Jamendo / ModelScope bootstrap + type-aware hard-case weighting

完成项：

• 补充 mtg_jamendo 与 modelscope_music 的 bootstrap manifest 生成
• 在训练链路中加入 type-aware hard-case weighting（针对 confused / humming_like）
• 重训 models_v5、重建 index_v5、重跑 smoke-v5 评测

验证结果：

• data/external_bootstrap/mtg_jamendo/manifests/catalog.bootstrap.json 成功生成
• data/external_bootstrap/modelscope_music/manifests/catalog.bootstrap.json 成功生成
• reports/smoke-v5/synthetic_v2/eval.json 成功生成
• 当前结果：top1=0.60, top5=0.90
• hard-case 结果：
  • humming_like top1=0.50（较 v4 有提升）
  • confused top1=0.00（仍未解决）

结论：

• type-aware weighting 比 naive oversampling 更有效
• 下一轮应专门针对 confused 类设计更强的 negative mining / confusion-aware 信号