安装适用于 Python 的 Databricks Connect

项目
03/25/2024

注意

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

本文介绍如何安装或更新适用于 Python 的 Databricks Connect。请参阅什么是 Databricks Partner Connect？。有关本文的 Scala 版本，请参阅安装适用于 Scala 的 Databricks Connect。

要求

目标 Azure Databricks 工作区和群集必须满足 Databricks Connect 群集配置的要求。
必须在开发计算机上安装 Python 3，并且客户端 Python 安装次要版本必须与 Azure Databricks 群集的次要 Python 版本相同。若要查找群集的 Python 次要版本，请参阅群集的 Databricks Runtime 发行说明的“系统环境”部分。请参阅 Databricks Runtime 发行说明版本和兼容性。

注意

如果要使用 PySpark UDF，请务必确保开发计算机安装的 Python 次要版本与群集上安装的 Databricks Runtime 附带的 Python 次要版本相匹配。
Databricks Connect 的主要和次要包版本应与 Databricks Runtime 版本匹配。 Databricks 建议始终使用与 Databricks Runtime 版本相匹配的 Databricks Connect 的最新包。例如，在使用 Databricks Runtime 14.0 群集时，也应使用 databricks-connect 包的 14.0 版本。

注意

请参阅 Databricks Connect 发行说明，了解可用 Databricks Connect 版本和维护更新的列表。

不需要使用与 Databricks Runtime 版本匹配的最新 Databricks Connect 包。对于 Databricks Runtime 13.0 及更高版本，可以对 Databricks Connect 包版本或更高版本的所有 Databricks Runtime 使用 Databricks Connect 包。但是，如果要使用 Databricks Runtime 的更高版本中提供的功能，则必须相应地升级 Databricks Connect 包。
Databricks 强烈建议为与 Databricks Connect 配合使用的每个 Python 版本激活 Python 虚拟环境。 Python 虚拟环境有助于确保将正确版本的 Python 和 Databricks Connect 一起使用。这有助于减少相关技术问题或缩短解决此类问题的时间。请参阅以下部分，以了解如何激活适用于 venv 或 Poetry 的 Python 虚拟环境。有关这些工具的详细信息，请参阅 venv 或 Poetry。

使用 venv 激活 Python 虚拟环境

如果在开发计算机上使用 venv，并且群集正在运行 Python 3.10，则必须使用该版本创建一个 venv 环境。以下示例命令生成使用 Python 3.10 激活 venv 环境的脚本，然后此命令将这些脚本放在当前工作目录内名为 .venv 的隐藏文件夹中：

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

若要使用这些脚本激活此 venv 环境，请参阅 venvs 的工作原理。

跳到设置客户端。

使用 Poetry 激活 Python 虚拟环境

如果尚未安装 Poetry，请先安装。
如果在开发计算机上使用 Poetry，并且群集正在运行 Python 3.10，则必须使用该版本创建一个 Poetry 虚拟环境。在现有 Python 代码项目的根目录中，通过运行以下命令，指示 poetry 初始化 Poetry 的 Python 代码项目：
```
poetry init
```
Poetry 显示多个需要完成的提示。这些提示都不特定于 Databricks Connect。有关这些提示的信息，请参阅 init。
完成提示后，Poetry 会将 pyproject.toml 文件添加到 Python 项目。有关 pyproject.toml 文件的信息，请参阅 pyproject.toml 文件。
在 Python 代码项目的根目录中，指示 poetry 读取 pyproject.toml 文件、解析依赖项并安装它们、创建 poetry.lock 文件以锁定依赖项，最后创建虚拟环境。为此，请运行以下命令：
```
poetry install
```
在 Python 代码项目的根目录中，指示 poetry 激活虚拟环境并进入 shell。为此，请运行以下命令：
```
poetry shell
```

当虚拟环境的名称显示在紧接终端提示符前面的括号中时（例如 (my-project-py3.10)），即表示你的虚拟环境已激活并且已进入 shell。

若要随时停用虚拟环境并退出 shell，请运行命令 exit。

当虚拟环境的名称不再显示在紧接终端提示符前面的括号中时，就表示你已退出 shell。

若要详细了解如何创建和管理 Poetry 环境，请参阅管理环境。

安装客户端

提示

如果你已安装 Visual Studio Code 的 Databricks 扩展，则无需按照这些设置说明进行操作。

Visual Studio Code 的 Databricks 扩展本身已经支持适用于 Databricks Runtime 13.0 及更高版本的 Databricks Connect。跳到使用 Databricks Connect 为 Visual Studio Code 的 Databricks 扩展调试代码。

满足 Databricks Connect 的要求后，请完成以下步骤来设置 Databricks Connect 客户端。

步骤 1：安装 Databricks Connect 客户端

本部分介绍如何使用 venv 或 Poetry 安装 Databricks Connect 客户端。

使用 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.0.*"  # Or X.Y.* to match your cluster version.
```
备注

Databricks 建议追加“.*”符号来指定 databricks-connect==X.Y.* 而不是 databricks-connect=X.Y，以确保安装最新的包。虽然并不要求如此，但这样有助于确保为该群集使用最新的受支持功能。

向前跳转到步骤 2：配置连接属性。

使用 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.0  # Or X.Y to match your cluster version.
```
注意

