分享方式:


安裝適用於 Python 的 Databricks Connect

注意

本文涵蓋 Databricks Runtime 13.3 LTS 和更新版本適用的 Databricks Connect。

本文說明如何安裝適用於 Python 的 Databricks Connect。 請參閱 什麼是 Databricks Connect?。 如需本文的 Scala 版本,請參閱 安裝適用於 Scala 的 Databricks Connect。

需求

若要安裝適用於 Python 的 Databricks Connect,必須符合下列需求:

  • 如果您要連線到 無伺服器計算,您的工作區必須符合 無伺服器計算的需求。

  • 如果您要連線到 叢集,您的目標叢集必須符合 叢集組態 需求,其中包括 Databricks 運行時間版本需求。

  • 您的開發計算機上必須安裝 Python 3,而安裝在開發電腦上的 Python 次要版本必須符合下表中的版本需求。

    Databricks Connect 版本 計算類型 相容的 Python 版本
    15.3 Cluster 3.11
    15.2 Cluster 3.11
    15.1 Cluster 3.11
    15.1 無伺服器 3.10
    13.3 LTS 至 14.3 LTS Cluster 3.10
  • 如果您想要使用 PySpark UDF,您的開發電腦安裝的次要 Python 版本必須符合叢集或無伺服器計算上安裝之 Databricks Runtime 隨附的 Python 次要版本。 若要尋找叢集的次要 Python 版本,請參閱 適用於叢集或無伺服器計算之 Databricks Runtime 版本資訊的系統環境 一節。 請參閱 Databricks Runtime 版本資訊版本資訊,以及相容性無伺服器計算版本資訊

啟用 Python 虛擬環境

Databricks 強烈建議您已針對與 Databricks Connect 搭配使用的每個 Python 版本啟用 Python 虛擬環境 。 Python 虛擬環境可協助您確定您使用的是正確的 Python 版本和 Databricks Connect。 如需這些工具以及如何啟用這些工具的詳細資訊,請參閱 venv詩歌

安裝 Databricks Connect 用戶端

本節說明如何使用 venv 或 Poetry 安裝 Databricks Connect 用戶端

注意

如果您已安裝適用於Visual Studio Code的 Databricks 擴充功能,就不需要遵循這些設定指示,因為適用於Visual Studio Code 的 Databricks 延伸模組已經內建支援 Databricks Connect for Databricks Runtime 13.3 LTS 和更新版本。 針對 Visual Studio Code 的 Databricks 延伸模組使用 Databricks Connect,跳至 偵錯程式代碼

使用 venv 安裝 Databricks Connect 用戶端

  1. 啟用虛擬環境后,執行 uninstall 命令,以卸載已安裝 PySpark。 這是必要的, databricks-connect 因為套件與 PySpark 衝突。 如需詳細資訊,請參閱 衝突的 PySpark 安裝。 若要檢查是否已安裝 PySpark,請執行 show 命令。

    # Is PySpark already installed?
    pip3 show pyspark
    
    # Uninstall PySpark
    pip3 uninstall pyspark
    
  2. 在虛擬環境仍啟用之後,請執行 install 命令來安裝 Databricks Connect 用戶端。 --upgrade使用 選項,將任何現有的用戶端安裝升級至指定的版本。

    pip3 install --upgrade "databricks-connect==14.3.*"  # Or X.Y.* to match your cluster version.
    

    注意

    Databricks 建議您附加 「dot-asterisk」 表示法來指定 databricks-connect==X.Y.* ,而不是 databricks-connect=X.Y,以確保已安裝最新的套件。 雖然這不是必要條件,但它有助於確定您可以使用該叢集的最新支援功能。

直接跳到設定 連線屬性

使用詩歌安裝 Databricks Connect 用戶端

  1. 啟用虛擬環境后,執行 remove 命令,以卸載已安裝 PySpark。 這是必要的, databricks-connect 因為套件與 PySpark 衝突。 如需詳細資訊,請參閱 衝突的 PySpark 安裝。 若要檢查是否已安裝 PySpark,請執行 show 命令。

    # Is PySpark already installed?
    poetry show pyspark
    
    # Uninstall PySpark
    poetry remove pyspark
    
  2. 在虛擬環境仍啟用之後,請執行 add 命令來安裝 Databricks Connect 用戶端。

    poetry add databricks-connect@~14.3  # Or X.Y to match your cluster version.
    

    注意

    Databricks 建議您使用「波狀符號」表示法來指定 databricks-connect@~14.3 ,而不是 databricks-connect==14.3,以確保已安裝最新的套件。 雖然這不是必要條件,但它有助於確定您可以使用該叢集的最新支援功能。

