Установка Databricks Connect для Python

Примечание.

В этой статье рассматриваются Databricks Connect для Databricks Runtime 13.3 LTS и более поздних версий.

В этой статье описывается установка Databricks Connect для Python. См. раздел "Что такое Databricks Connect?". Сведения о версии Scala этой статьи см. в разделе Install Databricks Connect for Scala.

Требования

Чтобы установить Databricks Connect для Python, необходимо выполнить следующие требования:

• Если вы подключаетесь к бессерверным вычислениям, рабочая область должна соответствовать требованиям для бессерверных вычислений.

  Примечание.

  Бессерверные вычисления поддерживаются в Databricks Connect версии 15.1 и выше. Кроме того, версии Databricks Connect по сравнению с выпуском Databricks Runtime в бессерверном режиме полностью совместимы. См . заметки о выпуске. Чтобы проверить, совместима ли версия Databricks Connect с бессерверными вычислениями, см. статью "Проверка подключения к Databricks".

• Если вы подключаетесь к кластеру, целевой кластер должен соответствовать требованиям к конфигурации кластера, включая требования к версии Databricks Runtime.

• На компьютере разработки должен быть установлен Python 3, а дополнительная версия Python, установленная на компьютере разработки, должна соответствовать требованиям к версии в таблице ниже.

  Тип вычисления	Версия Databricks Connect	Совместимая версия Python
  Кластер	13.3 LTS до 14.3 LTS	3,10
  Кластер	15.1 и более поздних версий	3.11
  Бессерверные приложения	15.1 и более поздних версий	3,10

• Если вы хотите использовать определяемые пользователем функции PySpark, на компьютере разработки установлена дополнительная версия Python, должна соответствовать дополнительной версии Python, которая включена в среду выполнения Databricks, установленную в кластере или бессерверном вычислении. Чтобы найти дополнительную версию Python кластера, обратитесь к разделу "Системная среда выполнения" заметок о выпуске Databricks Runtime для кластера или бессерверных вычислений. Ознакомьтесь с заметками о выпуске Databricks Runtime и версиями совместимости и заметками о выпуске бессерверных вычислений.

Активация виртуальной среды Python

Databricks настоятельно рекомендует активировать виртуальную среду Python для каждой версии Python, которая используется с Databricks Connect. Виртуальные среды Python помогают убедиться, что вы используете правильные версии Python и Databricks Connect вместе. Дополнительные сведения об этих инструментах и их активации см . в venv или поэзии.

Установка клиента Databricks Connect

В этом разделе описывается установка клиента Databricks Connect с помощью venv или поэзии.

Примечание.

Если у вас уже установлено расширение Databricks для Visual Studio Code, вам не нужно следовать этим инструкциям по настройке, так как расширение Databricks для Visual Studio Code уже имеет встроенную поддержку Databricks Connect для Databricks Runtime 13.3 LTS и выше. Перейдите к коду отладки с помощью Databricks Connect для расширения Databricks для Visual Studio Code.

Установка клиента Databricks Connect с помощью venv

1. После активации виртуальной среды удалите PySpark, если оно уже установлено, выполнив uninstall команду. Это необходимо, так как пакет databricks-connect конфликтует с PySpark. Дополнительные сведения см. в разделе Конфликтующие установки PySpark. Чтобы проверить, установлен ли PySpark, выполните show команду.

   # Is PySpark already installed?
   pip3 show pyspark
   
   # Uninstall PySpark
   pip3 uninstall pyspark
   

2. При активации виртуальной среды установите клиент Databricks Connect, выполнив install команду. --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. После активации виртуальной среды удалите PySpark, если оно уже установлено, выполнив remove команду. Это необходимо, так как пакет databricks-connect конфликтует с PySpark. Дополнительные сведения см. в разделе Конфликтующие установки PySpark. Чтобы проверить, установлен ли PySpark, выполните show команду.

   # Is PySpark already installed?
   poetry show pyspark
   
   # Uninstall PySpark
   poetry remove pyspark
   

2. При активации виртуальной среды установите клиент Databricks Connect, выполнив add команду.

   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, который требуется использовать.

Примечание.

• Проверка подлинности OAuth на компьютере (U2M) поддерживается в пакете SDK Databricks для Python 0.19.0 и более поздних версий. Возможно, потребуется обновить установленную версию проекта кода пакета SDK Databricks для Python до 0.19.0 или более поздней, чтобы использовать проверку подлинности OAuth U2M. Ознакомьтесь с пакетом SDK Databricks для Python.

  Для проверки подлинности OAuth U2M необходимо использовать интерфейс командной строки Databricks для проверки подлинности перед запуском кода Python. См. руководство.

• Проверка подлинности OAuth на компьютере (M2M) OAuth на компьютере (M2M) поддерживается в пакете SDK Databricks для Python 0.18.0 и более поздних версий. Возможно, потребуется обновить установленную версию проекта кода пакета SDK Databricks для Python до 0.18.0 или более поздней, чтобы использовать проверку подлинности OAuth M2M. Ознакомьтесь с пакетом SDK Databricks для Python.

• Пакет SDK Databricks для Python еще не реализовал проверку подлинности управляемых удостоверений Azure.

Настройка подключения к кластеру

Чтобы настроить подключение к кластеру, потребуется идентификатор кластера. Идентификатор кластера можно получить по URL-адресу. См . URL-адрес кластера и идентификатор.

