MuScriptor 在 Python 环境下安装依赖与模型加载的排查指南

MuScriptor 在 Python 环境下完成依赖安装后，import 或加载模型时报错，通常不是单一原因，而是依赖版本、模型文件完整性和环境配置共同作用的结果。建议先按报错阶段分步排查，不要急于重装，否则容易掩盖真实问题。

MuScriptor 的依赖问题多数表现为 torch、transformers 版本冲突，或模型文件缺失/损坏。排查时先区分 import 和加载模型两个阶段，用 pip check 校验依赖，用 os.path.exists 和 torch.load 确认文件完整，再检查 HF_HOME 等缓存目录权限。每一步都需要根据完整 traceback 定位，不要依赖模糊的报错描述。若模型来自 Hugging Face，缓存目录必须可写且有足够空间。

先定位错误发生在import还是模型加载

先运行两个最小命令，把报错阶段分开。以下命令都在项目虚拟环境中执行：

python -c "import muscriptor"

python -c "from muscriptor import load_model; load_model('./models/muscriptor.pt')"

第一条命令只触发模块导入，第二条命令才会真正加载模型。如果第一条报错，说明依赖安装或导入逻辑有问题；如果第二条报错，说明模型文件或加载代码有问题。执行时把完整 traceback 保存下来，重点关注最后几行的错误类型和文件路径。

常见报错与定位方向：

ModuleNotFoundError: No module named 'torch' — 依赖未安装或当前虚拟环境与安装环境不一致。
ImportError: cannot import name 'xxx' from 'transformers' — transformers 版本与 MuScriptor 要求不匹配。
OSError: Unable to load weights from checkpoint — 模型文件不存在、损坏或路径错误。

检查依赖库版本是否冲突

依赖冲突经常出现在 torch、transformers、numpy 这些底层库之间。先运行 pip check，它会列出当前环境中已安装包的依赖冲突：

pip check

如果使用 conda 管理环境，再运行 conda list 查看关键包版本：

conda list torch transformers numpy

然后把结果与项目自带的 requirements.txt 或 environment.yml 逐项比对，确认版本是否满足要求。重点看 torch 和 transformers 是否在指定区间内，numpy 是否与 torch 版本兼容。若发现冲突，建议新建一个干净虚拟环境，按项目文件重新安装，避免手动降级导致其他包被破坏。

验证模型文件路径与权重复原完整性

模型加载失败有时是因为路径写错或下载不完整。用下面的 Python 片段检查文件是否存在和是否能被 torch 读取：

import os
import torch

model_path = './models/muscriptor.pt'
print('文件存在:', os.path.exists(model_path))
if os.path.exists(model_path):
    print('文件大小:', os.path.getsize(model_path), 'bytes')
    try:
        state = torch.load(model_path, map_location='cpu')
        print('加载成功，state_dict keys:', list(state.keys())[:5])
    except Exception as e:
        print('加载失败:', repr(e))

如果文件不存在，先确认相对路径是否正确，建议改成绝对路径再试。如果文件大小为 0 KB，说明下载未完成，需要重新下载。如果 torch.load 抛出 zipfile.BadZipFile 或类似异常，说明文件损坏，同样需要重新获取权重文件。

调整环境变量与缓存目录

当模型由 Hugging Face 的 transformers 下载时，缓存放错位置或权限不足会导致加载失败。可以先设置环境变量，把缓存指向当前用户可写目录：

export HF_HOME=/data/cache/huggingface
export TRANSFORMERS_CACHE=/data/cache/huggingface/transformers

设置后再运行加载命令前，先用 df -h /data/cache 检查该目录所在磁盘的剩余空间，至少保证有足够空间存放模型权重（具体大小取决于模型）。同时确认目录有写权限，否则会在下载或加载阶段报 PermissionError。

写一个最小可运行脚本验证修复效果

为了确保问题真正被解决，写一个最小脚本，只依赖 MuScriptor 的公开入口，不掺入业务代码：

import os
from muscriptor import load_model

model_path = os.environ.get('MUSCRIPTOR_MODEL', './models/muscriptor.pt')
assert os.path.exists(model_path), f'模型文件不存在: {model_path}'

model = load_model(model_path)
print('模型加载成功:', type(model).__name__)

每次修改依赖或环境变量后，都运行 python min_test.py 回归测试。这个脚本只做加载动作，输出成功信息，可以快速暴露加载阶段的问题。如果脚本稳定通过，再回到原有业务代码中运行，能定位到是否为调用方式导致的问题。