Skip to content

沈秋雨 / import_hk_songs

Go to a project
Toggle navigation
Toggle navigation pinning
Commit e04906eb e04906eb6f70431628e0c0ec5a7b79e15c767ebb by 沈秋雨
Options

更新readme

1 parent 5a9a4064
Inline Side-by-side
Showing 1 changed file with 170 additions and 0 deletions
1 # 词曲 & 音眼资产导入工具 1 # 词曲 & 音眼资产导入工具
2 2
3 本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 `hk_songs` 表，并提供：
4
5 - **L1 层**：基于元数据（歌名 + 词曲作者）的六步标准化去重
6 - **L2 层**：基于歌词文本 Jaccard 相似度的深度去重
7 - **ETL 管道**：将词曲库数据同步至爬虫库（crawler），支持断点续传
8 - **审计工具**：库内重复数据审计、L2 歌词审计、BPM 分类补全
9 - **复核前端**：L2 去重测试的人工评审看板
10
11 ## 项目结构
12
13 ```
14 .
15 ├── import_hk_songs.py # 主脚本：聚合查询、L1/L2 去重、导入
16 ├── run_etl.py # ETL 入口：hk_songs → crawler 库同步
17 ├── etl_to_crawler/ # ETL 管道模块
18 │ ├── config.py # 多库 & OSS 配置
19 │ ├── connections.py # 数据库连接管理
20 │ ├── reader.py # 源表分批读取
21 │ ├── spider.py # 平台数据抓取/构造
22 │ ├── writer.py # 目标库写入
23 │ ├── runner.py # 编排引擎（断点续传）
24 │ ├── lyric.py # 歌词下载与处理
25 │ └── oss.py # OSS 上传
26 ├── lyric_dedup/ # 歌词去重核心模块
27 │ ├── normalization.py # 歌词文本规范化（NFKC + OpenCC）
28 │ ├── checker.py # 去重匹配逻辑（L1/L2 六步算法）
29 │ ├── eval_dataset.py # 评测数据集构建
30 │ ├── file_import.py # 文件导入工具
31 │ └── cli.py # CLI 入口
32 ├── audit_hk_songs_duplicates.py # L1 元数据重复审计 & 合并修复
33 ├── audit_hk_songs_l2.py # L2 歌词去重库内审计（下载+比对）
34 ├── backfill_bpm_class.py # BPM 分类增量补全
35 ├── migrate_test_to_prod.py # 测试表 → 正式表迁移（含 COS 转存）
36 ├── patch_merge_authors.py # 作者合并补处理脚本
37 ├── create_hk_songs_import_staging.sql # 暂存表建表 DDL
38 ├── serve_l2_dashboard.py # L2 复核前端服务
39 ├── l2_review_dashboard.html # 前端页面
40 ├── tests/ # 单元测试
41 │ ├── test_lyric.py
42 │ ├── test_oss.py
43 │ ├── test_reader.py
44 │ ├── test_runner.py
45 │ ├── test_spider.py
46 │ └── test_writer.py
47 ├── test_dedup.py # 去重单元测试 & L2 benchmark
48 ├── test_audit_hk_songs_duplicates.py # 审计脚本单元测试
49 ├── docs/ # 文档
50 ├── requirements.txt # Python 依赖
51 ├── 测试流程指南.md # L2 测试流程说明
52 ├── 音眼数据库配置.md # 数据库配置说明
53 ├── 音眼词曲跨库去重任务清单.md # 跨库去重任务清单
54 └── .env # 环境配置（不纳入版本控制）
55 ```
56
57 ## 快速开始
58
59 ### 1. 安装依赖
60
61 ```bash
62 pip install -r requirements.txt
63 ```
64
65 ### 2. 配置数据库
66
67 复制 `.env.example` 为 `.env` 并填写数据库连接信息：
68
69 ```env
70 # 源库 - 音眼
71 SOURCE_DB_HOST=
72 SOURCE_DB_PORT=3306
73 SOURCE_DB_USER=
74 SOURCE_DB_PASSWORD=
75 SOURCE_DB_NAME=
76
77 # 目标库 - 词曲库
78 TARGET_DB_HOST=
79 TARGET_DB_PORT=3306
80 TARGET_DB_USER=
81 TARGET_DB_PASSWORD=
82 TARGET_DB_NAME=
83 TARGET_TABLE_NAME=hk_songs
84
85 # OSS 配置
86 OSS_ACCESS_KEY_ID=
87 OSS_ACCESS_KEY_SECRET=
88 OSS_ENDPOINT=
89 OSS_BUCKET_NAME=
90 OSS_FILE_BASE_NAME=
91 ```
92
93 ### 3. 运行数据导入
94
95 ```bash
96 python import_hk_songs.py --help
97 ```
98
99 ### 4. 运行 ETL 同步至爬虫库
100
101 ```bash
102 # 全量同步（支持断点续传）
103 python run_etl.py --resume
104
105 # 冒烟测试（仅前 3 批）
106 python run_etl.py --max-batches 3
107
108 # 指定平台
109 python run_etl.py --platform qq --resume
110 ```
111
112 ### 5. 审计工具
113
114 ```bash
115 # L1 元数据重复审计
116 python audit_hk_songs_duplicates.py
117
118 # L1 应用合并（软删 loser + 作者增量合并）
119 python audit_hk_songs_duplicates.py --apply-merge
120
121 # L2 歌词去重审计（下载 + 比对）
122 python audit_hk_songs_l2.py --phase all --workers 32
123
124 # BPM 分类补全
125 python backfill_bpm_class.py --dry-run
126
127 # 测试表迁移至正式表
128 python migrate_test_to_prod.py --limit 10 --dry-run
129 ```
130
131 ### 6. 运行 L2 歌词去重测试
132
133 小样本验证：
134
135 ```bash
136 RUN_L2_BENCHMARK=1 \
137 L2_BENCHMARK_LIMIT=20 \
138 L2_BENCHMARK_EXISTING_LIMIT=50 \
139 L2_BENCHMARK_TOPKS=20,100 \
140 python -m pytest test_dedup.py::TestL2Benchmark::test_l2_recall_topk_efficiency_and_review_artifacts -q -s
141 ```
142
143 详见 [测试流程指南.md](./测试流程指南.md)。
144
145 ### 7. 启动复核前端
146
147 ```bash
148 python serve_l2_dashboard.py --host 127.0.0.1 --port 8765
149 ```
150
151 然后访问 http://127.0.0.1:8765 查看测试报告、比对歌词、人工标注。
152
153 ## 单元测试
154
155 ```bash
156 # 去重测试
157 python -m pytest test_dedup.py -q
158
159 # ETL 模块测试
160 python -m pytest tests/ -q
161
162 # 审计脚本测试
163 python -m pytest test_audit_hk_songs_duplicates.py -q
164 ```
165
166 ## 注意事项
167
168 - `.env` 文件包含数据库凭据，**不要**提交到仓库。
169 - `output/` 目录存放测试报告和缓存文件，不纳入版本控制。
170 - CSV / SQL / Excel 等数据文件不纳入版本控制。
171 # 词曲 & 音眼资产导入工具
172
3 本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 `hk_songs` 表，并提供 L2 歌词去重测试和人工复核前端。 173 本项目用于将音眼（Hikoon）数据库中的歌词和歌曲数据去重、比对后，导入至词曲库的 `hk_songs` 表，并提供 L2 歌词去重测试和人工复核前端。
4 174
5 ## 项目结构 175 ## 项目结构
......