music_analyze_v2

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

实际主流程：

1. 读取输入 xlsx
2. 从指定 URL 列取音频地址
3. 透传部分元数据给音乐分析器
4. 调用 app.middleware.music_analyze.analyze_music(...)
5. 将结果整理成固定交付列并持续写回输出 xlsx
6. 通过已有输出文件和 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，最干净。