一、模型下载速度慢或中断（如 Hugging Face 下载超时）
- 解决办法：
- 使用 Hugging Face 国内镜像：export HF_ENDPOINT=https://hf-mirror.com，再执行下载命令。
- 用git lfs断点续传：git lfs pull（中断后重新执行可继续下载）。
- 使用下载工具（如 wget/curl）带断点续传参数：wget -c 模型文件URL。
- 手动下载模型文件（通过网盘分享），放入~/.cache/huggingface/hub对应目录。
- 配置代理加速（如 Clash 代理，确保终端代理生效：export https_proxy=https://127.0.0.1:7890）。
二、模型文件损坏或校验失败（如 “checkpoint is corrupted”）
- 解决办法：
- 校验文件哈希值（对比模型页面提供的 SHA256 值），不匹配则重新下载。
- 用git lfs fsck检查 LFS 文件完整性，修复损坏文件：git lfs fetch –all。
- 下载时关闭 “快速下载” 或 “压缩传输”，避免文件被篡改。
- 更换浏览器 / 下载工具（如用 aria2 替代浏览器直接下载）。
- 从官方渠道获取模型（如 Hugging Face 官方库、模型作者 GitHub），避免第三方非可信源。
三、模型文件路径错误（如 “FileNotFoundError: model-00001-of-00002.safetensors”）
- 解决办法：
- 检查模型加载路径是否正确（绝对路径优先，如/home/user/models/chatglm3-6b）。
- 确认模型文件完整（分片模型需所有 part 文件齐全，如 00001 到 00002）。
- 解压模型压缩包时保留目录结构（避免文件被解压到混乱路径）。
- 权限设置：chmod -R 755 模型目录，确保程序有权限读取文件。
- 若使用 Windows，避免路径含中文 / 空格（如改为D:/models/chatglm）。
四、多文件模型分片合并失败（如 Stable Diffusion 权重合并报错）
- 解决办法：
- 使用官方合并脚本（如python merge_ckpt.py），确保脚本版本与模型匹配。
- 检查分片文件命名是否规范（如model-00001-of-00003.bin需连续编号）。
- 合并时关闭其他占用内存的程序，避免内存不足导致中断。
- 手动合并（适用于简单分片）：cat model-part-* > model-full.bin（Linux/macOS）。
- 下载已合并的完整模型（若官方提供），跳过手动合并步骤。
五、模型格式不兼容（如 “Unsupported model format: .pth for transformers”）
- 解决办法：
- 确认模型支持的框架（如 PyTorch 模型需用from_pretrained，TensorFlow 模型需用tf.keras.models.load_model）。
- 使用转换工具（如transformers的convert_llama_weights_to_hf.py转换 LLaMA 原生权重）。
- 安装兼容的模型加载库（如sentence-transformers支持特定格式的 embedding 模型）。
- 查找模型的转换教程（如将 Fairseq 模型转为 Hugging Face 格式）。
- 下载对应格式的模型文件（如官网同时提供.bin和.pth版本时选择适配的）。