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

Пакеты ресурсов Databricks описывают ресурсы Databricks, такие как задания, конвейеры и записные книжки в качестве исходных файлов, позволяют включать метаданные вместе с этими исходными файлами для подготовки инфраструктуры и других ресурсов, а также предоставлять комплексное определение проекта, все упакованные в виде одного развертываемого проекта. См. раздел "Что такое пакеты ресурсов Databricks?".

Шаблоны пакетов позволяют пользователям создавать пакеты в согласованном, повторяемом режиме, устанавливая структуры папок, шаги сборки и задачи, тесты и другие атрибуты инфраструктуры как кода (IaC) DevOps, распространенные в конвейере развертывания.

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

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

Создание пакета с помощью шаблона

Чтобы использовать шаблон пакета Azure Databricks для создания пакета, используйте команду cli Databricks clibundle init, указав имя используемого шаблона. Например, следующая команда создает пакет с помощью шаблона пакета Python по умолчанию:

databricks bundle init default-python

Чтобы использовать пользовательский шаблон пакета, передайте локальный путь или удаленный URL-адрес шаблона в команду Databricks CLIbundle init.

Например, следующая команда использует шаблон dab-container-template, созданный в Учебнике по созданию пользовательского шаблона пакета:

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Если шаблон не указан, команда bundle init предлагает набор доступных шаблонов по умолчанию, из которых можно выбрать.

Шаблоны пакетов по умолчанию

Azure Databricks предоставляет следующие шаблоны пакетов по умолчанию:

Пользовательские шаблоны наборов

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

Структура проекта шаблона

Как минимум, проект шаблона пакета должен иметь следующее:

• Файл databricks_template_schema.json в корневом каталоге проекта, который определяет свойство, запрашиваемое у пользователя, для имени проекта пакета. См. Схема шаблона.
• databricks.yml.tmpl Файл, расположенный в папкеtemplate, которая определяет конфигурацию для всех пакетов, созданных с помощью шаблона. Если ваш databricks.yml.tmpl файл ссылается на любые дополнительные *.yml.tmpl шаблоны конфигурации, укажите их расположение в сопоставлении include. См. шаблоны конфигурации.

Кроме того, структура папок и включенные файлы в папке template проекта шаблона пакета дублируются в пакетах, созданных с этим шаблоном. Например, если вы хотите, чтобы шаблон создавал пакет с простой записной книжкой, расположенной в папке src, и с определением задания, которое запускает эту записную книжку в папке resources, вам следует упорядочить проект шаблона следующим образом:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb

Схема шаблона

Проект шаблона пользовательского пакета должен содержать databricks_template_schema.jsonJSON-файл в корневом каталоге этого проекта. Этот файл определяет поля, используемые интерфейсом командной строки Databricks при выполнении команды bundle init, например текста запроса.

Следующий базовый файл databricks_template_schema.json определяет входную переменную project_name для проекта пакета, включающую сообщение запроса и значение по умолчанию. Затем определяется сообщение об успешной инициализации проекта "bunde", которое использует входное значение переменной в сообщении.

{
  "properties": {
    "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
    }
  },
  "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

Поля схемы шаблона

Файл databricks_template_schema.json поддерживает определение входных переменных для сбора информации во время инициализации пакета от пользователя в поле properties, а также дополнительные поля для настройки инициализации.

Входные переменные определяются в поле properties схемы шаблона. Каждая входная переменная определяет метаданные, необходимые для представления пользователю запроса во время инициализации пакета. Затем значение переменной доступно с помощью синтаксиса переменной шаблона, например {{.project_name}}.

Можно также задать значения некоторых полей для настройки процесса инициализации пакета.

Поддерживаемые поля схемы перечислены в следующей таблице.

Шаблоны конфигурации

Шаблон пользовательского пакета должен содержать файл databricks.yml.tmpl в папке template в проекте шаблона пакета, который используется для создания файла конфигурации проекта пакета databricks.yml. Шаблоны для файлов конфигурации для ресурсов можно создать в папке resources. Заполните эти файлы шаблонов конфигурацией в формате YAML.

В следующем простом примере шаблонов конфигурации для databricks.yml и связанных *_job.yml устанавливают имя пакета и две целевые среды, а также определяют задание, которое запускает ноутбук в пакете для пакетов, созданных с использованием этого шаблона. Эти шаблоны конфигурации используют возможности подстановочных параметров пакета и вспомогательных функций шаблонов пакета .

template/{{.project_name}}/databricks.yml.tmpl:

# databricks.yml
# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.project_name}}_job.yml
# The main job for {{.project_name}}

resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

помощники и переменные шаблонов

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

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

Вспомогательные функции пользовательских шаблонов

Чтобы определить собственные вспомогательные шаблоны, создайте файл шаблона в папке library проекта шаблона и используйте синтаксис шаблонов Go для определения вспомогательных элементов. Например, следующее содержимое файла library/variables.tmpl определяет переменные cli_version и model_name. Если этот шаблон используется для инициализации пакета, значение переменной model_name создается с помощью поля input_project_name, определенного в файле схемы шаблона. Значение этого поля — это входные данные пользователя после запроса.

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

Полный пример см. в файле переменных шаблона mlops-stacks.

Тестирование шаблона пакета

Наконец, обязательно протестируйте шаблон. Например, используйте интерфейс командной строки Databricks для инициализации нового пакета с помощью шаблона, определенного в предыдущих разделах:

databricks bundle init basic-bundle-template

Для запроса What is your bundle project name? введите my_test_bundle.

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

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

Теперь databricks.yml файл и задание настраиваются:

# databricks.yml
# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

# my_test_bundle_job.yml
# The main job for my_test_bundle

resources:
    jobs:
        my_test_bundle_job:
        name: my_test_bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

Поделитесь шаблоном

Если вы хотите предоставить общий доступ к этому шаблону пакета другим пользователям, вы можете сохранить его в элементе управления версиями с любым поставщиком, поддерживающим Git, и к которым у пользователей есть доступ. Чтобы выполнить bundle init команду с URL-адресом Git, убедитесь, что databricks_template_schema.json файл находится в корневом расположении относительно этого URL-адреса Git.

Следующие шаги

• Просмотрите дополнительные шаблоны, созданные и поддерживаемые Databricks. См. репозиторий примеров пакетов в GitHub.
• Чтобы использовать стеки MLOps с шаблонами наборов ресурсов Databricks, см. раздел Наборы ресурсов Databricks для стеков MLOps.
• Узнайте больше о шаблонизации пакетов Go. Ознакомьтесь с документацией шаблона пакета Go.