README.md



词曲 & 音眼资产导入工具

本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 hk_songs 表，并提供：


L1 层：基于元数据（歌名 + 词曲作者）的六步标准化去重

L2 层：基于歌词文本 Jaccard 相似度的深度去重

ETL 管道：将词曲库数据同步至爬虫库（crawler），支持断点续传

审计工具：库内重复数据审计、L2 歌词审计、BPM 分类补全

复核前端：L2 去重测试的人工评审看板


项目结构

.
├── import_hk_songs.py              # 主脚本：聚合查询、L1/L2 去重、导入
├── run_etl.py                      # ETL 入口：hk_songs → crawler 库同步
├── etl_to_crawler/                 # ETL 管道模块
│   ├── config.py                   # 多库 & OSS 配置
│   ├── connections.py              # 数据库连接管理
│   ├── reader.py                   # 源表分批读取
│   ├── spider.py                   # 平台数据抓取/构造
│   ├── writer.py                   # 目标库写入
│   ├── runner.py                   # 编排引擎（断点续传）
│   ├── lyric.py                    # 歌词下载与处理
│   └── oss.py                      # OSS 上传
├── lyric_dedup/                    # 歌词去重核心模块
│   ├── normalization.py            # 歌词文本规范化（NFKC + OpenCC）
│   ├── checker.py                  # 去重匹配逻辑（L1/L2 六步算法）
│   ├── eval_dataset.py             # 评测数据集构建
│   ├── file_import.py              # 文件导入工具
│   └── cli.py                      # CLI 入口
├── audit_hk_songs_duplicates.py    # L1 元数据重复审计 & 合并修复
├── audit_hk_songs_l2.py            # L2 歌词去重库内审计（下载+比对）
├── backfill_bpm_class.py           # BPM 分类增量补全
├── migrate_test_to_prod.py         # 测试表 → 正式表迁移（含 COS 转存）
├── patch_merge_authors.py          # 作者合并补处理脚本
├── create_hk_songs_import_staging.sql  # 暂存表建表 DDL
├── serve_l2_dashboard.py           # L2 复核前端服务
├── l2_review_dashboard.html        # 前端页面
├── tests/                          # 单元测试
│   ├── test_lyric.py
│   ├── test_oss.py
│   ├── test_reader.py
│   ├── test_runner.py
│   ├── test_spider.py
│   └── test_writer.py
├── test_dedup.py                   # 去重单元测试 & L2 benchmark
├── test_audit_hk_songs_duplicates.py  # 审计脚本单元测试
├── docs/                           # 文档
├── requirements.txt                # Python 依赖
├── 测试流程指南.md                  # L2 测试流程说明
├── 音眼数据库配置.md                # 数据库配置说明
├── 音眼词曲跨库去重任务清单.md      # 跨库去重任务清单
└── .env                            # 环境配置（不纳入版本控制）


快速开始


1. 安装依赖

pip install -r requirements.txt


2. 配置数据库

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

# 源库 - 音眼
SOURCE_DB_HOST=
SOURCE_DB_PORT=3306
SOURCE_DB_USER=
SOURCE_DB_PASSWORD=
SOURCE_DB_NAME=

# 目标库 - 词曲库
TARGET_DB_HOST=
TARGET_DB_PORT=3306
TARGET_DB_USER=
TARGET_DB_PASSWORD=
TARGET_DB_NAME=
TARGET_TABLE_NAME=hk_songs

# OSS 配置
OSS_ACCESS_KEY_ID=
OSS_ACCESS_KEY_SECRET=
OSS_ENDPOINT=
OSS_BUCKET_NAME=
OSS_FILE_BASE_NAME=


3. 运行数据导入

python import_hk_songs.py --help


4. 运行 ETL 同步至爬虫库

# 全量同步（支持断点续传）
python run_etl.py --resume

# 冒烟测试（仅前 3 批）
python run_etl.py --max-batches 3

# 指定平台
python run_etl.py --platform qq --resume


5. 审计工具

# L1 元数据重复审计
python audit_hk_songs_duplicates.py

# L1 应用合并（软删 loser + 作者增量合并）
python audit_hk_songs_duplicates.py --apply-merge

# L2 歌词去重审计（下载 + 比对）
python audit_hk_songs_l2.py --phase all --workers 32

# BPM 分类补全
python backfill_bpm_class.py --dry-run

# 测试表迁移至正式表
python migrate_test_to_prod.py --limit 10 --dry-run


6. 运行 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。


7. 启动复核前端

先在 .env 配置审核编辑暗号（支持中文或英文）：

REVIEW_ACCESS_CODE=请替换成你的暗号


暗号只在服务端校验。验证成功后，当前浏览器标签页会获得默认有效期 12 小时的临时编辑会话；未配置暗号或验证失败时，领取、审核、撤销、删除和入库接口均不可调用。

首次启用多人审核时，先让服务补齐领取和乐观锁字段（已有审核结果不会被修改）：

python serve_l2_dashboard.py --migrate-review-schema --host 127.0.0.1 --port 8765


后续正常启动：

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


然后访问 http://127.0.0.1:8765，填写审核人姓名或工号后开始审核。打开 pending/unsure 的人工复核记录时会自动领取；new/merge/skip/已审核 记录仅供浏览，不会领取。领取冲突只会将当前记录设为只读，不会刷新列表或跳转。其他审核人的结果约 15 秒内轻量同步，统计信息每分钟刷新一次，页面处于后台时暂停轮询。


单元测试

# 去重测试
python -m pytest test_dedup.py -q

# ETL 模块测试
python -m pytest tests/ -q

# 审计脚本测试
python -m pytest test_audit_hk_songs_duplicates.py -q


注意事项


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

output/ 目录存放测试报告和缓存文件，不纳入版本控制。
CSV / SQL / Excel 等数据文件不纳入版本控制。
# 词曲 & 音眼资产导入工具


本项目用于将音眼（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 等数据文件不纳入版本控制。