环境配置与依赖安装
本页系统性地介绍 bytedance/piano_transcription 仓库的环境装配机制：Python 运行时与 PyTorch 基线、requirements.txt 中的固定版本训练依赖、cog.yaml 声明的系统级依赖与容器化推理环境，以及三条可独立使用的装配路径（pip 推理包 / 从零训练 / Cog 容器）。
目的与范围
本页覆盖：
- 训练路径的环境基线：Python 3.7 + PyTorch 1.4.0（
README.md声明的开发环境） requirements.txt中全部 9 个 Python 依赖的版本与用途cog.yaml声明的系统包（ffmpeg、timidity、libsndfile1-dev 等）、容器 Python 版本与容器专属 Python 包- 三条环境装配路径的完整控制流与决策依据
- 硬件资源要求（GPU 显存、数据集磁盘占用、训练时长）
- 常见环境失败模式（GPU OOM、torch 缺失、版本兼容性）与规避方法
本页不覆盖（留给兄弟页面）：
- 转录模型的网络结构与训练算法 —— 属于模型训练主题页面
- 推理包
piano_transcription_inference的完整 API 用法 —— 属于推理使用主题页面 - MAESTRO 数据集的内容与评测指标口径 —— 属于数据准备与评估主题页面
本文档所有结论均来自仓库实际文件：README.md、requirements.txt、runme.sh、cog.yaml、predict.py。
概述
piano_transcription 是字节跳动提出的高分辨率钢琴转录系统（音频 → MIDI）的 PyTorch 实现。仓库在同一代码基线上同时支持两种差异极大的运行环境：
- 从零训练环境：面向希望复现论文结果的研究者，需要下载 121.8 GB 的 MAESTRO V2.0.0 数据集、具备约 29 GB 显存的 GPU，并使用
requirements.txt固定的 9 个科学计算依赖（不含 PyTorch 本体，需另行安装）。 - 容器化推理环境：面向 Replicate 平台部署，由
cog.yaml完整声明，包括 GPU 启用、5 个 apt 系统包、Python 3.8 运行时以及含torch==1.8.0在内的更完整 Python 包集合。
此外，仓库还推荐一条零克隆快捷路径：直接 pip install piano_transcription_inference 安装独立推理包，无需本仓库代码即可完成推理。这条路径的环境要求由推理包自身解决，是官方文档中标注的"最简单方式"。
这种多路径设计的原因在于：训练需要重量级的数据工程依赖（h5py 打包、pandas 解析元数据、mir_eval 评估），而推理只需要模型前向计算与音频 I/O；将推理封装为独立 pip 包后，普通用户的环境装配成本从"克隆仓库 + 配置数据集 + 下载 121.8 GB"降低为"一条 pip 命令"。
架构：环境的分层模型
整个环境可以划分为五个层次：应用入口层、Python 包层、运行时层、系统层、数据与模型层。不同装配路径激活不同层次的子集：
分层解读：
- 应用层：
pytorch/main.py（训练）与pytorch/inference.py（本地推理）是runme.sh中被逐行调用的两个入口；predict.py:Predictor则是 Cog 平台的钩子类。它们决定了对下层依赖的实际需求面。 - Python 包层：
requirements.txt只服务训练/评估链路。注意该文件不包含 PyTorch，PyTorch 需按 README 声明的 1.4.0 基线单独安装。 - 运行时层：两条基线并存 —— README 的 Python 3.7 + PyTorch 1.4.0，与 cog.yaml 的 Python 3.8 + torch==1.8.0。README 明确说明"应该可以在其他版本上工作，但未充分测试"。
- 系统层：仅在容器路径中由
cog.yaml显式声明（如 libsndfile1-dev 提供音频文件 I/O、ffmpeg/timidity 服务音视频与 MIDI 合成链路）；手工部署训练环境时这些库以隐式方式存在于多数 Linux 发行版中。 - 数据与模型层：训练路径依赖 MAESTRO 数据集与 GPU 显存；推理路径依赖 Zenodo 上的预训练 checkpoint。
核心流程：三条装配路径
用户应根据目标（推理 or 训练）选择不同路径。下面的流程图展示完整决策过程：
路径一：独立推理包（官方推荐的"最简"方式）
README 明确指出这是转录新钢琴录音最简单的方式——无需克隆本仓库：
pip install piano_transcription_inferenceSource: README.md
安装后可直接使用（README 中给出的最小示例，仓库原文代码）：
1from piano_transcription_inference import PianoTranscription, sample_rate, load_audio
2
3# Load audio
4(audio, _) = load_audio('resources/cut_liszt.mp3', sr=sample_rate, mono=True)
5
6# Transcriptor
7transcriptor = PianoTranscription(device='cuda') # 'cuda' | 'cpu'
8
9# Transcribe and write out to MIDI file
10transcribed_dict = transcriptor.transcribe(audio, 'cut_liszt.mid')Source: README.md
设计意图：推理包把"环境装配"压缩为一次 pip 安装，将 checkpoint 下载、音频重采样等细节封装在包内部，避免普通用户接触训练代码库的复杂依赖图。
路径二：本仓库训练/推理路径
第一步，安装 requirements.txt 声明的依赖（README 环境章节原文命令）：
pip install -r requirements.txtSource: README.md
requirements.txt 全文如下（9 个包，全部为精确版本固定）：
1h5py==2.10.0
2pandas==1.1.2
3librosa==0.6.0
4numba==0.48
5mido==1.2.9
6mir_eval==0.5
7matplotlib==3.0.3
8torchlibrosa==0.0.4
9sox==1.4.0Source: requirements.txt
关键陷阱：该文件不包含 torch。 PyTorch 必须按 README 声明的 Python 3.7 + PyTorch 1.4.0 基线单独安装（例如按 CUDA 版本从 PyTorch 官方渠道安装对应的 1.4.0 wheel）。漏装 torch 会导致后续 python3 pytorch/main.py 直接失败。
若仅做本地推理，runme.sh 开头两行展示了预训练 checkpoint 的获取与调用方式：
1CHECKPOINT_PATH="CRNN_note_F1=0.9677_pedal_F1=0.9186.pth"
2wget -O $CHECKPOINT_PATH "https://zenodo.org/record/4034264/files/CRNN_note_F1%3D0.9677_pedal_F1%3D0.9186.pth?download=1"
3MODEL_TYPE="Note_pedal"
4python3 pytorch/inference.py --model_type=$MODEL_TYPE --checkpoint_path=$CHECKPOINT_PATH --audio_path='resources/cut_liszt.mp3' --cudaSource: runme.sh
若从零训练，还需在安装依赖之后完成数据集与工作目录配置（runme.sh 训练段）：
1# MAESTRO dataset directory. Users need to download MAESTRO dataset into this folder.
2DATASET_DIR="./datasets/maestro/dataset_root"
3
4# Modify to your workspace
5WORKSPACE="./workspaces/piano_transcription"
6
7# Pack audio files to hdf5 format for training
8python3 utils/features.py pack_maestro_dataset_to_hdf5 --dataset_dir=$DATASET_DIR --workspace=$WORKSPACESource: runme.sh
注意依赖链顺序：必须先下载数据集到 DATASET_DIR，再执行 pack_maestro_dataset_to_hdf5（该步骤依赖 h5py），之后才能进入训练命令。
路径三：Cog 容器路径（Replicate 云端部署）
cog.yaml 是容器环境的唯一声明文件，其构建阶段配置如下：
1build:
2 gpu: true
3
4 system_packages:
5 - "libgl1-mesa-glx"
6 - "libglib2.0-0"
7 - "libsndfile1-dev"
8 - "ffmpeg"
9 - "timidity"
10
11 python_version: "3.8"
12
13 python_packages:
14 - "torch==1.8.0"
15 - "torchvision==0.9.0"
16 - "piano_transcription_inference==0.0.5"
17 - "librosa==0.6.0"
18 - "h5py==2.10.0"
19 - "pandas==1.1.2"
20 - "librosa==0.6.0"
21 - "numba==0.48"
22 - "mido==1.2.9"
23 - "mir_eval==0.5"
24 - "matplotlib==3.0.3"
25 - "torchlibrosa==0.0.4"
26 - "sox==1.4.0"
27 - "tqdm==4.62.3"
28 - "pretty_midi==0.2.9"
29 - "synthviz==0.0.2"
30
31 run:
32 - "ffmpeg -version"
33
34predict: "predict.py:Predictor"Source: cog.yaml
要点解读：
gpu: true：容器必须运行在 GPU 机器上，与predict.py中device="cuda"硬编码一致。run段执行ffmpeg -version：这是一次构建期自检，用于验证 ffmpeg 已正确安装且可执行，若系统包缺失会在构建阶段提前失败，而不是等到运行期。librosa==0.6.0出现两次：这是仓库源文件中真实存在的重复声明（对 pip 而言幂等，无害）。- 容器 Python 包 ⊋ requirements.txt：容器额外引入
torch/torchvision（训练路径要求用户自行安装的部分）、piano_transcription_inference==0.0.5（推理包）、tqdm、pretty_midi、synthviz（predict.py用其生成可视化视频）。
容器环境装配完成后的运行期入口为 predict.py，其 setup() 与 predict() 清晰展示了环境资源如何被消费：
1class Predictor(cog.Predictor):
2 transcriptor: PianoTranscription
3
4 def setup(self):
5 self.transcriptor = PianoTranscription(
6 device="cuda", checkpoint_path="./model.pth"
7 )
8
9 @cog.input("audio_input", type=Path, help="Input audio file")
10 def predict(self, audio_input):
11 midi_intermediate_filename = "transcription.mid"
12 video_filename = os.path.join(Path.cwd(), "output.mp4")
13 audio, _ = librosa.core.load(str(audio_input), sr=sample_rate)
14 # Transcribe audio
15 self.transcriptor.transcribe(audio, midi_intermediate_filename)
16
17 # 'Visualization' output option
18 create_video(
19 input_midi=midi_intermediate_filename, video_filename=video_filename
20 )
21 print(
22 f"Created video of size {os.path.getsize(video_filename)} bytes at path {video_filename}"
23 )
24 # Return path to video
25 return Path(video_filename)Source: predict.py
该文件同时揭示了容器系统包的用途映射：librosa.core.load 读取任意格式音频（背后依赖 libsndfile1-dev），create_video（synthviz）渲染 MIDI 可视化视频，timidity/ffmpeg 支撑 MIDI→音频→视频的合成链路。
依赖清单详解
requirements.txt 依赖（训练/评估路径）
| 包名 | 版本固定 | 用途（依据于仓库代码的调用链路） |
|---|---|---|
h5py | 2.10.0 | 训练前将 MAESTRO 音频打包为 hdf5（utils/features.py pack_maestro_dataset_to_hdf5），实现随机访问训练片段 |
pandas | 1.1.2 | 解析 maestro-v2.0.0.csv 元数据以切分 train/validation/test |
librosa | 0.6.0 | 音频加载、重采样、特征提取（配合 torchlibrosa） |
numba | 0.48 | librosa 0.6.0 的 JIT 加速依赖（音频重采样等计算） |
mido | 1.2.9 | MIDI 文件读写，用于训练标签与推理输出 |
mir_eval | 0.5 | 训练/评估时计算 onset/offset/frame F1 等指标 |
matplotlib | 3.0.3 | 绘制训练统计曲线与转录结果可视化 |
torchlibrosa | 0.0.4 | 提供基于 PyTorch 的 stft/mel 滤波组等音频特征算子 |
sox | 1.4.0 | 音频格式转换/处理 |
torch | 未包含 | 必须按 README 基线（PyTorch 1.4.0）单独安装 |
Source: requirements.txt、runme.sh、README.md
cog.yaml 容器依赖（推理部署路径）
| 依赖 | 类型 | 版本/取值 | 用途 |
|---|---|---|---|
gpu | 构建标志 | true | 强制 GPU 运行时，支撑 predict.py 中 device="cuda" |
libgl1-mesa-glx | apt 系统包 | — | matplotlib/OpenCV 类库所需的 OpenGL 库 |
libglib2.0-0 | apt 系统包 | — | GObject 库，常见于图像/视频处理依赖链 |
libsndfile1-dev | apt 系统包 | — | libsndfile 头文件与库，librosa 读取 wav/flac 等 |
ffmpeg | apt 系统包 | — | 音视频处理，synthviz 生成可视化视频所需 |
timidity | apt 系统包 | — | MIDI 合成播放器，MIDI→音频合成链路 |
| Python | 运行时 | 3.8 | 容器 Python 基线 |
torch / torchvision | Python 包 | 1.8.0 / 0.9.0 | 容器内 PyTorch 基线（注意与训练基线 1.4.0 不同） |
piano_transcription_inference | Python 包 | 0.0.5 | 官方推理包，predict.py 导入 PianoTranscription |
tqdm | Python 包 | 4.62.3 | 进度条 |
pretty_midi | Python 包 | 0.2.9 | MIDI 处理，服务于 synthviz 可视化 |
synthviz | Python 包 | 0.0.2 | 由 MIDI 生成钢琴演奏可视化视频 |
| 其余 8 个包 | Python 包 | 与 requirements.txt 相同 | 与训练路径保持版本对齐 |
Source: cog.yaml
硬件与数据资源需求
| 资源 | 要求 | 出处 |
|---|---|---|
| GPU 显存 | 训练共需约 29 GB（batch_size=12，可用更小 batch 或多卡缓解） | README 训练章节 |
| 参考训练硬件 | 单张 Tesla-V100-PCIE-32GB | README Results 章节 |
| 训练时长 | 300k iterations，约一周 | README Results 章节 |
| 数据集磁盘 | MAESTRO V2.0.0 共 121.8 GB（train 97.7 GB / valid 11.8 GB / test 12.4 GB） | README 数据统计表 |
| 推理 | 无强制 GPU 要求（device='cuda' 与 'cpu' 均可） | README 推理示例 |
环境装配时序：以 Cog 容器为例
下图展示从 cog.yaml 构建到一次完整推理请求的时序，说明各依赖在何时被消费：
设计意图：setup() 在模型服务生命周期中只执行一次，把 checkpoint 加载这种重操作放在请求循环之外；predict() 只做音频加载、转录、视频合成三步，依赖均来自构建期声明，保证运行期环境可复现。
故障模式、边界情况与并发
以下均直接来自仓库内的显式提示或可从源码推得：
1. GPU 显存不足（OOM）
README 的 FAQ 只写了一条："If users met running out of GPU memory error, then try to reduce batch size." 训练命令中 --batch_size=12 对应约 29 GB 显存，线性外推可在更小显存卡上通过降低该值完成训练；runme.sh 中同时建议使用多 GPU 卡。这是本仓库唯一官方给出的故障排查建议。
Source: README.md
2. 漏装 PyTorch
requirements.txt 不含 torch。执行 pip install -r requirements.txt 后直接运行 pytorch/main.py 会因缺少 PyTorch 而失败。需先按 Python 3.7 + PyTorch 1.4.0 基线手动安装 torch（含匹配的 CUDA 版本）。
3. 版本兼容性边界
README 明确表述："This codebase is developed with Python 3.7 and PyTorch 1.4.0 (Should work with other versions, but not fully tested)"。即其他版本属于未承诺的边界。特别注意仓库自身就存在两条不同基线（1.4.0 训练 / 1.8.0 容器），说明代码可跨越该版本区间工作，但复现论文指标应以 1.4.0 为准。
Source: README.md
4. numba 与 numpy 的隐性版本约束
numba==0.48 与 librosa==0.6.0 是 2020 年代早期的组合，对 numpy 版本有上限要求（numba 0.48 不支持较新的 numpy 2.x）。在新机器上若先装了较新 numpy，pip install -r requirements.txt 的解析可能失败或运行期报错。建议在干净虚拟环境中安装，让 pip 按固定版本自洽解析。
5. 数据集路径必须先于打包步骤存在
runme.sh 的注释明确要求数据集先下载到 DATASET_DIR（./datasets/maestro/dataset_root），且目录结构必须符合 README 描述的 dataset_root/2004/.../maestro-v2.0.0.csv 布局，pack_maestro_dataset_to_hdf5 才能成功。路径错误时该步骤会在读取 csv/音频阶段失败。
6. 容器中 checkpoint 路径是约定而非自动下载
predict.py 的 setup() 硬编码 checkpoint_path="./model.pth"，cog.yaml 并不下载它 —— 该文件需由部署流程放置在容器工作目录。这与 runme.sh 中用 wget 从 Zenodo 显式下载的做法是两种不同的供给方式。
性能与运维注意
- 训练吞吐：README 显示单卡 V100 上 300k iterations 耗时约一周，一次完整训练的
Train time单次达 8953.815 s 量级（含验证 93.683 s），规划实验预算时应以"天"为单位。 - 磁盘规划：除 121.8 GB 原始数据外，打包为 hdf5 与 workspace（checkpoints、statistics）还需要额外磁盘空间。
- 训练可恢复性：
runme.sh训练命令提供--resume_iteration=0参数，配合--reduce_iteration=10000，可在中断后从 checkpoint 续训，降低长训练周期的环境风险。 - 推理 CPU/GPU 弹性：推理路径允许
device='cuda' | 'cpu'，本地轻量使用时无 GPU 也可运行（README 推理示例注释）。 - 容器构建期自检：
run: ffmpeg -version把常见系统依赖故障前移到构建阶段，属于低成本高收益的运维设计。
扩展点
- 更换推理后端：
predict.py通过device="cuda"参数化设备选择，改成"cpu"即可去掉 GPU 依赖（需同步调整 cog.yaml 的gpu: true）。 - 更换 checkpoint：
PianoTranscription(checkpoint_path=...)与pytorch/inference.py --checkpoint_path=均暴露了模型文件路径，可用自行训练合并出的CRNN_note_F1=0.9677_pedal_F1=0.9186.pth（经combine_note_and_pedal_models.py产出）替换 Zenodo 版本。 - 容器包集合调整：cog.yaml 的
python_packages是纯声明式的，新增依赖只需追加条目；同理可调整python_version以适配新 torch 版本。 - 数据集切换：训练链路以
--dataset_dir与--workspace为注入点（见runme.sh），理论上可指向任何遵循 MAESTRO 目录约定的本地路径。
相关链接
- 仓库主文档（环境章节原文）：README.md
- 依赖清单：requirements.txt
- 完整训练/推理命令脚本：runme.sh
- 容器环境声明：cog.yaml
- Cog 推理入口：predict.py
- 官方独立推理包：qiuqiangkong/piano_transcription_inference
- MAESTRO 数据集下载：magenta.tensorflow.org/datasets/maestro
- 预训练 checkpoint（Zenodo）：record/4034264