1. 这个报错到底在说什么ModuleNotFoundError: No module named models是 PyTorch 加载模型时非常典型的一类错误尤其在你想把别人训练好的.pt/.pth文件拿到自己项目里跑推理的时候。它的核心含义是Python 在反序列化unpickle模型对象时需要重新导入模型定义所在的模块而当前运行环境里找不到名为models的包或模块。很多人第一反应是「我明明装了 PyTorch为什么还找不到模块」其实这个报错跟 PyTorch 本身没关系它来自 Python 的pickle机制。当你用torch.save(model, whole_model.pth)保存整个模型对象时pickle 不会把模型类的代码一起存进去它只记录了这个类「住在哪个文件、哪个包路径下」。加载时Python 会按照记录去sys.path里找那个模块找不到就抛ModuleNotFoundError。所以这个问题的本质是模块导入路径问题不是模型文件损坏也不是版本不兼容。它通常出现在三种场景一是你换了项目目录原来的models/文件夹不在当前工作路径下二是你从 GitHub 下载了别人的推理代码但没把模型定义文件放到对应位置三是你在服务器上跑工作目录和训练时不一致。搞清楚这一点排查方向就明确了让 Python 能找到那个models模块。2. 先理清目录结构和导入路径在动手改代码之前我建议先把项目目录画出来因为 90% 的这类报错都能从目录结构上看出来。假设你训练时的项目长这样project_train/ ├── train.py ├── models/ │ ├── __init__.py │ ├── common.py │ └── yolo.py └── weights/ └── best.pt训练脚本里可能是from models.yolo import Model保存整个模型后pickle 里记录的类路径就是models.yolo.Model。现在你换到推理项目project_infer/ ├── detect.py └── weights/ └── best.ptdetect.py里执行torch.load(weights/best.pt)Python 会去找models.yolo这个模块但project_infer/下根本没有models/文件夹于是报错。解决办法有两种思路要么把models/目录补回来要么让sys.path指向那个目录。先确认当前 Python 到底能看到哪些路径运行这段代码import sys for p in sys.path: print(p)sys.path是 Python 搜索模块的路径列表第一个元素通常是脚本所在目录或当前工作目录。如果你发现models/的父目录不在这个列表里那就是问题所在。另外可以用os.getcwd()确认当前工作目录很多时候你在终端里cd到了别的目录导致相对路径失效。注意sys.path里的路径顺序很重要Python 按顺序查找找到第一个匹配就停止。如果存在同名模块可能加载到错误的那个。3. 用 TaoToken 统一 Key 管理排查工具排查这类问题经常需要借助 AI 辅助工具来分析报错栈、生成修复代码或者让模型帮你解读 pickle 的模块依赖。如果你同时用好几个 AI 工具每个都要单独配 Key、单独记额度管理起来很乱。我自己的做法是用 TaoToken 做统一的 Key 和 API 通道管理一个 Key 走多个模型排查时切换工具不用反复改配置。TaoToken 的定位是统一的大模型 API 接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它适合需要长期做 AI 辅助编码、Agent 调试的开发者尤其是你会在多个项目间切换、又不想每个项目都维护一套 Key 的场景。配置方式很简单以环境变量为例把 Key 写进去export TAOTOKEN_API_KEY你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Python 里用 OpenAI 兼容的 SDK 调用from openai import OpenAI import os client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[ {role: user, content: 解释这个报错ModuleNotFoundError: No module named models} ], ) print(resp.choices[0].message.content)这样你在排查 PyTorch 报错时可以把完整的 traceback 贴给模型让它帮你判断是路径问题还是保存方式问题。Key 的创建在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。如果你主要做长期编码和 Agent 任务可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。需要说明的是TaoToken 在这里的角色是帮你管理 AI 辅助排查的通道它不参与 PyTorch 的模型加载过程也不会替你修sys.path。真正解决报错还是要靠下面的路径修复手段。4. 可复制的修复配置修复的核心是让 Python 能找到models模块。下面给出几种可复制的方案按推荐程度排序。方案一把models/目录补到推理项目里这是最直接的做法。从训练项目里把整个models/文件夹复制过来确保里面有__init__.pyproject_infer/ ├── detect.py ├── models/ │ ├── __init__.py │ ├── common.py │ └── yolo.py └── weights/ └── best.pt__init__.py可以是空文件它的作用是让 Python 把models当成一个包。复制完直接跑detect.py多数情况下报错就消失了。方案二用sys.path.insert动态添加路径如果models/在别的目录不想复制可以在加载模型前把它的父目录插进sys.pathimport sys import os import torch # 假设 models 目录在 /home/user/project_train 下 MODEL_ROOT /home/user/project_train if MODEL_ROOT not in sys.path: sys.path.insert(0, MODEL_ROOT) # 现在可以正常加载了 ckpt torch.load(weights/best.pt, map_locationcpu) model ckpt[model] if isinstance(ckpt, dict) else ckpt model.eval()用insert(0, ...)是为了让这个路径优先被搜索避免被其他同名模块干扰。加if ... not in sys.path判断是防止重复插入。方案三改用state_dict方式重新保存如果你能拿到原始模型定义最干净的做法是不要加载整个模型而是只加载权重。先用原始项目把整个模型转成state_dictimport torch from models.yolo import Model # 在原始项目环境下执行 model torch.load(weights/best.pt, map_locationcpu) if hasattr(model, module): model model.module torch.save(model.state_dict(), weights/best_state_dict.pth)之后在推理项目里只要你有同样的模型类定义就可以from models.yolo import Model import torch model Model(cfgmodels/yolov5s.yaml) model.load_state_dict(torch.load(weights/best_state_dict.pth, map_locationcpu)) model.eval()state_dict只存参数张量不存类路径所以不会有模块导入问题。这也是 PyTorch 官方推荐的保存方式。方案四用 TorchScript 固化模型如果不想依赖任何 Python 模块定义可以用torch.jit.trace把模型转成 TorchScriptimport torch model torch.load(weights/best.pt, map_locationcpu) model.eval() example torch.rand(1, 3, 640, 640) traced torch.jit.trace(model, example) torch.jit.save(traced, weights/model.tjm)加载时import torch model torch.jit.load(weights/model.tjm) model.eval()TorchScript 把计算图序列化不再依赖原始类文件跨项目迁移最省心代价是动态控制流可能不被支持。5. 验证导入是否成功改完配置别急着跑完整推理先用几行代码验证模块能不能导入、模型能不能加载。这样能把问题范围缩小。第一步验证models模块可导入import importlib try: m importlib.import_module(models) print(models 导入成功路径, m.__file__) except ModuleNotFoundError as e: print(仍然找不到 models, e)如果这里就失败说明sys.path还是不对回到第 4 节检查路径。第二步验证模型文件能反序列化import torch try: ckpt torch.load(weights/best.pt, map_locationcpu) print(加载成功类型, type(ckpt)) except ModuleNotFoundError as e: print(反序列化失败, e)第三步验证模型能前向推理import torch model torch.load(weights/best.pt, map_locationcpu) model.eval() with torch.no_grad(): out model(torch.rand(1, 3, 640, 640)) print(输出形状, out.shape if hasattr(out, shape) else type(out))三步都通过说明报错彻底解决。如果第二步还报No module named models可以用pickletools看看文件里到底记录了哪些模块import pickletools with open(weights/best.pt, rb) as f: data f.read() pickletools.dis(data[:2000])输出里会看到类似GLOBAL models.yolo Model的记录这就是 pickle 依赖的模块路径对照它去补目录或改sys.path就行。6. 常见错排查清单排查过程中有几个坑特别容易踩我列出来对照检查。第一个坑是__init__.py缺失。Python 3 虽然支持命名空间包但很多老项目依赖显式__init__.py缺了它import models可能失败。补一个空文件即可。第二个坑是工作目录不对。你在终端里cd到了project_infer/但脚本里用的是相对路径models/而sys.path[0]是脚本所在目录不是当前工作目录。用os.path.dirname(os.path.abspath(__file__))拿到脚本目录再拼接路径更稳。第三个坑是模块名冲突。你本地有个models.py文件和要导入的models包同名Python 优先加载了文件而不是包。用importlib.import_module(models).__file__确认实际加载的是哪个。第四个坑是保存时用了torch.save(model, path)但加载时环境 Python 版本不同。pickle 对版本敏感跨版本可能报各种导入错误。这种情况建议回到原始环境转成state_dict或 TorchScript。第五个坑是map_location没设。在 CPU 机器上加载 GPU 保存的模型会报设备相关错误虽然不一定是ModuleNotFoundError但排查时容易混淆。加载时统一加map_locationcpu或map_locationdevice。第六个坑是路径里有中文或空格。sys.path插入含空格路径时某些环境下导入会失败。尽量用纯英文无空格路径。如果你在排查时想让 AI 帮你分析 traceback可以把完整报错贴到模型对话里用 TaoToken 统一 Key 调用省去多工具切换的麻烦。接入方式参考文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 管理。长期做编码和 Agent 调试的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 会更顺手。最后提醒一句torch.save(model, path)这种保存整个模型的方式官方文档里明确不推荐用于长期存储和跨项目迁移因为它把类路径和目录结构绑死了。养成用state_dict的习惯这类ModuleNotFoundError基本就不会再找上门。