CHANGELOG.md 125 KB

Raw Blame History Permalink



Changelog


2026-06-02


Stage: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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/wait_for_fma_and_prepare.py

支持：


周期性检查 FMA archive 是否已完整
完整后自动调用 fma_postdownload_ready.py

未完成时返回结构化 waiting 快照


将脚本接入 docs/open-dataset-workflow.md 与 docs/session-handoff.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/wait_for_fma_and_prepare.py 成功

/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 2 --max-cycles 2 成功
当前结果：


第 1 次快照 archive_size=2110291968

第 2 次快照 archive_size=2115256320

status=waiting
最新进度 27.5439%


结论：


现在仓库已经具备“等待完成 -> 自动切入解压/就绪检查”的衔接能力
后续 session 可以用单命令挂起等待，而不是反复手工轮询


Stage: FMA 下载完成后自动就绪

完成项：


新增 acr-engine/scripts/fma_postdownload_ready.py

在 FMA 整包完成后，可自动执行：


extract
check-local-ready
inspect-local


将该脚本挂接到 docs/open-dataset-workflow.md 与 docs/session-handoff.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/fma_postdownload_ready.py 成功

/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 成功返回结构化结果
当前结果：


status=blocked
reason=archive_not_complete
archive_size=1631584256
progress_percent=21.2457


结论：


真实 FMA 下载一旦完成，仓库已经具备单命令进入“解压 + 本地就绪检查”的能力
后续 session 不需要再手工串接这些步骤


Stage: pgvector bulk load plan 模板

完成项：


新增 acr-engine/scripts/pgvector_bulk_load_template.py

为 pgvector 导出结果补充 PostgreSQL bulk-load plan 模板
在 docs/training-data-and-pgvector-guide.md 中补充对应说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/pgvector_bulk_load_template.py 成功

/usr/local/miniconda3/bin/python scripts/pgvector_bulk_load_template.py --input reports/pgvector_manifest_export_test.json --output reports/pgvector_bulk_load_plan_test.json 成功
当前结果：


songs=24
references=24
segments=20


结论：


pgvector 方向现在已经具备：


schema 模板
manifest 导出模板
bulk-load plan 模板


后续接真实 PostgreSQL 时，只差 live loader，而不是从零设计数据入口


Stage: pgvector 落库模板

完成项：


新增 acr-engine/sql/pgvector_schema.sql

新增 acr-engine/scripts/export_manifest_to_pgvector_json.py

在 docs/training-data-and-pgvector-guide.md 中补充可执行模板说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/export_manifest_to_pgvector_json.py 成功

/usr/local/miniconda3/bin/python scripts/export_manifest_to_pgvector_json.py --data data/synthetic_v2 --split test --source-dataset synthetic_v2 --output reports/pgvector_manifest_export_test.json 成功
当前导出结果：


songs=24
references=24
segments=20


结论：


pgvector 方向现在不仅有概念文档，还有可直接复用的 schema 和 manifest 导出桥接脚本
后续接 PostgreSQL 时返工成本会显著降低


Stage: FMA 下载自动守护

完成项：


新增 acr-engine/scripts/watch_fma_download.py

支持周期性：


inspect 当前下载进度
检查 curl 进程是否存活
如果停滞或进程消失则自动重新触发 bg-download


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/watch_fma_download.py 成功

/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 2 --interval 2 成功
当前 watcher 观测到：


第 1 次 archive_size=513179648

第 2 次 archive_size=516587520

两次 live_curl=true

两次 restarted=null（说明下载健康推进，无需重启）


最新 inspect：


archive_size=522387456
archive_progress_percent=6.8023


结论：


现在真实 FMA 下载不只可手动恢复，也具备基础自动守护能力
长时间下载的持续性进一步增强


Stage: 训练数据与 pgvector 专项文档

完成项：


新增 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练数据/输入数据应该是什么格式

reference / query 的角色区分
BGM / 手机录音 / 直播录屏如何转成训练数据

song_id / type / offset / segment_type 等标签建议
未来接 pgvector 时的推荐表结构与字段设计


将该文档挂接到 docs/README.md 与 docs/session-handoff.md


验证结果：


文档内容已对齐当前代码行为：


acr-engine/src/data/dataset.py
acr-engine/src/data/manifest_tools.py


已补充从“原始音频 -> 标准化资产 -> manifest -> pgvector”的完整分层说明


结论：


现在项目对“训练数据应该长什么样”与“以后怎么接 pgvector”已经有独立、可交接、可执行的文档说明


Stage: FMA 后台续传恢复

完成项：


为 acr-engine/scripts/prepare_fma_archive.py 新增 bg-download

