CHANGELOG.md 12.7 KB

Raw Blame History Permalink



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: 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 信号