使用Databricks Connect V2本地运行代码遇RuntimeError求助

问题重现 #

使用VSCode Databricks扩展可正常连接带Unity Catalog的Azure Databricks工作区，集群为DBR 13.2/13.3，执行以下代码时触发错误：

from pyspark.sql import SparkSession
spark = SparkSession.builder.getOrCreate()

错误信息：

RuntimeError: Only remote Spark sessions using Databricks Connect are supported. Could not find connection parameters to start a Spark remote session.

已尝试AZ CLI、PAT两种认证方式，均未解决。

必须完成的配置步骤 #

• 安装匹配版本的Databricks Connect包
  需安装与集群DBR版本完全匹配的包，DBR 13.x对应安装databricks-connect==13.2.*或13.3.*，执行命令：

  pip install databricks-connect==13.2.*
  

• 本地初始化连接配置
  运行交互式配置命令，按提示输入工作区URL、集群ID、认证方式（PAT或AZ CLI）：

  databricks-connect configure
  

  注意：集群ID可从Databricks工作区集群页面的URL中提取（格式如/clusters/xxxxxx-xxxxxx-xxxxxx，最后一段即为集群ID），且需确保集群处于活跃运行状态。

• 验证配置有效性
  执行测试命令确认连接正常：

  databricks-connect test
  

  测试通过后再运行Spark代码。

• 指定VSCode的Python解释器
  确保VSCode使用的Python解释器是安装了Databricks Connect的环境，可通过左下角的解释器选择器切换到对应虚拟环境或conda环境。

• Unity Catalog额外配置
  若需访问Unity Catalog，需在SparkSession中添加相关配置：

  spark = SparkSession.builder \
      .config("spark.databricks.unityCatalog.enabled", "true") \
      .config("spark.sql.catalog.spark_catalog", "com.databricks.spark.catalog.UnityCatalog") \
      .getOrCreate()
  

常见排查点 #

• 检查本地配置文件~/.databricks-connect，确认host、cluster_id、token（PAT认证时）或auth_type（AZ CLI认证时为azure-cli）参数正确。
• 确保本地网络可访问Databricks工作区及集群端口，集群未处于暂停或异常状态。
• 使用AZ CLI认证时，需先执行az login完成账号登录，且登录账号拥有集群访问权限。

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