Миграция из dbx в пакеты

Статья
02/05/2025

Внимание

Databricks рекомендует использовать пакеты ресурсов Databricks вместо dbx Databricks Labs. Связанные статьи о dbx них были прекращены и могут быть не обновлены.

В этой статье описывается перенос проектов для dbx Databricks Labs в пакеты ресурсов Databricks. Общие сведения о dbx by Databricks Labs и что такое пакеты активов Databricks?.

Перед миграцией обратите внимание на следующие ограничения и сравнения функций между dbx Databricks Labs и Databricks Asset Bundles.

Сравнения функций

Перед миграцией обратите внимание на то, как в пакетах ресурсов Databricks реализованы следующие функции dbx Databricks Labs.

Шаблоны и проекты

dbx обеспечивает поддержку шаблонов Jinja. Вы можете включить шаблоны Jinja в конфигурацию развертывания и передать переменные среды либо встроенными, либо через файл переменных. Хотя это не рекомендуется, dbx также предоставляет экспериментальную поддержку пользовательских функций.

Пакеты обеспечивают поддержку шаблонов Go для повторного использования конфигурации. Пользователи могут создавать пакеты на основе предварительно созданных шаблонов. Существует почти полная четность для шаблонов, за исключением пользовательских функций пользователя.

Управление сборками

dbx обеспечивает поддержку сборки с помощью pip wheel, поэзии и Flit. Пользователи могут указать параметр сборки в build разделе файла проекта deployment.yml .

Пакеты позволяют пользователям создавать, развертывать и запускать файлы колес python. Пользователи могут использовать встроенную whl запись в файле пакета databricks.yml .

Синхронизация, развертывание и запуск кода

dbx позволяет отправлять код отдельно от создания ресурсов рабочей области, таких как задания Azure Databricks.

Пакеты всегда загружают код и создают или обновляют ресурсы рабочей области одновременно. Это упрощает развертывание и позволяет избежать блокировки условий для заданий, которые уже выполняются.

Перенос проекта dbx в пакет

После того как вы заметите предыдущие ограничения и сравнения функций между dbx Databricks Labs и Databricks Asset Bundles, вы можете перейти из dbx пакетов.

Databricks рекомендует начать dbx миграцию проекта, сохранить проект dbx в исходной папке и у вас есть отдельная пустая папка, в которую копируется содержимое исходного dbx проекта. Эта отдельная папка будет новым пакетом. Вы можете столкнуться с непредвиденными проблемами, если начать преобразование dbx проекта в исходную папку в пакет, а затем сделать некоторые ошибки или начать с самого начала,

Шаг 1. Установка и настройка интерфейса командной строки Databricks

Пакеты активов Databricks обычно доступны в Databricks CLI версии 0.218.0 и выше. Если вы уже установили и настроили Интерфейс командной строки Databricks версии 0.218.0 или более поздней, перейдите к шагу 2.

Примечание.

Пакеты несовместимы с Databricks CLI версии 0.18 и ниже.

Установите или обновите интерфейс командной строки Databricks версии 0.218.0 или более поздней. См. установите или обновите CLI Databricks.
Настройте интерфейс командной строки Databricks для проверки подлинности с помощью целевых рабочих областей Azure Databricks, например с помощью проверки подлинности маркера личного доступа Azure Databricks. Сведения о других типах проверки подлинности Azure Databricks см. в разделе "Проверка подлинности" для интерфейса командной строки Databricks.

Шаг 2. Создание файла конфигурации пакета

Если вы используете интегрированную среду разработки, например Visual Studio Code, PyCharm Professional или IntelliJ IDEA Ultimate, которая обеспечивает поддержку файлов YAML и файлов схемы JSON, вы можете использовать интегрированную среду разработки не только для создания файла конфигурации пакета, но и для проверки синтаксиса и форматирования файла и предоставления подсказок о завершении кода. следующим образом.

Visual Studio Code

Добавьте поддержку сервера языка YAML в Visual Studio Code, например путем установки расширения YAML из Visual Studio Code Marketplace.
Создайте файл схемы пакета ресурсов Databricks в формате JSON с помощью интерфейса командной строки Databricks для выполнения команды bundle schema и перенаправления выходных данных в JSON-файл. Например, создайте файл с именем bundle_config_schema.json в текущем каталоге следующим образом:
```
databricks bundle schema > bundle_config_schema.json
```
Используйте Visual Studio Code для создания или открытия файла конфигурации пакета в текущем каталоге. По соглашению этот файл называется databricks.yml.
Добавьте следующий комментарий в начало файла конфигурации пакета:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Примечание.

В предыдущем комментарии, если файл схемы конфигурации пакета ресурсов Databricks находится в другом месте, замените bundle_config_schema.json на полный путь к вашему файлу схемы.
Используйте функции сервера языка YAML, добавленные ранее. Дополнительные сведения см. в документации по серверу языка YAML.

PyCharm Professional

Создайте файл схемы пакета ресурсов Databricks в формате JSON с помощью интерфейса командной строки Databricks для выполнения команды bundle schema и перенаправления выходных данных в JSON-файл. Например, создайте файл с именем bundle_config_schema.json в текущем каталоге следующим образом:
```
databricks bundle schema > bundle_config_schema.json
```
Настройте PyCharm для распознавания файла конфигурации JSON схемы пакета, а затем завершите сопоставление JSON схемы, следуя инструкциям в Настройка пользовательской схемы JSON.
Используйте PyCharm для создания или открытия файла конфигурации пакета. По соглашению этот файл называется databricks.yml. При вводе PyCharm проверяет синтаксис схемы JSON и форматирование и предоставляет указания по завершению кода.