使用 nohup curl + 日志文件的方式增强大文件后台续传稳定性
在发现下载停滞后，切换到新的后台恢复路径并重新托管 ModelScope 下载


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py bg-download 成功
当前返回：


returncode=0
pid=47175
log_path=/tmp/fma_modelscope_download.log


重新 inspect 后结果：


archive_size 从 61550592 增长到 71835648

archive_progress_percent=0.9354


日志验证：


Resuming transfer from byte position 61550592
当前吞吐已达到 MB/s 级别


结论：


FMA 真实数据下载不再依赖脆弱的一次性前台命令
当前已恢复到可持续的后台续传状态，后续 session 更容易接力


Stage: FMA 下载进度可视化

完成项：


增强 acr-engine/scripts/prepare_fma_archive.py 的 inspect 输出
新增：


archive_bytes_expected
archive_progress_ratio
archive_progress_percent


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/prepare_fma_archive.py 成功

/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
当前结果：


archive_size=61550592
archive_progress_percent=0.8015


结论：


新 session 现在不需要手工换算大包下载进度
长时间 FMA 下载的交接成本进一步降低


Stage: FMA 源切换到 ModelScope

完成项：


将 acr-engine/scripts/prepare_fma_archive.py 的默认 FMA 整包源切换到用户提供的 ModelScope 地址
同步更新：


acr-engine/data/raw/README.md
docs/open-dataset-workflow.md
docs/session-handoff.md


通过 repo 内脚本重新启动托管下载流程


验证结果：


curl -I -L --max-time 60 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 成功
当前响应关键信息：


200
content-length=7679594875
accept-ranges: bytes


curl -L --range 0-1023 ... 成功获取 1024 bytes

/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
当前结果：


archive_url=https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip
archive_size=53620736
托管下载进程存在：prepare_fma_archive.py download


结论：


真实 FMA 下载现在已切换到用户指定的 ModelScope 通道
下载控制面也已统一回 repo 内脚本，后续 session 更容易续传与接力


Stage: 服务 HTTP smoke

完成项：


新增 acr-engine/scripts/service_smoke.py

用 uvicorn 真正拉起 FastAPI 服务，而不是只做函数级调用
更新 acr-engine/README.md 与 docs/service-api.md 的服务运行说明


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/service_smoke.py 成功

/usr/local/miniconda3/bin/python scripts/service_smoke.py 成功
当前 smoke 已验证：


/health
/ready
/config
/cache


当前结果：


health.ready=true
ready.ready=true

engine_cache_size=0（未执行 recognize 前）


结论：


服务现在已经具备最小 HTTP 级 smoke 验证
后续继续做鉴权、异步任务、监控时，有了更真实的回归入口


Stage: 服务就绪探针与缓存可见性

完成项：


增强 acr-engine/src/service/app.py

新增：


/ready
/cache


为服务默认模型/索引/manifest 增加 readiness 快照
为 HybridEngine 增加进程内缓存，避免同配置重复重载
更新 docs/service-api.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile src/service/app.py 成功
直接调用 health() / ready() / cache_status() 成功
直接调用 _load_engine() 两次成功
当前结果：


默认 service ready=true

首次加载 cache_hit=false

第二次加载 cache_hit=true

same_object=true


结论：


服务层现在不再只是“能调接口”的骨架
已具备最基本的就绪探针与缓存可见性，更接近工业级内网服务原型


Stage: FMA 整包下载/解压脚手架

完成项：


新增 acr-engine/scripts/prepare_fma_archive.py

支持：


inspect

download（支持 resume）
extract


将 FMA 官方整包路径接入：


acr-engine/data/raw/README.md
docs/open-dataset-workflow.md


验证结果：


/usr/local/miniconda3/bin/python -m py_compile scripts/prepare_fma_archive.py 成功

/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 成功
当前结果：


archive_exists=true
archive_size=9404416
extract_exists=true
num_audio_files=0


结论：


真实 FMA 整包路径现在不仅在下载，而且已经有标准化的 inspect/download/extract 工具链
即使下载耗时较长，后续 session 也能直接续传与接力


Stage: FMA 官方整包下载路径确认

完成项：


进一步验证 FMA Small 的稳定 archive 下载路径
确认 fma_small.zip 可通过官方归档地址直接访问
将该路径补充到开放数据工作流与交接文档


验证结果：


curl -I -L --max-time 60 https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 成功
当前响应头关键信息：


200 OK
Content-Type: application/zip
Content-Length: 7679594875
Accept-Ranges: bytes


curl -L --range 0-1023 ... 成功获取前 1024 bytes