Databricks 建议使用“at-tilde”表示法来指定 databricks-connect@~14.0 而不是 databricks-connect==14.0，以确保安装最新的包。虽然并不要求如此，但这样有助于确保为该群集使用最新的受支持功能。

第 2 步：配置连接属性

本部分将配置属性以在 Databricks Connect 和远程 Azure Databricks 群集之间建立连接。这些属性包括用于对群集的 Databricks Connect 进行身份验证的设置。

对于适用于 Databricks Runtime 13.1 及更高版本的 Databricks Connect，Databricks Connect 包括适用于 Python 的 Databricks SDK。此 SDK 实施 Databricks 客户端统一身份验证标准，这是一种整合且一致的体系结构和编程身份验证方法。此方法可使 Azure Databricks 的身份验证设置和自动化更加集中和可预测。借助此方法，你只需配置 Azure Databricks 身份验证一次，然后即可在多个 Azure Databricks 工具和 SDK 中使用该配置，而无需进一步更改身份验证配置。

注意

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 进行身份验证。请参阅教程。
Databricks SDK for Python 尚未实现 Azure 托管标识身份验证。
适用于 Databricks Runtime 13.0 的 Databricks Connect 仅支持使用 Azure Databricks 个人访问令牌身份验证进行身份验证。

收集以下配置属性。
- Azure Databricks 工作区实例名称。这与群集的服务器主机名值相同；请参阅获取 Azure Databricks 计算资源的连接详细信息。
- 群集的 ID。可从 URL 获取群集 ID。请参阅群集 URL 和 ID。
- 要使用的受支持的 Databricks 身份验证类型所需的任何其他属性。本部分将通篇介绍这些属性。

在代码中配置连接。 Databricks Connect 按以下顺序搜索配置属性，直到找到这些属性。找到后，它不再搜索剩余的选项。下表后面显示了每个选项的详细信息：

配置属性选项	适用于
1.`DatabricksSession` 类的 `remote()` 方法	仅限 Azure Databricks 个人访问令牌身份验证
2.一个 Azure Databricks 配置文件	所有 Azure Databricks 身份验证类型
3.`SPARK_REMOTE` 环境变量	仅限 Azure Databricks 个人访问令牌身份验证
4.`DATABRICKS_CONFIG_PROFILE` 环境变量	所有 Azure Databricks 身份验证类型
5.每个配置属性具有一个环境变量	所有 Azure Databricks 身份验证类型
6.一个名为 `DEFAULT` 的 Azure Databricks 配置文件	所有 Azure 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 不建议在代码中直接指定这些连接属性。而 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()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

一个 Azure Databricks 配置文件

对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及你要使用的 Databricks 身份验证类型所需的任何其他字段。

每种身份验证类型所需的配置文件字段如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：host 和 token。
- 对于 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()
```
SPARK_REMOTE 环境变量

对于仅适用于 Azure Databricks 个人访问令牌身份验证的此选项，请将 SPARK_REMOTE 环境变量设置为以下字符串，并将占位符替换为适当的值。
```
sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>
```
然后如下所示初始化 DatabricksSession 类：
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```
若要设置环境变量，请参阅操作系统的文档。
DATABRICKS_CONFIG_PROFILE 环境变量

对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及你要使用的 Databricks 身份验证类型所需的任何其他字段。

如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。

每种身份验证类型所需的配置文件字段如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：host 和 token。
- 对于 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 用户到计算机 (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 的 Azure Databricks 配置文件

对于此选项，请创建或标识 Azure Databricks 配置文件，其中包含字段 cluster_id，以及你要使用的 Databricks 身份验证类型所需的任何其他字段。

如果已使用群集 ID 设置 DATABRICKS_CLUSTER_ID 环境变量，则也无需指定 cluster_id。

每种身份验证类型所需的配置文件字段如下：
- 适用于 Azure Databricks 个人访问令牌身份验证：host 和 token。
- 对于 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 群集的连接
- 以下命令将验证是否已为 Databricks Connect 正确设置环境、默认凭据和与群集的连接。
```
databricks-connect test
```
  此命令会选取在环境中配置的默认凭据（如 DEFAULT 配置文件或通过环境变量）。
  
  当命令检测到设置不兼容时，该命令将失败并显示非零退出代码和相应的错误消息。
- 此外，还可以使用 Databricks Connect for Python 附带的 pyspark shell。通过运行以下命令来启动 shell：
```
pyspark
```
  此时会显示 Spark shell，例如：
```
Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>
```
  在 >>> 提示符下，运行简单的 PySpark 命令，例如 spark.range(1,10).show()。如果未出现错误，则表示连接成功。
  
  如果已成功连接，若要停止 Spark shell，请按 Ctrl + d 或 Ctrl + z，或者运行命令 quit() 或 exit()。
  
  有关 databricks-connect 二进制文件的更多详细信息，请参阅 Databricks Connect for Python 的高级用法