IntelliJ IDEA Ultimate

Создайте файл схемы пакета ресурсов Databricks в формате JSON с помощью интерфейса командной строки Databricks для выполнения команды bundle schema и перенаправления выходных данных в JSON-файл. Например, создайте файл с именем bundle_config_schema.json в текущем каталоге следующим образом:
```
databricks bundle schema > bundle_config_schema.json
```
Настройте IntelliJ IDEA для распознавания файла схемы JSON конфигурации бандла, а затем завершите сопоставление схемы JSON, следуя инструкциям в разделе Настройка пользовательской схемы JSON.
Используйте IntelliJ IDEA для создания или открытия файла конфигурации пакета. По соглашению этот файл называется databricks.yml. При вводе IntelliJ IDEA проверяет синтаксис схемы JSON и форматирование и предоставляет указания по завершению кода.

Шаг 3. Преобразование параметров проекта dbx в databricks.yml

Преобразуйте параметры в файле проекта dbx.dbx/project.json в эквивалентные параметры в файле пакета databricks.yml . Дополнительные сведения см. в разделе "Преобразование параметров проекта dbx в databricks.yml".

Шаг 4. Преобразование параметров развертывания dbx в databricks.yml

Преобразуйте параметры в папку проекта dbxconf в эквивалентные параметры в файле пакета databricks.yml . Дополнительные сведения см. в разделе "Преобразование параметров развертывания dbx в databricks.yml".

Шаг 5. Проверка пакета

Перед развертыванием артефактов или выполнением задания Azure Databricks, конвейера Delta Live Tables или конвейера MLOps необходимо убедиться, что файл конфигурации пакета синтаксически правильным. Для этого выполните bundle validate команду из корневого каталога пакета:

databricks bundle validate

Дополнительные сведения см. в bundle validateразделе "Проверка пакета".

Шаг 6. Развертывание пакета

Чтобы развернуть все указанные локальные артефакты в удаленной рабочей области, выполните bundle deploy команду из корневого каталога пакета. Если параметры команды не указаны, используется целевой объект по умолчанию, объявленный в файле конфигурации пакета:

databricks bundle deploy

Чтобы развернуть артефакты в контексте определенного целевого объекта, укажите -t параметр (или --target) вместе с именем целевого объекта, объявленным в файле конфигурации пакета. Например, для целевого объекта, объявленного именем development:

databricks bundle deploy -t development

Дополнительные сведения см. в bundle deployразделе "Развертывание пакета".

Совет

Вы можете связать задания и конвейеры, определенные в пакете, с существующими заданиями и конвейерами в рабочей области Azure Databricks, чтобы сохранить их в синхронизации. См. Связывание ресурсов пакета.

Шаг 7. Запуск пакета

Чтобы запустить определенное задание или конвейер, выполните bundle run команду из корневого каталога пакета. Необходимо указать задание или конвейер, объявленные в файле конфигурации пакета. -t Если параметр не указан, используется целевой объект по умолчанию, объявленный в файле конфигурации пакета. Например, чтобы запустить задание с именем hello_job в контексте целевого объекта по умолчанию:

databricks bundle run hello_job

Выполнение задания с именем hello_job в контексте целевого объекта, объявленного с именем development:

databricks bundle run -t development hello_job

Дополнительные сведения см. в bundle runразделе "Запуск задания или конвейера".

(Необязательно) Шаг 8. Настройка пакета для CI/CD с помощью GitHub

Если вы используете GitHub для CI/CD, вы можете использовать GitHub Actions для автоматического выполнения databricks bundle deploy и databricks bundle run команд на основе определенных событий рабочего процесса GitHub и других критериев. См . сведения о выполнении рабочего процесса CI/CD с помощью пакета ресурсов Databricks и GitHub Actions.

Преобразование параметров проекта dbx в databricks.yml

Для dbxэтого параметры проекта по умолчанию находятся в файле с именем project.json в папке проекта .dbx . См . справочник по файлу project.

Для пакетов конфигурации пакетов по умолчанию находятся в файле, именованном databricks.yml в корневой папке пакета. См. сведения о конфигурации пакета активов Databricks.

Для файла со следующим примером содержимого conf/project.json :

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

Соответствующий databricks.yml файл выглядит следующим образом:

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

Следующие объекты в предыдущем conf/project.json файле этого примера не поддерживаются в databricks.yml файлах и не имеют обходных решений.

inplace_jinja_support
storage_type

Следующие дополнительные разрешенные объекты в conf/project.json файлах не поддерживаются в databricks.yml файлах и не имеют обходных решений.

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Преобразование параметров развертывания dbx в databricks.yml

Для dbxэтого параметры развертывания по умолчанию находятся в файле в папке проекта conf . См . справочник по файлу развертывания. Файл параметров развертывания по умолчанию имеет одно из следующих имен файлов:

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

Для пакетов параметры развертывания по умолчанию находятся в файле с именем databricks.yml в корневой папке пакета. См. сведения о конфигурации пакета активов Databricks.

Для файла со следующим примером содержимого conf/deployment.yml :

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"