使用databricks-connect连接11.3 LTS集群无法导入已安装模块

问题描述 #

从Databricks Runtime 10.4 LTS升级到11.3 LTS后，databricks-connect能正常连接集群，但无法加载集群上已安装的对应版本模块：

• 创建11.3 LTS版本新集群；
• 通过集群配置“库”标签，用PyPI安装pandas==1.5.3；
• 集群及模块安装完成后，运行以下databricks-connect代码：

def test_map(s):
    import pandas as pd

    return pd.__version__


test_rdd = spark.sparkContext.parallelize(["test"])
test_rdd.map(test_map).collect()

返回结果为['1.3.4']，但预期应为['1.5.3']；同一集群的Databricks笔记本运行相同代码，结果符合预期。

在10.4 LTS集群执行相同步骤，databricks-connect和笔记本均返回['1.5.3']。若在11.3 LTS集群安装默认运行时未包含的模块（如openpyxl），databricks-connect导入会触发ModuleNotFoundError: No module named 'openpyxl'，但笔记本可正常导入。

连接10.4 LTS使用databricks-connect==10.4.22，连接11.3 LTS使用databricks-connect==11.3.10。

问题根源 #

通过对比databricks-connect和笔记本的Python环境路径，发现11.3 LTS下两者使用不同环境：

11.3 LTS开始，集群默认启用库隔离特性，笔记本会自动使用集群库的隔离Python环境，而databricks-connect仍调用集群全局Python环境，导致无法读取安装在隔离环境中的模块。

解决方案 #

1. 禁用集群库隔离（临时快速方案） #

在集群的高级选项 > Spark > Spark配置中添加以下配置，强制集群使用全局Python环境，消除环境差异：

spark.databricks.libraryIsolation.enabled false

重启集群后，databricks-connect即可正常加载集群安装的模块。但此方案会禁用集群库的版本隔离能力，不适合需要多版本依赖共存的场景。

2. 显式加载集群隔离环境的包路径（推荐） #

在本地代码中手动添加集群隔离环境的site-packages路径，让databricks-connect能读取到安装的模块：

• 首先在Databricks笔记本中运行以下代码，获取隔离环境的包路径：

import sys
print([p for p in sys.path if 'cluster_libraries' in p])

典型输出类似：['/local_disk0/.ephemeral_nfs/cluster_libraries/python/lib/python3.9/site-packages']

• 在本地databricks-connect代码的开头添加路径导入：

import sys
sys.path.append("/local_disk0/.ephemeral_nfs/cluster_libraries/python/lib/python3.9/site-packages")

也可以通过终端环境变量全局配置：

export PYTHONPATH="/local_disk0/.ephemeral_nfs/cluster_libraries/python/lib/python3.9/site-packages:$PYTHONPATH"

注意：集群重启后该路径可能会变化，需重新获取并更新配置。

3. 改用作业模式提交代码（替代方案） #

如果上述方案仍无法解决问题，可以将代码包装为Databricks作业，通过作业API或CLI提交执行，确保代码运行在集群的隔离环境中，完全匹配笔记本的执行环境。

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