结论：


FMA 真实数据已经不再缺下载地址
当前剩余问题从“找不到稳定 URL”转为“是否开始实际拉取 7.68 GB 归档并落盘”


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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: 真实 FMA 守护长时稳定性再验证

完成项：


再次复检 detached guard 进程与运行时长
检查守护日志是否继续稳定跨轮输出
再次复检后处理门槛状态


验证结果：


守护进程继续存活：


pid=52277
PPID=1
运行时长 02:15


守护日志已继续增长到至少 5 轮：


cycle=4, 60.0672%


cycle=5, 62.0764%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4836065280
archive_progress_percent=62.9729


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=62.9733


结论：


detached guard 当前已显示出连续多轮、多分钟级别的稳定驻留能力
当前仍未切换阶段的唯一原因，是归档尚未达到完整字节数


Stage: 真实 FMA 守护稳定性续验

完成项：


复检新守护进程 pid 与运行时长
复检守护日志是否已跨更多轮持续输出
再次执行后处理就绪检查，确认是否仍被未完成归档阻塞


验证结果：


守护进程持续存活：


pid=52277
PPID=1
运行时长 01:29


守护日志已连续输出至少 3 轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


cycle=3, 58.5098%


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4612112384
archive_progress_percent=60.0567


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
progress_percent=60.0582


结论：


新的守护启动方式已表现出明显更好的长期稳定性
当前唯一阻塞继续保持为：FMA 归档尚未完整下载


Stage: 真实 FMA 后台守护方式稳定化

完成项：


对 wait_for_fma_and_prepare.py 做前台多轮复现实验，确认逻辑本身不是“首轮即崩”
判断二次掉线更可能来自后台脱离方式而非轮询逻辑
新增 acr-engine/scripts/start_wait_for_fma_guard.sh，使用 setsid + 明确工作目录 + pid/log 文件启动长期守护
验证新守护方式可跨多轮轮询持续存活


验证结果：


前台验证：


/usr/local/miniconda3/bin/python -u scripts/wait_for_fma_and_prepare.py --interval 1 --max-cycles 3
连续输出 3 轮 polling，并正常结束为 status=waiting


下载进度继续增长到：


4261445632 -> 4265574400
55.4905% -> 55.5443%


新守护脚本启动后：


pid=52277

PPID=1
进程状态仍存活


守护日志已连续输出至少两轮：


cycle=1, 55.8297%


cycle=2, 57.0573%


结论：


之前等待器掉线的主因更接近后台启动/脱离方式，而非轮询主循环本身
现在真实 FMA 自动承接链路已有更稳的守护启动入口


Stage: 真实 FMA 长时等待器二次掉线复验

完成项：


复检长期等待器与日志输出状态
确认下载继续前进，但长期等待器再次退出
重新拉起等待器，恢复“下载完成后自动后处理”能力


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=4102045696
archive_progress_percent=53.4149


进程侧未发现 wait_for_fma_and_prepare.py

日志文件只保留首轮输出：


cycle=1
archive_progress_percent=52.5032


重新启动后，进程再次恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


结论：


下载本身没有停，问题集中在长期等待器稳定性仍不足
下一步需要继续定位其二次退出原因，避免只靠重启维持自动承接链路


Stage: 真实 FMA 等待器寿命缺陷修复

完成项：


诊断 wait_for_fma_and_prepare.py 掉线原因
确认原实现默认 max-cycles=3，约 90 秒后自然退出
修复为：max-cycles=0 时无限等待，并在每轮轮询输出进度日志
重新启动长期等待器并验证日志开始产生轮询输出


验证结果：


复检下载进度时已达到：


archive_size=3886596096
archive_progress_percent=50.6094


修复后执行：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 0.1 --max-cycles 2
返回两轮 polling，并确认字节继续增长到：
3977117696 -> 3977314304
51.7881% -> 51.7907%


长期等待器已重新启动：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30


日志文件 .omx_wait_for_fma.log 已开始输出轮询 JSON


结论：


之前等待器掉线不是下载异常，而是脚本寿命设计过短
现在真实 FMA 链路已具备可长期驻留的自动等待与后处理能力


Stage: 真实 FMA 守护链路掉线恢复

完成项：


再次复检 FMA 下载进度
复检后台等待器是否仍存活
发现等待器已退出后，重新拉起自动等待与后处理守护链路


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3650322432
archive_progress_percent=47.5327


复检时未发现 wait_for_fma_and_prepare.py --interval 30 --max-cycles 400 仍在运行
等待器日志文件存在但为空：


acr-engine/.omx_wait_for_fma.log


重新启动后，进程确认恢复：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


