Переход из dbx в пакеты

Внимание

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

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

Перед миграцией обратите внимание на следующие ограничения и сравнительные характеристики между dbx от Databricks Labs и Декларативными Пакетами Автоматизации.

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

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

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

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

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

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

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

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

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

dbx позволяет отправлять код отдельно от создания ресурсов пространства работы, таких как Задания Lakeflow.

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

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

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

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

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

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

Примечание.

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

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

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

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

Visual Studio Code

Добавьте поддержку сервера языка YAML в Visual Studio Code, например путем установки расширения YAML из Visual Studio Code Marketplace.
Создайте файл схемы 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
```
Примечание.

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

PyCharm Professional

Создайте файл схемы 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

Создайте файл схемы 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

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

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

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

databricks bundle validate

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

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

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

databricks bundle deploy

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

databricks bundle deploy -t development

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

Совет

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

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

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

databricks bundle run hello_job

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

databricks bundle run -t development hello_job

Для получения информации о bundle run см. databricks bundle run.

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

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

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

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

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

Для файла со следующим примером содержимого 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 в корневой папке пакета. См . раздел "Декларативная конфигурация пакетов автоматизации".

Для файла со следующим примером содержимого 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'