Подключение к кластеру можно настроить одним из следующих способов. Databricks Connect ищет свойства конфигурации в следующем порядке и использует первую найденную конфигурацию. Дополнительные сведения о конфигурации см. в статье "Дополнительное использование Databricks Connect для Python".

1. Метод remote() класса DatabricksSession.
2. Профиль конфигурации Databricks
3. Переменная среды DATABRICKS_CONFIG_PROFILE
4. Переменная среды для каждого свойства конфигурации
5. Профиль конфигурации Databricks с именем DEFAULT

DatabricksSession Метод класса remote()

Для этого параметра, который применяется только к проверке подлинности личного маркера доступа Azure Databricks, укажите имя экземпляра рабочей области, личный маркер доступа Azure Databricks и идентификатор кластера.

Класс можно инициализировать DatabricksSession несколькими способами следующим образом:

• hostЗадайте в поле , tokenа также cluster_id поля DatabricksSession.builder.remote().
• Используйте класс пакета SDK Config Databricks.
• Укажите профиль конфигурации 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

Для этого параметра создайте или определите профиль конфигурации Azure Databricks, содержащий поле cluster_id и любые другие поля, необходимые для типа проверки подлинности Databricks, который требуется использовать.

Обязательные поля профиля конфигурации для каждого типа проверки подлинности приведены следующим образом:

• Для проверки подлинности маркера личного доступа Azure Databricks: host и token.
• Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): hostclient_idи client_secret.
• Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): host
• Для проверки подлинностиhost субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secretи, возможноazure_workspace_resource_id, .
• Для проверки подлинности Azure CLI: host
• Для проверки подлинности управляемых удостоверений Azure (где поддерживается): host, azure_use_msiazure_client_idи, возможноazure_workspace_resource_id, .

Затем задайте имя этого профиля конфигурации через 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 среды

Для этого параметра создайте или определите профиль конфигурации Azure Databricks, содержащий поле cluster_id и любые другие поля, необходимые для типа проверки подлинности Databricks, который требуется использовать.

Если вы уже установили DATABRICKS_CLUSTER_ID переменную среды с идентификатором кластера, вам также не нужно указывать cluster_id.

Обязательные поля профиля конфигурации для каждого типа проверки подлинности приведены следующим образом:

• Для проверки подлинности маркера личного доступа Azure Databricks: host и token.
• Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): hostclient_idи client_secret.
• Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): host
• Для проверки подлинностиhost субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secretи, возможноazure_workspace_resource_id, .
• Для проверки подлинности Azure CLI: host
• Для проверки подлинности управляемых удостоверений Azure (где поддерживается): host, azure_use_msiazure_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.
• Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): DATABRICKS_HOSTDATABRICKS_CLIENT_IDи DATABRICKS_CLIENT_SECRET.
• Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): DATABRICKS_HOST
• Для проверки подлинностиDATABRICKS_HOST субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , ARM_TENANT_ID, ARM_CLIENT_IDARM_CLIENT_SECRETи, возможноDATABRICKS_AZURE_RESOURCE_ID, .
• Для проверки подлинности Azure CLI: DATABRICKS_HOST
• Для проверки подлинности управляемых удостоверений Azure (где поддерживается): DATABRICKS_HOST, ARM_USE_MSIARM_CLIENT_IDи, возможноDATABRICKS_AZURE_RESOURCE_ID, .

Затем инициализировать DatabricksSession класс следующим образом:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Профиль конфигурации Databricks с именем DEFAULT

Для этого параметра создайте или определите профиль конфигурации Azure Databricks, содержащий поле cluster_id и любые другие поля, необходимые для типа проверки подлинности Databricks, который требуется использовать.

Если вы уже установили DATABRICKS_CLUSTER_ID переменную среды с идентификатором кластера, вам также не нужно указывать cluster_id.

Обязательные поля профиля конфигурации для каждого типа проверки подлинности приведены следующим образом:

• Для проверки подлинности маркера личного доступа Azure Databricks: host и token.
• Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): hostclient_idи client_secret.
• Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): host
• Для проверки подлинностиhost субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secretи, возможноazure_workspace_resource_id, .
• Для проверки подлинности Azure CLI: host
• Для проверки подлинности управляемых удостоверений Azure (где поддерживается): host, azure_use_msiazure_client_idи, возможноazure_workspace_resource_id, .

Присвойте этому профилю DEFAULTконфигурации имя.

Затем инициализировать DatabricksSession класс следующим образом:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Настройка подключения к бессерверным вычислениям

Внимание

Эта функция предоставляется в режиме общедоступной предварительной версии.

Databricks Connect поддерживает подключение к бессерверным вычислениям. Чтобы использовать эту функцию, необходимо выполнить требования для подключения к бессерверному серверу. См. раздел Требования.

Внимание

Сейчас эта функция имеет следующие ограничения:

• Все ограничения Databricks Connect для Python
• Все ограничения бессерверных вычислений
• Для определяемых пользователем пользователей можно использовать только зависимости Python, включенные в состав бессерверной вычислительной среды. См. сведения о системной среде. Не удается установить дополнительные зависимости.
• Определяемые пользователем функции с пользовательскими модулями не поддерживаются.

Подключение к бессерверным вычислениям можно настроить одним из следующих способов:

• Задайте для переменной 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...
  

• Кроме того, просто обновите код Python Databricks Connect следующим образом:

  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()