使用英语阅读

通过

适用于 Python 的 Databricks Connect 故障排除

  • 项目
  • 2025/05/13

备注

本文介绍适用于 Databricks Runtime 13.3 LTS 及更高版本的 Databricks Connect。

本文介绍有关适用于 Python 的 Databricks Connect 常见问题的故障排除信息。 Databricks Connect 使你能够将常用 IDE、笔记本服务器和自定义应用程序连接到 Azure Databricks 群集。 请参阅什么是 Databricks Partner Connect？。 有关本文的 Scala 版本，请参阅适用于 Scala 的 Databricks Connect 故障排除。

错误: StatusCode.UNAVAILABLE，StatusCode.UNKNOWN，DNS 解析失败，或收到状态为 500 的 http2 标头

问题：尝试使用 Databricks Connect 运行代码时，收到包含 、StatusCode.UNAVAILABLE、StatusCode.UNKNOWN 或 DNS resolution failed 等字符串的错误消息。

可能的原因：Databricks Connect 无法访问你的群集。

建议的解决方法：

  • 检查并确保工作区实例名称正确。 如果使用了环境变量，请检查并确保相关环境变量在本地开发计算机上可用且正确。
  • 检查并确保群集 ID 正确。 如果使用了环境变量，请检查并确保相关环境变量在本地开发计算机上可用且正确。
  • 检查并确保群集使用与 Databricks Connect 兼容的正确自定义群集版本。

Python 版本不匹配

检查确保在本地使用的 Python 版本至少与群集上的版本具有相同的次要版本（例如，3.10.11 是 3.10.10 是正确的，3.10 和 3.9 不正确）。 有关支持的版本，请参阅 版本支持矩阵。

如果本地安装了多个 Python 版本，请设置 PYSPARK_PYTHON 环境变量（例如 PYSPARK_PYTHON=python3），确保 Databricks Connect 使用的版本是正确的。

PySpark 安装存在冲突

databricks-connect 包与 PySpark 冲突。 在 Python 中初始化 Spark 上下文时，安装这两种都会导致错误。 这可能以多种方式显示出来，包括“流已损坏”或“找不到类”错误。 如果已在 pyspark Python 环境中安装，请确保在安装 databricks-connect之前卸载它。 卸载 PySpark 后，请确保彻底重新安装 Databricks Connect 包：

pip3 uninstall pyspark
pip3 uninstall databricks-connect
pip3 install --upgrade "databricks-connect==14.0.*"  # or X.Y.* to match your specific cluster version.

Databricks Connect 和 PySpark 互斥，但可以使用 Python 虚拟环境在 IDE 中执行 databricks-connect 远程开发，并在终端中使用本地测试 pyspark 。 但是，Databricks 建议在所有测试中使用 Databricks Connect for Python 和 无服务器计算 ，原因如下：

  • Databricks Runtime，因此 databricks-connect包含 OSS pyspark中不可用的功能。
  • 使用 databricks-connect 和无服务器进行测试比在本地测试 pyspark 更快。
  • Unity Catalog 的集成在 pyspark 中不可用，因此，当您在本地使用 pyspark 进行测试时，不会强制实施任何权限。
  • 对于使用外部依赖项（如 Databricks 计算）进行端到端测试，集成测试（而不是单元测试）是最好的。

如果仍选择连接到本地 Spark 群集，可以使用以下命令指定 连接字符串 ：

connection_string = "sc://localhost"
DatabricksSession.builder.remote(connection_string).getOrCreate()

二进制文件的 PATH 项冲突或缺失

可能是这样配置 PATH 的：spark-shell 等命令将运行之前安装的其他某些二进制文件，而不是运行随附 Databricks Connect 提供的二进制文件。 应确保 Databricks Connect 二进制文件优先，或者删除之前安装的二进制文件。

如果无法运行 spark-shell 之类的命令，也可能是 pip3 install 未自动设置 PATH，你需要将 bin dir 手动安装到 PATH 中。 即使未设置此项，也可将 Databricks Connect 与 IDE 一起使用。

Windows 上的文件名、目录名称或卷标签语法不正确

如果正在 Windows 上使用 Databricks Connect，请参阅：

The filename, directory name, or volume label syntax is incorrect.

Databricks Connect 已安装到路径中带有空格的目录中。 要解决此问题，可安装到不带空格的目录路径或使用短名称格式配置路径。