在Databricks与MLflow环境下为Spark执行器安装Python包失败：cv2模块未找到（ModuleNotFoundError）

遇到这种ModuleNotFoundError太常见了——Spark UDF跑在工作节点的独立Python环境里，和驱动节点的环境完全分离，光在驱动装包根本没用。你之前尝试的addFile方法只适合传递自定义的单个脚本或小型模块，像cv2这种包含大量二进制文件和子模块的复杂第三方库，必须通过集群级的包安装来搞定。下面给你几个自动化、贴合Databricks+MLflow工作流的解决方案：

1. 最推荐：用集群初始化脚本批量安装依赖（长期稳定） #

初始化脚本会在集群启动时自动在所有节点（驱动+工作节点）上执行，完美实现依赖的自动化部署：

• 第一步：写一个bash脚本（比如install_deps.sh），内容如下：

  # 如果你用系统Python
  pip install opencv-python==<你的具体版本号>
  
  # 如果你用Databricks的conda环境（推荐，避免版本冲突）
  # conda install -y opencv-python==<你的具体版本号>
  

• 第二步：把脚本上传到DBFS（比如dbfs:/databricks/scripts/install_deps.sh），可以用Databricks UI或者dbutils.fs.put命令上传
• 第三步：在集群配置的高级选项 > 初始化脚本里添加这个脚本路径，重启集群后，所有节点都会自动安装cv2

2. 贴合MLflow工作流：利用mlflow.pyfunc.spark_udf的环境管理 #

既然你已经用MLflow记录了conda环境，那可以直接让MLflow帮你在工作节点重建环境：

• 训练阶段：确保你的MLflow日志里包含了完整的conda环境，比如训练脚本里指定：

  conda_env = {
      "name": "mlflow-env",
      "channels": ["defaults"],
      "dependencies": [
          "python=3.8",
          "pip",
          {
              "pip": [
                  "mlflow",
                  "opencv-python==<你的版本>",
                  # 其他依赖
              ]
          }
      ]
  }
  
  mlflow.pyfunc.log_model(
      artifact_path="model",
      python_model=your_model,
      conda_env=conda_env
  )
  

• 推理阶段：调用spark_udf时指定env_manager参数，让MLflow自动在工作节点创建环境：

  import mlflow.pyfunc
  
  # 从Model Registry加载模型
  model_uri = "models:/your_model/production"
  spark_udf = mlflow.pyfunc.spark_udf(spark, model_uri, env_manager="conda")
  
  # 然后用这个UDF处理数据
  df.withColumn("prediction", spark_udf(struct(*df.columns))).show()
  

  Databricks会自动把conda环境分发到所有工作节点，不需要手动安装。

3. 笔记本动态安装：用Databricks Libraries API #

如果是临时测试或者不想重启集群，可以在笔记本里用dbutils直接安装到所有节点：

# 安装指定版本的opencv-python
dbutils.library.installPyPI("opencv-python", version="<你的版本>")

# 必须重启Python进程才能让依赖生效
dbutils.library.restartPython()

这个方法会自动把包安装到所有工作节点，重启后整个集群的Python环境就统一了。

为什么你之前的方法失败？ #

• addFile/addPyFile只能传递单个文件或目录，而cv2是一个包含大量二进制文件和子模块的复杂库，光传__init__.py或者根目录根本没用，工作节点还是找不到完整的库文件
• 工作节点的执行器任务确实无法访问Spark上下文，所以即使你在驱动添加了文件，执行器也没法加载这些资源

回应你提到的其他问题 #

• 重启Spark会话：在Databricks笔记本里，不需要重启整个集群，用dbutils.library.restartPython()就能重启当前会话的Python进程，让新安装的依赖生效
• 驱动与执行器环境一致：上面的三个方法都是直接在所有节点安装依赖，从根本上保证了驱动和工作节点的环境一致，不需要手动设置路径

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