README.md



music_analyze_v2

当前项目是一个基于 Excel 批量跑音频标签分析的独立流水线。

实际主流程：


读取输入 xlsx

从指定 URL 列取音频地址
透传部分元数据给音乐分析器
调用 app.middleware.music_analyze.analyze_music(...)

将结果整理成固定交付列并持续写回输出 xlsx

通过已有输出文件和 checkpoint 支持断点续跑


当前批处理入口是 pipeline/batch_analyze_xlsx.py。


当前状态


可直接运行的主入口：pipeline/batch_analyze_xlsx.py

当前默认分析链路：QwenAnalyzer

当前实际可用 provider：qwen

提示词来源：app/prompts/step2_music_decode

输出格式：固定交付列，不保留原始全部输入列


说明：


命令行参数里虽然还保留了 --provider doubao 选项，但当前 factory.py 只实例化 qwen，传 doubao 会在运行时失败。
README 以下内容按“当前代码实际行为”描述，而不是按历史规划描述。


安装

python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env


环境变量

最小必需配置通常是：

QWEN_API_KEY=your_api_key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen3-omni-flash
QWEN_TIMEOUT=15
QWEN_LYRICS_TIMEOUT=90
QWEN_MAX_RETRIES=3


项目还支持以下可选增强能力：


QWEN_DASHSCOPE_API_KEY：部分 DashScope/ASR 路径会用到

SONGFORMER_URL：启用额外音频结构特征

MUSIC_LYRICS_ASR_BACKEND、DASHSCOPE_*：歌词提取相关配置

OSS_*：音频过大时走 OSS 降级上传


配置定义见 app/core/config.py。


输入要求

输入文件必须是 xlsx。

至少需要一列音频地址。脚本按下面顺序解析 URL 列：


显式传入的 --url-column

URL
url
cos访问地址
cos_url
audio_url


若整行 URL 为空：


不会发起分析
该行会被直接跳过
在断点续跑里会被视为已处理


元数据不是必填，但建议提供。脚本会优先识别这些字段：


歌曲ID / song_id / id


tmeid / tmeID / TMEID


歌曲名 / 歌曲名称 / title


表演者 / 歌手 / artist


歌曲时长 / duration


默认会额外透传这些列给模型作为 metadata：


tmeID,歌曲名称,歌曲名,歌手,表演者,版本,词作者,曲作者


可通过 --metadata-columns 覆盖。


快速开始

常规跑批：

python pipeline/batch_analyze_xlsx.py \
  --input 待分析.xlsx \
  --output outputs/标签交付结果.xlsx \
  --url-column URL \
  --provider qwen \
  --workers 3


提取歌词：

python pipeline/batch_analyze_xlsx.py \
  --input 待分析.xlsx \
  --output outputs/标签交付结果.xlsx \
  --url-column URL \
  --provider qwen \
  --workers 3 \
  --extract-lyrics


从头重跑，不复用历史输出或 checkpoint：

python pipeline/batch_analyze_xlsx.py \
  --input 待分析.xlsx \
  --output outputs/标签交付结果.xlsx \
  --provider qwen \
  --no-resume


命令行参数


参数
说明
当前实际行为


--input
输入 Excel 路径
必填


--output
输出 Excel 路径
必填


--checkpoint
checkpoint 文件路径
默认是 <output>.checkpoint.json


--url-column
URL 列名
默认 URL，不存在时会自动 fallback


--provider
分析 provider
参数允许 qwen/doubao，当前实际只应使用 qwen


--extract-lyrics
是否提取歌词
开启后会走带歌词分析路径


--label-level
标签级别

0 或 1


--metadata-columns
额外透传给模型的列
逗号分隔


--workers
并发线程数
默认 3


--checkpoint-every
每处理多少行保存一次
默认 10


--no-resume
禁用断点续跑
默认关闭


输出结构

脚本输出的是固定交付表，不是“原始输入列 + 分析列”的全量回写。

当前输出列定义在 batch_analyze_xlsx.py 的 DEFAULT_OUTPUT_COLUMNS：


tmeid
歌曲ID
歌曲名
表演者
歌曲时长
表演者类型
语种
BPM速度
情绪
网络/抖音歌曲
音乐风格
配器
场景


结果字段映射规则：


表演者类型 <- performer_type 或 vocal_texture


语种 <- language


BPM速度 <- bpm


情绪 <- emotion


网络/抖音歌曲 <- douyin_tags


音乐风格 <- music_style_tags，否则回退到 genre/sub_genre


配器 <- instrument_tags


场景 <- scene


列表型字段会被拼成 、 分隔字符串。


断点续跑

当前断点续跑逻辑比 README 旧版描述更具体，实际行为如下：


如果输出文件已存在，且行数与本次输入一致：
直接按行号复用历史输出
如果输出文件已存在，但行数不一致：
尝试按 歌曲ID 和 tmeid 复用旧结果
如果 checkpoint 存在：
会在“输出按索引对齐”的前提下合并 checkpoint 完成状态
空 URL 行会直接加入 completed 集合
处理中按 --checkpoint-every 周期性落盘

Ctrl+C 时会先保存当前进度，再强制退出避免卡住线程


默认 checkpoint 文件名：

<output>.checkpoint.json


提示词与分析链路

批处理脚本本身不直接读取 prompt 文件，而是走统一分析入口：

pipeline/batch_analyze_xlsx.py
-> app/middleware/music_analyze/__init__.py
-> app/middleware/music_analyze/music_analyzer.py
-> app/middleware/music_analyze/factory.py
-> app/middleware/music_analyze/qwen_analyzer.py
-> app/middleware/music_analyze/prompts.py

当前 prompt 目录固定为：


music_analyze_system_prompt.md
music_analyze_system_prompt_part_a.md
music_analyze_system_prompt_part_b.md
music_analyze_user_prompt.md
music_lyrics_only_prompt.md


项目结构

music_analyze_v2/
├── app/
│   ├── core/
│   │   └── config.py
│   ├── middleware/
│   │   └── music_analyze/
│   │       ├── __init__.py
│   │       ├── base.py
│   │       ├── factory.py
│   │       ├── music_analyzer.py
│   │       ├── prompts.py
│   │       ├── qwen_analyzer.py
│   │       ├── doubao_analyzer.py
│   │       ├── audio_features.py
│   │       └── bpm_analyzer_tools.py
│   ├── prompts/
│   │   └── step2_music_decode/
│   └── utils/
├── pipeline/
│   └── batch_analyze_xlsx.py
├── outputs/
├── requirements.txt
├── .env
├── .env.example
└── README.md


依赖

基础依赖见 requirements.txt。

当前显式包含：


openai
requests
httpx
python-dotenv
pydantic-settings
numpy
scipy
librosa
soundfile
pandas
openpyxl


dashscope 在 requirements.txt 中仍是注释状态；如果你要跑依赖该 SDK 的歌词路径，需要自行安装并校验对应代码分支。


常见问题


为什么传了 --provider doubao 还是失败？

因为当前 CLI 还保留了 doubao 选项，但分析器工厂只支持 qwen。这是代码现状，不是使用方式问题。


输出为什么没有保留原 Excel 的全部列？

因为当前脚本在保存时只写 DEFAULT_OUTPUT_COLUMNS，这是代码的固定行为。


修改提示词应该改哪里？

改 app/prompts/step2_music_decode 下的模板文件即可。


行数变了还能续跑吗？

可以部分复用。脚本会尝试按 歌曲ID 和 tmeid 匹配历史输出。


如何完全重跑？

加 --no-resume，并删除旧输出和旧 checkpoint，最干净。