如何解决Python脚本调用子模块时的相对模块导入错误？

问题场景 #

项目结构：

├── samples/
├── scripts/
│   └── script.py  # 原有导入：from ai_model import AiModel
├── model/  # Git子模块，分支main
    ├── models/  # 已含__init__.py
    │   ├── base_model.py
    │   └── ai_model.py  # 含相对导入：from .base_model import BaseModel
    ├── util/  # 已含__init__.py
    └── data/  # 已含__init__.py

在scripts/目录执行script.py时，通过添加models/和model/目录到sys.path尝试解决导入，但出现报错：

Traceback (most recent call last):
  File "C:\Users\example\Project\scripts\script.py", line 9, in <module>
    from ai_model import AiModel
  File "C:\Users\example\Project\model\models\ai_model.py", line 6, in <module>
    from .base_model import BaseModel
ImportError: attempted relative import with no known parent package

解决方案 #

核心思路：让Python识别完整的包结构，而非单独导入子目录，这样子模块内的相对导入能找到父包上下文。

1. 添加项目根目录的__init__.py
   在包含samples/、scripts/、model/的项目根目录下创建空的__init__.py，使整个项目成为可识别的Python包。

2. 修改script.py的路径配置
   仅将项目根目录添加到sys.path，替换原有多目录添加代码：

import sys
from pathlib import Path

# 获取项目根目录（scripts目录的父级）
project_root = Path(__file__).parent.parent.resolve()
sys.path.insert(0, str(project_root))

3. 修改script.py的导入语句
   使用绝对导入从完整包路径导入目标类：

from model.models.ai_model import AiModel

原理说明 #

之前直接将model/models/加入sys.path，会让ai_model.py被当作顶层独立模块执行，失去models包的上下文，导致相对导入from .base_model...找不到父包。将项目根目录加入sys.path后，Python能识别model.models作为完整包结构，子模块内的相对导入即可正常解析。

内容的提问来源于stack exchange，提问作者rbaleksandar