README.md



ACR Engine

一个可运行的听歌识曲原型，包含：


合成数据集生成
传统音频指纹（landmark hash）匹配
深度 embedding 检索（ECAPA-TDNN）
Hybrid 混合识别入口


快速开始

cd acr-engine
/usr/local/miniconda3/bin/python -m pip install -r requirements.txt
/usr/local/miniconda3/bin/python run_demo.py full-demo --device cpu


常用命令


1. 生成合成数据

python run_demo.py generate-data --output data/synthetic --num-songs 24


2. 训练前做干跑校验

python train.py --data data/synthetic --dry-run --device cpu


3. 训练一个最小模型

python train.py --data data/synthetic --output data/models --device cpu --epochs 1 --batch-size 8


4. 构建指纹与 embedding 索引

python run_demo.py build-index --data data/synthetic --model data/models/best_model.pt --output data/index


5. 跑识别

python run_demo.py recognize \
  --query data/synthetic/segments/song_0020_seg_00.wav \
  --data data/synthetic \
  --model data/models/best_model.pt \
  --index-prefix data/index/reference


6. 一键最小闭环

python run_demo.py full-demo --device cpu


服务启动与 smoke


启动服务

cd acr-engine
/usr/local/miniconda3/bin/python -m uvicorn src.service.app:app --host 127.0.0.1 --port 8000


运行服务 smoke

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


常看接口


GET /health
GET /ready
GET /config
GET /cache


目录


train.py：训练入口

run_demo.py：数据生成 / 建索引 / 识别 / 一键 demo

src/data：数据集和合成数据生成

src/models：ECAPA 模型与损失

src/engines：指纹、embedding、hybrid 检索

configs/default.yaml：默认配置


当前定位

这是一个原型仓库，目标是验证 ACR 主链路能否跑通，不是生产级服务。


评测

python evaluate.py --data data/synthetic --model data/models/best_model.pt --index-prefix data/index/reference --split test --device cpu


本地 20 首歌流程与生产向量库约定


本地小样本（如 /workspace/downloads 的 20 首歌流程）优先使用 FAISS。
若后续本机安装了 chromadb，可作为可选对照后端，但不是默认依赖。
生产环境统一保留 pgvector 作为正式向量存储与检索底座。


本地 20 首歌流程：

cd acr-engine
/usr/local/miniconda3/bin/python scripts/local_music20_acr.py \
  --downloads-dir /workspace/downloads \
  --song-limit 20 \
  --backend faiss \
  --output data/local_eval/music20_summary.json


说明：


query_type=1/7/8/16 会在一个汇总 JSON 里统一输出。
默认本地后端为 faiss。
若使用 --backend chromadb 且环境缺少 chromadb，脚本会明确报错提示。
生产向量化链路仍走 scripts/export_manifest_to_pgvector_json.py 与后续 pgvector 入库。


当前提升方向


更强合成混淆样本（confused / humming_like）
Hybrid 分数归一化后再融合
full-demo 自动训练
后续可接入开源数据集