Python YOLO打包exe后模型加载失败如何解决？

Question

在使用Python开发基于YOLO的目标检测应用并尝试将其打包为exe文件（如使用PyInstaller）时，常常遇到“模型加载失败”的问题。典型表现为程序运行时报错：`Unable to find weights file`或`model not found`等。此问题多由资源路径处理不当引起。由于exe环境中相对路径与开发环境不同，导致模型权重文件（如`yolov5s.pt`）无法正确加载。解决方法包括：1）在代码中使用`sys._MEIPASS`判断打包后的资源路径；2）将模型文件放置在正确目录，并通过绝对路径加载；3）配置PyInstaller的`--add-data`参数确保模型文件被正确打包。正确处理资源路径是解决问题的关键。

Answer 1

一、问题背景与常见表现

在使用Python开发基于YOLO的目标检测应用并尝试将其打包为exe文件时，开发者常常会遇到“模型加载失败”的问题。典型表现为程序运行时报错：Unable to find weights file 或 model not found 等。

此类问题多由资源路径处理不当引起。由于PyInstaller打包后的exe环境与开发环境的相对路径机制不同，导致原本在开发环境中正常工作的模型权重文件（如yolov5s.pt）无法正确加载。

二、问题分析：为何路径出错？

在开发阶段，我们通常使用相对路径来引用模型文件，例如：

model = torch.load('weights/yolov5s.pt')

但在打包成exe后，程序的工作目录发生变化，或资源未被正确包含进打包后的目录结构中，从而导致路径失效。

以下是几个关键因素：

• 打包工具不会自动将非代码资源（如模型文件）包含进去
• 开发环境和exe运行环境的当前工作目录不一致
• 未正确使用 PyInstaller 提供的临时资源访问机制

三、解决方案详解

解决该问题的核心在于：**正确识别exe运行时的资源路径，并确保模型文件被打包进可执行文件中**。以下是三种主流解决方案：

1. 使用 sys._MEIPASS 获取打包后的资源路径

PyInstaller 在运行时会将资源解压到一个临时目录，并通过 sys._MEIPASS 暴露该路径。我们可以据此动态构造模型文件的路径：

import sys
import os

if getattr(sys, 'frozen', False):
    # 打包后的路径
    base_path = sys._MEIPASS
else:
    # 开发环境路径
    base_path = os.path.dirname(__file__)

model_path = os.path.join(base_path, 'weights', 'yolov5s.pt')
model = torch.load(model_path)
    

2. 将模型文件放置在正确目录并通过绝对路径加载

可以将模型文件放在与可执行文件同一目录下，然后使用如下方式构建路径：

base_dir = os.path.dirname(sys.executable)  # exe所在目录
model_path = os.path.join(base_dir, 'weights', 'yolov5s.pt')
    

这种方式简单有效，但要求用户在部署时手动维护模型文件的位置。

3. 配置 PyInstaller 的 --add-data 参数

为了让模型文件被打包进exe中，需要在打包命令中加入资源文件：

pyinstaller --add-data "weights;yolov5/weights" main.py

其中，“weights”是本地路径，“yolov5/weights”是打包后的目标路径。

四、流程图展示

graph TD
            A[开始] --> B{是否已打包?}
            B -->|否| C[使用相对路径加载模型]
            B -->|是| D[判断资源路径]
            D --> E[使用 sys._MEIPASS 构建路径]
            E --> F[加载模型成功]
            D --> G[或使用 sys.executable 构建路径]
            G --> H[加载模型成功]

五、总结性建议与最佳实践

为避免“模型加载失败”问题，建议开发者遵循以下最佳实践：

建议项	说明
统一路径管理	封装路径处理逻辑，避免硬编码路径字符串
使用 add-data 参数	确保模型文件等资源被正确打包进exe
测试不同环境	在开发环境和打包环境都进行测试，验证路径有效性
日志输出路径	打印加载路径信息，便于调试
异常处理	捕获模型加载异常，提升用户体验