設定連線屬性

在本節中,您會設定屬性來建立 Databricks Connect 與 Azure Databricks 叢集無伺服器計算之間的連線,其中包括下列內容:

注意

設定叢集的連線

若要設定叢集的連線,您需要叢集的標識符。 您可以從 URL 取得叢集識別碼。 請參閱 叢集 URL 和標識碼

您可以使用下列其中一種方式來設定叢集的連線。 Databricks Connect 會依下列順序搜尋組態屬性,並使用它找到的第一個組態。 如需進階組態資訊,請參閱 適用於 Python 的 Databricks Connect 進階使用方式。

  1. DatabricksSession 類別的 remote() 方法
  2. Databricks 組態配置檔
  3. DATABRICKS_CONFIG_PROFILE環境變數
  4. 每個組態屬性的環境變數
  5. 名為 DEFAULT 的 Databricks 組態配置檔

類別 DatabricksSessionremote() 方法

針對此選項,僅適用於 Azure Databricks 個人存取令牌驗證 、指定工作區實例名稱、Azure Databricks 個人存取令牌,以及叢集的標識符。

您可以透過數種方式初始化 DatabricksSession 類別,如下所示:

  • 在中DatabricksSession.builder.remote()設定hosttokencluster_id 欄位。
  • 使用 Databricks SDK 的 Config 類別。
  • 指定 Databricks 組態配置檔以及 cluster_id 欄位。
  • 在 中DatabricksSession.builder.remote()設定 Spark Connect 連接字串。

Databricks 建議透過環境變數或組態檔設定屬性,而不是在您的程式代碼中指定這些連接屬性,如本節所述。 下列程式代碼範例假設您提供建議 retrieve_* 函式的一些實作,以從使用者或從某些其他組態存放區取得必要的屬性,例如 Azure KeyVault

下列每個方法的程式代碼如下:

# 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 組態配置檔

針對此選項,請建立或識別包含字段cluster_id的 Azure Databricks 組態配置檔,以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。

每個驗證類型的必要組態設定檔欄位如下所示:

然後透過 Config 類別設定此組態配置檔的名稱。

您可以透過幾種方式來指定 cluster_id ,如下所示:

  • cluster_id 組態配置檔中包含 字段,然後只指定組態配置檔的名稱。
  • 指定組態配置檔名稱以及 cluster_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環境變數

針對此選項,請建立或識別包含字段cluster_id的 Azure Databricks 組態配置檔,以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。

如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID 環境變數,則不需要指定 cluster_id

每個驗證類型的必要組態設定檔欄位如下所示:

DATABRICKS_CONFIG_PROFILE 環境變數設定為此組態配置檔的名稱。 然後初始化 類別, DatabricksSession 如下所示:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

每個組態屬性的環境變數

針對此選項,請設定DATABRICKS_CLUSTER_ID環境變數,以及您想要使用之 Databricks 驗證類型所需的任何其他環境變數。

每個驗證類型的必要環境變數如下:

然後初始化 類別, DatabricksSession 如下所示:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

名為的 Databricks 組態配置檔 DEFAULT

針對此選項,請建立或識別包含字段cluster_id的 Azure Databricks 組態配置檔,以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。

如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID 環境變數,則不需要指定 cluster_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
    
    spark = DatabricksSession.builder.serverless(True).getOrCreate()
    
    from databricks.connect import DatabricksSession
    
    spark = DatabricksSession.builder.remote(serverless=True).getOrCreate()
    

注意

無伺服器計算會話會在閑置 10 分鐘後逾時。 之後,必須在用戶端重新啟動 Python 程式,才能建立新的 Spark 工作階段,以連線到無伺服器計算。

驗證 Databricks 的連線

若要驗證您的環境、預設認證和計算連線已針對 Databricks Connect 正確設定,請執行 databricks-connect test 命令,此命令會在偵測到安裝程式中的任何不相容時,失敗並出現非零結束代碼和對應的錯誤訊息。

databricks-connect test

或者,您可以使用 pyspark 包含在 Databricks Connect for Python 中的殼層,並執行簡單的命令。 如需 PySpark 殼層的詳細資訊,請參閱 Pyspark 殼層