新守护进程 pid：51526


结论：


真实 FMA 下载仍在持续推进
自动承接链路曾短暂掉线，但现在已恢复到“下载完成后自动后处理”的可继续状态


Stage: 真实 FMA 自动等待与后处理守护启动

完成项：


再次复检 FMA 归档进度
检查是否已有后台“等待完成后自动后处理”任务
启动 wait_for_fma_and_prepare.py 守护链路，确保下载完成后可自动衔接后处理


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3518038016
archive_progress_percent=45.8102


启动后台等待器后，进程确认存在：


/usr/local/miniconda3/bin/python scripts/wait_for_fma_and_prepare.py --interval 30 --max-cycles 400


当前后台等待器 pid：51242

等待器日志文件已创建：


acr-engine/.omx_wait_for_fma.log


结论：


除了持续下载本身，现在“下载完成 -> 自动后处理”的承接链路也已常驻
后续无需人工频繁盯守即可在归档完成后自动推进到下一阶段


Stage: 真实 FMA 下载活跃性复验

完成项：


再次采集 FMA 归档字节进度
执行 watchdog 续验并附带进程级活跃性确认


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3403972608
archive_progress_percent=44.3249


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3406938112
archive_progress_percent=44.3635
live_curl=true
restarted=null


进程侧确认：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip 仍在运行


结论：


下载链路仍在持续前进且后台拉取进程健康
真实 FMA 下游工作仍等待归档完整这一单一前置条件


Stage: 真实 FMA 后处理门槛复验

完成项：


再次复检 FMA 下载进度
直接执行后处理就绪脚本，验证是否已达到“可解压/可继续”的门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3322314752
archive_progress_percent=43.2616


/usr/local/miniconda3/bin/python scripts/fma_postdownload_ready.py 返回：


status=blocked
reason=archive_not_complete
archive_size=3323641856
progress_percent=43.2789


结论：


真实 FMA 下载仍在继续推进，但仍未达到后处理门槛
当前阻塞已被脚本化验证，不是人工主观判断


Stage: 真实 FMA 下载续进展验证

完成项：


再次执行 FMA 归档 inspect

执行一次下载 watchdog 续验，确认后台传输仍存活且无需重启


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_size=3222601728
archive_progress_percent=41.9632


/usr/local/miniconda3/bin/python scripts/watch_fma_download.py --cycles 1 --interval 2 返回：


archive_size=3222896640
archive_progress_percent=41.967
live_curl=true
restarted=null


对比上一阶段，归档已从 3117514752 字节继续增长到 3222896640 字节


结论：


当前下载未卡死，仍在稳定推进
真实 FMA 的解压与 smoke 验证继续受制于归档尚未完成这一单一门槛


Stage: 真实 FMA 下载状态续验

完成项：


复检用户指定 FMA 源下载状态：https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip

复检后台下载进程与本地归档体积
确认当前仍未达到可解压/可真实 smoke 的完成门槛


验证结果：


/usr/local/miniconda3/bin/python scripts/prepare_fma_archive.py inspect 返回：


archive_bytes_expected=7679594875
archive_size=3117514752
archive_progress_percent=40.5948
num_audio_files=0


后台下载进程仍存活：


curl -L --continue-at - --output data/raw/fma_small.zip https://modelscope.cn/datasets/pengzhendong/fma/resolve/master/fma_small.zip


当前本地归档文件：


data/raw/fma_small.zip = 3.0G


结论：


当前主卡点仍是 FMA 归档未完整下载
真实 FMA 的解压、prepare、smoke-local 需要等待归档达到完整体积后继续


Stage: 训练数据与 pgvector 专项说明补强

完成项：


重写并补强 docs/training-data-and-pgvector-guide.md

单独详细说明：


当前训练输入应由音频资产 + song_id 标签 + manifest 组成
reference 与 query 的角色区分
BGM / 手机录音 / 环境录音 / 直播录屏如何转成训练样本
面向 PostgreSQL + pgvector 的字段保留与入库分层


将该专项文档挂接到 docs/README.md 的“数据与评测”主入口


验证结果：


已校验文档内新增相对链接全部可达
文档已覆盖：


输入格式
切片时长建议
label 设计

song_id/version_id 规范

pgvector 数据模型与入库流程


当前引用的仓库内实现锚点：


acr-engine/scripts/export_manifest_to_pgvector_json.py
acr-engine/sql/pgvector_schema.sql


结论：


现在“训练数据应该长什么样”“BGM/录音如何转训练集”“未来如何接 pgvector”已经有单独成体系文档
新 session 与后续数据工程实现可直接按该文档落地


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