Ray并行函数间歇性报ModuleNotFoundError的原因及历史正常运行后突发问题的疑问

这种间歇性的Ray模块找不到问题确实太头疼了——时好时坏、没法稳定复现，排查起来简直摸不着头脑。我来结合Ray的运行时环境机制，给你拆解一下为什么会出现这种情况，以及临时修复的两行代码为什么能生效：

一、为什么之前正常运行近一年，现在突然间歇性出问题？ #

核心原因和Ray的运行时环境缓存机制以及主进程与Worker进程的路径隔离有关：

1. Ray的工作目录缓存变脏：Ray默认会缓存工作目录的内容（通过RAY_RUNTIME_ENV_WORKING_DIR_CACHE_SIZE_GB控制大小），一开始你的缓存是正确的，Worker进程能从缓存里加载到完整的utils包结构。但后来可能因为：
   • 你修改了utils包的内部结构（比如新增模块、修改__init__.py、移动文件），但Ray的缓存没有及时更新；
   • Ray的缓存机制出现了偶发的bug，导致缓存的目录结构和实际本地目录不一致；
     这种情况下，当Worker进程加载旧的脏缓存时，就会出现模块找不到的错误，而什么时候触发加载缓存、什么时候用新目录是随机的，所以错误是间歇性的。
2. py_modules的局限：你之前用runtime_env={'py_modules': [module1]}，这种方式只会把module1这个单个模块序列化传递给Worker，但如果module1依赖utils包内的其他模块（比如package2里的内容），或者Worker进程需要识别utils这个父包的结构（比如模块内有相对导入），仅传递单个模块是不够的。之前正常是因为缓存里刚好包含了完整的包结构，后来缓存失效后，单个模块的序列化就满足不了依赖需求了。
3. 主进程的sys.path修改不传递给Worker：你在主进程里sys.path.insert(0, BASE_DIR)，但Ray的Worker进程是独立启动的子进程，主进程的sys.path修改不会自动同步过去。之前正常是因为缓存或者py_modules的方式刚好补全了路径，后来这些机制失效，Worker的Python路径里就没有mydir，自然找不到utils包。

二、为什么临时修复的两行代码能解决问题？ #

1. os.environ['PYTHONPATH'] = 'C:/some_path/mydir/'：
   环境变量PYTHONPATH是全局的，Ray的Worker进程启动时会继承主进程的环境变量。设置这个后，所有Worker进程的Python路径都会包含mydir，不管缓存或者runtime_env的配置如何，都能直接找到utils包。而你之前主进程的sys.path.insert只是修改了主进程自己的路径，不会传递给Worker，所以没用。
2. os.environ['RAY_RUNTIME_ENV_WORKING_DIR_CACHE_SIZE_GB'] = '0'：
   这行直接禁用了Ray的工作目录缓存，每次Worker进程启动都会重新同步最新的本地目录结构，而不是加载旧的脏缓存。这样就避免了缓存过期导致的路径错误，自然也就不会出现间歇性的模块找不到问题。

三、为什么串行运行完全没问题？ #

串行时所有代码都在同一个主进程里执行，你已经把BASE_DIR加到了主进程的sys.path，Python能正常遍历到utils包的所有模块。而Ray并行时是启动独立的Worker子进程，这些子进程的Python环境是全新初始化的，和主进程的路径配置不共享，所以才会出现主进程能找到、Worker找不到的差异。

更规范的修复建议（替代临时方案） #

其实你不需要硬编码路径或者禁用缓存，正确配置Ray的runtime_env就能解决问题：

ray.init(
    runtime_env={
        # 把整个mydir目录同步给所有Worker，确保包结构完整
        'working_dir': BASE_DIR,
        # 显式设置Worker的PYTHONPATH，强化路径配置
        'env_vars': {
            'PYTHONPATH': BASE_DIR
        }
    },
    num_cpus=4
)

这种方式会同步整个项目目录到Worker，同时确保Worker的Python路径正确，既能避免缓存脏数据的问题（如果缓存正常的话），也能满足模块的依赖需求。

内容来源于stack exchange