安装适用于 Python 的 Databricks Connect
注意
本文介绍适用于 Databricks Runtime 13.3 LTS 及更高版本的 Databricks Connect。
本文介绍如何安装或更新适用于 Python 的 Databricks Connect。 请参阅什么是 Databricks Partner Connect？。 有关本文的 Scala 版本，请参阅安装适用于 Scala 的 Databricks Connect。
要求
要安装适用于 Python 的 Databricks Connect，必须满足以下要求：
必须已在开发计算机上安装 Python 3，并且开发计算机上安装的 Python 次要版本必须满足下表中的版本要求。
计算类型 Databricks Connect 版本 兼容的 Python 版本 Cluster 13.3 LTS 到 14.3 LTS 3.10 Cluster 15.1 及更高版本 3.11
如果你要使用 PySpark UDF，开发计算机上安装的 Python 次要版本必须与群集或无服务器计算上安装的 Databricks Runtime 附带的 Python 次要版本相匹配。 若要查找群集的 Python 次要版本，请参阅群集计算的 Databricks Runtime 发行说明的“系统环境”部分。 请参阅 Databricks Runtime 发行说明版本和兼容性。
激活 Python 虚拟环境
Databricks 强烈建议为与 Databricks Connect 配合使用的每个 Python 版本激活 Python 虚拟环境。 Python 虚拟环境有助于确保将正确版本的 Python 和 Databricks Connect 一起使用。 有关这些工具及其激活方式的详细信息，请参阅venv或Poetry。
安装 Databricks Connect 客户端
本部分介绍了如何使用venv或Poetry安装 Databricks Connect 客户端。
注意
如果已安装适用于 Visual Studio Code 的 Databricks 扩展，则无需按照这些设置说明进行操作，因为适用于 Visual Studio Code 的 Databricks 扩展已内置支持适用于 Databricks Runtime 13.3 LTS 及更高版本的 Databricks Connect。 跳过使用 Databricks Connect 为 Visual Studio Code 的 Databricks 扩展调试代码。
使用 vnev 安装 Databricks Connect 客户端
激活虚拟环境后，运行
uninstall命令卸载 PySpark（如果已安装）。 这是必需的，因为databricks-connect包与 PySpark 冲突。 有关详细信息，请参阅 PySpark 安装存在冲突。 若要检查是否已安装 PySpark，请运行show命令。# Is PySpark already installed? pip3 show pyspark # Uninstall PySpark pip3 uninstall pyspark在虚拟环境仍处于激活状态的情况下，运行
install命令安装 Databricks Connect 客户端。 使用--upgrade选项将任何现有客户端安装升级到指定的版本。pip3 install --upgrade "databricks-connect==14.3.*" # Or X.Y.* to match your cluster version.备注
Databricks 建议追加“.*”符号来指定
databricks-connect==X.Y.*而不是databricks-connect=X.Y，以确保安装最新的包。 虽然并不要求如此，但这样有助于确保为该群集使用最新的受支持功能。
向前跳转到配置连接属性。
使用 Poetry 安装 Databricks Connect 客户端
激活虚拟环境后，运行
remove命令卸载 PySpark（如果已安装）。 这是必需的，因为databricks-connect包与 PySpark 冲突。 有关详细信息，请参阅 PySpark 安装存在冲突。 若要检查是否已安装 PySpark，请运行show命令。# Is PySpark already installed? poetry show pyspark # Uninstall PySpark poetry remove pyspark在虚拟环境仍处于激活状态的情况下，运行
add命令安装 Databricks Connect 客户端。poetry add databricks-connect@~14.3 # Or X.Y to match your cluster version.注意
Databricks 建议使用“at-tilde”表示法来指定
databricks-connect@~14.3而不是databricks-connect==14.3，以确保安装最新的包。 虽然并不要求如此，但这样有助于确保为该群集使用最新的受支持功能。
配置连接属性
在本部分，你将配置属性以在 Databricks Connect 和 Azure Databricks 群集之间建立连接，此配置包括：
- Azure Databricks 工作区实例名称。 此即计算的“服务器主机名”值。 请参阅获取 Azure Databricks 计算资源的连接详细信息。
- 要使用的 Databricks 身份验证类型所需的任何其他属性。
注意
Databricks SDK for Python 0.19.0 及更高版本支持 OAuth 用户到计算机 (U2M) 身份验证。 可能需要将代码项目的 Databricks SDK for Python 的已安装版本更新为 0.19.0 或更高版本，才能使用 OAuth U2M 身份验证。 请参阅 Databricks SDK for Python 入门。
对于 OAuth U2M 身份验证，必须在运行 Python 代码之前使用 Databricks CLI 进行身份验证。 请参阅教程。
OAuth 计算机到计算机 (M2M) 身份验证 0.18.0 及更高版本的 Databricks SDK for Python 支持 OAuth 计算机到计算机 (M2M) 身份验证。 可能需要将代码项目的 Databricks SDK for Python 的已安装版本更新为 0.18.0 或更高版本，才能使用 OAuth M2M 身份验证。 请参阅 Databricks SDK for Python 入门。
Databricks SDK for Python 尚未实现 Azure 托管标识身份验证。
配置与群集的连接
要配置与群集的连接，需要群集的 ID。 可从 URL 获取群集 ID。 请参阅群集 URL 和 ID。
可以通过以下方式之一配置到群集的连接。 Databricks Connect 按以下顺序搜索配置属性，并使用它找到的第一个配置。 有关高级配置信息，请参阅适用于 Python 的 Databricks Connect 的高级用法。
- DatabricksSession 类的 remote() 方法。
- Databricks 配置文件
- DATABRICKS_CONFIG_PROFILE 环境变量
- 每个配置属性具有一个环境变量
- 名为 DEFAULT 的 Databricks 配置文件
DatabricksSession 类的 remote() 方法
对于仅适用于 Azure Databricks 个人访问令牌身份验证的此选项，请指定工作区实例名称、Azure Databricks 个人访问令牌和群集的 ID。
可通过多种方式来初始化 DatabricksSession 类，如下所示：
- 在
DatabricksSession.builder.remote()中设置host、token和cluster_id字段。 - 使用 Databricks SDK 的
Config类。 - 指定 Databricks 配置文件和
cluster_id字段。 - 在
DatabricksSession.builder.remote()中设置 Spark Connect 连接字符串。
Databricks 建议通过环境变量或配置文件配置属性，而不是在代码中指定这些连接属性，如本部分通篇所述。 以下代码示例假定你提供建议的retrieve_*函数的一些实现，以从用户或其他配置存储（例如，Azure 密钥保管库）中获取必要的属性。
每种方法的代码如下所示：
# Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.remote(
host = f"https://{retrieve_workspace_instance_name()}",
token = retrieve_token(),
cluster_id = retrieve_cluster_id()
).getOrCreate()
# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config
config = Config(
host = f"https://{retrieve_workspace_instance_name()}",
token = retrieve_token(),
cluster_id = retrieve_cluster_id()
)
spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()
# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config
config = Config(
profile = "<profile-name>",
cluster_id = retrieve_cluster_id()
)
spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()
Databricks 配置文件
对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及你要使用的 Databricks 身份验证类型所需的任何其他字段。
每种身份验证类型所需的配置文件字段如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：
host和token。 - 对于 OAuth 计算机到计算机 (M2M) 身份验证（在支持的情况下）：
host、client_id和client_secret。 - 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：
host。 - 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：
host、azure_tenant_id、azure_client_id、azure_client_secret和可能的azure_workspace_resource_id。 - 适用于 Azure CLI 身份验证：
host。 - 对于 Azure 托管标识身份验证（如果支持）：
host、azure_use_msi、azure_client_id和可能的azure_workspace_resource_id。
然后通过 Config 类设置此配置文件的名称。
可通过多种方式指定 cluster_id，如下所示：
- 在配置文件中包含
cluster_id字段，然后只需指定配置文件的名称。 - 指定配置文件名称和
cluster_id字段。
如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。
每种方法的代码如下所示：
# Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()
# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config
config = Config(
profile = "<profile-name>",
cluster_id = retrieve_cluster_id()
)
spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()
DATABRICKS_CONFIG_PROFILE 环境变量
对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及你要使用的 Databricks 身份验证类型所需的任何其他字段。
如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。
每种身份验证类型所需的配置文件字段如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：
host和token。 - 对于 OAuth 计算机到计算机 (M2M) 身份验证（在支持的情况下）：
host、client_id和client_secret。 - 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：
host。 - 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：
host、azure_tenant_id、azure_client_id、azure_client_secret和可能的azure_workspace_resource_id。 - 适用于 Azure CLI 身份验证：
host。 - 对于 Azure 托管标识身份验证（如果支持）：
host、azure_use_msi、azure_client_id和可能的azure_workspace_resource_id。
将 DATABRICKS_CONFIG_PROFILE 环境变量设置为此配置文件的名称。 然后如下所示初始化 DatabricksSession 类：
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
每个配置属性的环境变量
对于此选项，请设置 DATABRICKS_CLUSTER_ID 环境变量，以及你要使用的 Databricks 身份验证类型所需的任何其他环境变量。
每种身份验证类型所需的环境变量如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：
DATABRICKS_HOST和DATABRICKS_TOKEN。 - 对于 OAuth 计算机到计算机 (M2M) 身份验证（在支持的情况下）：
DATABRICKS_HOST、DATABRICKS_CLIENT_ID和DATABRICKS_CLIENT_SECRET。 - 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：
DATABRICKS_HOST。 - 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：
DATABRICKS_HOST、ARM_TENANT_ID、ARM_CLIENT_ID、ARM_CLIENT_SECRET和可能的DATABRICKS_AZURE_RESOURCE_ID。 - 适用于 Azure CLI 身份验证：
DATABRICKS_HOST。 - 对于 Azure 托管标识身份验证（如果支持）：
DATABRICKS_HOST、ARM_USE_MSI、ARM_CLIENT_ID和可能的DATABRICKS_AZURE_RESOURCE_ID。
然后如下所示初始化 DatabricksSession 类：
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
名为 DEFAULT 的 Databricks 配置文件
对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及你要使用的 Databricks 身份验证类型所需的任何其他字段。
如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。
每种身份验证类型所需的配置文件字段如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：
host和token。 - 对于 OAuth 计算机到计算机 (M2M) 身份验证（在支持的情况下）：
host、client_id和client_secret。 - 对于 OAuth 用户到计算机 (U2M) 身份验证（在支持的情况下）：
host。 - 对于 Microsoft Entra ID（以前称为 Azure Active Directory）服务主体身份验证：
host、azure_tenant_id、azure_client_id、azure_client_secret和可能的azure_workspace_resource_id。 - 适用于 Azure CLI 身份验证：
host。 - 对于 Azure 托管标识身份验证（如果支持）：
host、azure_use_msi、azure_client_id和可能的azure_workspace_resource_id。
将此配置文件命名为 DEFAULT。
然后如下所示初始化 DatabricksSession 类：
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
配置与无服务器计算的连接
重要
此功能目前以公共预览版提供。
Databricks Connect 支持连接到无服务器计算。 要使用此功能，必须满足连接到无服务器的要求。 请参阅 要求。
可以通过以下方式之一配置与无服务器计算的连接：
将本地环境变量
DATABRICKS_SERVERLESS_COMPUTE_ID设置为auto。 如果设置了此环境变量，则 Databricks Connect 会忽略cluster_id。在本地 Databricks 配置文件中，设置
serverless_compute_id = auto，然后从 Databricks Connect Python 代码中引用该配置文件。[DEFAULT] host = https://my-workspace.cloud.databricks.com/ serverless_compute_id = auto token = dapi123...或者，只需更新 Databricks Connect Python 代码，如下所示：
from databricks.connect import DatabricksSession as SparkSession spark = DatabricksSession.builder.serverless(True).getOrCreate()from databricks.connect import DatabricksSession as SparkSession spark DatabricksSession.builder.remote(serverless=True).getOrCreate()
注意
无服务器计算会话在处于非活动状态 10 分钟后超时。 之后，需要在客户端重启 Python 进程以新建 Spark 会话，从而连接到无服务器计算。
验证与 Databricks 的连接
要验证是否已为 Databricks Connect 正确设置环境、默认凭据和与计算的连接，请运行databricks-connect test命令，该命令在检测到设置中的任何不兼容时，会失败并显示非零退出代码和相应的错误消息。
databricks-connect test
在 Python 代码中还可以使用 validateSession() 验证环境：
DatabricksSession.builder.validateSession(True).getOrCreate()