README.md



词曲 & 音眼资产导入工具

本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 hk_songs 表，并提供 L2 歌词去重测试和人工复核前端。


项目结构

.
├── import_hk_songs.py          # 主脚本：聚合查询、去重、导入
├── lyric_dedup/                # 歌词去重核心模块
│   ├── normalization.py        # 歌词文本规范化
│   ├── checker.py              # 去重匹配逻辑
│   ├── eval_dataset.py         # 评测数据集构建
│   ├── file_import.py          # 文件导入工具
│   └── cli.py                  # CLI 入口
├── test_dedup.py               # 单元测试 & L2 benchmark
├── serve_l2_dashboard.py       # L2 测试复核前端服务
├── l2_review_dashboard.html    # 前端页面
├── requirements.txt            # Python 依赖
├── 测试流程指南.md              # L2 测试流程说明
└── .env                        # 数据库配置（不纳入版本控制）


快速开始


1. 安装依赖

pip install -r requirements.txt


2. 配置数据库

复制 .env.example 为 .env 并填写数据库连接信息：

YINYAN_DB_HOST=...
YINYAN_DB_PORT=3306
YINYAN_DB_USER=...
YINYAN_DB_PASSWORD=...
YINYAN_DB_NAME=...

CIKU_DB_HOST=...
CIKU_DB_PORT=3306
CIKU_DB_USER=...
CIKU_DB_PASSWORD=...
CIKU_DB_NAME=...


3. 运行数据导入

python import_hk_songs.py --help


4. 运行 L2 歌词去重测试

小样本验证：

RUN_L2_BENCHMARK=1 \
L2_BENCHMARK_LIMIT=20 \
L2_BENCHMARK_EXISTING_LIMIT=50 \
L2_BENCHMARK_TOPKS=20,100 \
python -m pytest test_dedup.py::TestL2Benchmark::test_l2_recall_topk_efficiency_and_review_artifacts -q -s


详见 测试流程指南.md。


5. 启动复核前端

python serve_l2_dashboard.py --host 127.0.0.1 --port 8765


然后访问 http://127.0.0.1:8765 查看测试报告、比对歌词、人工标注。


普通单元测试

python -m pytest test_dedup.py -q


注意事项


.env 文件包含数据库凭据，不要提交到仓库。

output/ 目录存放测试生成的报告和歌词文件，不纳入版本控制。
CSV / SQL / Excel 等数据文件不纳入版本控制。