Azure ML多步骤脚本与共享模块项目组织最佳实践问询

问题场景 #

我正在搭建基于Python的Azure ML项目，用main.py构建并触发管道，每个管道步骤对应step_scripts下的独立脚本（step1.py、step2.py等），主脚本和步骤脚本都依赖modules文件夹里的共享函数。期望的项目结构如下：

project
|   main.py
|   
+---modules
|       __init__.py
|       module1.py
|       module2.py
|       
\---step_scripts
        step1.py
        step2.py

但遇到核心问题：Azure会把每个步骤脚本当作主模块执行（此时__name__ == "__main__"），导致步骤脚本无法通过相对导入访问modules里的内容。

已尝试的方案局限 #

1. 调整结构：把步骤脚本和modules同级（主脚本也同级）虽然可行，但不想让主脚本和步骤脚本混在一起；把modules嵌套到step_scripts里又会造成模块冗余。
2. 修改sys.path：这是常见方法，但担心在Azure计算集群运行时出现兼容性问题，且方案本身比较脆弱。

推荐的最佳实践 #

1. 把共享模块做成可安装的本地包（最可靠） #

这是符合Python包规范的最优解，彻底解决导入问题：

• 调整后的项目结构：

project
|   main.py
|   setup.py  # 或用pyproject.toml
|   
+---src
|   +---my_project_modules
|   |       __init__.py
|   |       module1.py
|   |       module2.py
|   |       
|   \---step_scripts
|           step1.py
|           step2.py

• 编写setup.py示例：

from setuptools import setup, find_packages

setup(
    name="my_project_modules",
    version="0.1",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
)

• 本地开发时执行pip install -e .（开发模式，修改模块无需重新安装），Azure运行环境中执行pip install .。之后不管是主脚本还是步骤脚本，都可以直接用绝对导入：from my_project_modules import module1，完全不受执行上下文影响。

2. 动态计算项目根目录（快速适配现有结构） #

如果不想打包模块，可以在每个步骤脚本开头添加一段稳定的路径配置，基于脚本自身的绝对路径推导项目根：

import sys
from pathlib import Path

# 推导项目根目录（假设step_scripts在project下，根目录是当前脚本的父级父目录）
project_root = Path(__file__).parent.parent
sys.path.append(str(project_root))

# 之后正常导入modules
from modules import module1

这种方式比硬编码路径可靠，因为Path(__file__)会获取脚本的真实绝对路径，不管Azure把脚本放在哪个位置执行。

3. 通过Azure ML环境变量统一配置路径 #

可以在Azure ML的运行环境中设置PYTHONPATH，把项目根目录加入Python的搜索路径，无需修改脚本：

• 定义管道步骤时，配置环境变量：

from azureml.core import Environment

# 获取或创建你的运行环境
env = Environment.get(workspace, name="your_environment_name")
# Azure ML默认将项目目录挂载到/azureml-app，把这个路径加入PYTHONPATH
env.environment_variables["PYTHONPATH"] = "$PYTHONPATH:/azureml-app"

# 将该环境关联到每个管道步骤
step1 = PythonScriptStep(
    script_name="step1.py",
    source_directory="./step_scripts",
    environment=env,
    # 其他参数...
)

设置后，所有步骤脚本都可以直接导入modules里的内容，本地运行时只需手动设置PYTHONPATH为项目根目录即可。

方案对比 #

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