Szablony projektów pakietu zasobów usługi Databricks

Pakiety zasobów Databricks opisują zasoby Databricks, takie jak zadania, potoki i notesy, jako pliki źródłowe, umożliwiając dołączanie metadanych do tych plików w celu przygotowania infrastruktury i innych zasobów, oraz dostarczają kompleksową definicję projektu — wszystko to spakowane jako jeden łatwy do wdrożenia pakiet projektowy. Zobacz Co to są pakiety zasobów Databricks?.

Szablony pakietów umożliwiają użytkownikom tworzenie pakietów w spójny, powtarzalny sposób przez ustanowienie struktur folderów, kroków kompilacji i zadań, testów i innych atrybutów infrastruktury jako kodu (IaC) devOps wspólnych w potoku wdrażania.

Jeśli na przykład rutynowo uruchamiasz zadania usługi Databricks, które wymagają pakietów niestandardowych z czasochłonnym krokiem kompilacji podczas instalacji, możesz przyspieszyć pętlę programowania, tworząc szablon pakietu, który określa niestandardowe środowisko kontenera.

Usługa Databricks udostępnia zestaw domyślnych szablonów pakietów , ale można również utworzyć szablony pakietów niestandardowych . Użytkownicy mogą następnie inicjować pakiety przy użyciu polecenia bundle init, określając szablon domyślny lub własny szablon.

Tworzenie pakietu przy użyciu szablonu

Aby utworzyć pakiet przy użyciu szablonu pakietu usługi Azure Databricks, użyj interfejsu wiersza polecenia usługi Databricksbundle init, określając nazwę szablonu do użycia. Na przykład następujące polecenie tworzy pakiet przy użyciu domyślnego szablonu pakietu języka Python:

databricks bundle init default-python

Aby użyć niestandardowego szablonu pakietu, przekaż ścieżkę lokalną lub zdalny adres URL szablonu do polecenia Databricks CLIbundle init.

Na przykład, następujące polecenie używa szablonu dab-container-template stworzonego w Poradniku dotyczącym tworzenia niestandardowego szablonu pakietu.

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

Jeśli nie określisz szablonu, wiersz polecenia bundle init podpowiada zestaw dostępnych domyślnych szablonów, z którego można wybrać.

Domyślne szablony pakietów

Usługa Azure Databricks udostępnia następujące domyślne szablony pakietów:

szablony pakietów niestandardowych

Szablony pakietów używają składni tworzenia szablonów pakietów języka Go, która zapewnia elastyczność szablonów pakietów niestandardowych, które można utworzyć. Zapoznaj się z dokumentacją szablonu pakietu Go.

struktura projektu szablonu

Co najmniej projekt szablonu pakietu musi mieć następujące elementy:

• Plik databricks_template_schema.json w katalogu głównym projektu, który definiuje jedną właściwość monitu użytkownika dla nazwy projektu pakietu. Zobacz Schemat szablonu.
• databricks.yml.tmpl Plik znajdujący się w folderze definiującym konfigurację template wszystkich pakietów utworzonych za pomocą szablonu. Jeśli plik databricks.yml.tmpl odwołuje się do dodatkowych szablonów konfiguracji *.yml.tmpl, określ lokalizację tych szablonów w mapowaniu include. Zobacz szablony konfiguracji .

Dodatkowo, struktura folderów oraz dołączone pliki projektu szablonu pakietu template są odwzorowane przez pakiety utworzone z użyciem tego szablonu. Jeśli na przykład chcesz, aby szablon wygenerował pakiet z prostym notesem w folderze src i definicją zadania uruchamiającą notes w folderze resources, należy zorganizować projekt szablonu w następujący sposób:

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

schemat szablonu

Projekt niestandardowego szablonu pakietu musi zawierać plik databricks_template_schema.jsonJSON w katalogu głównym projektu. Ten plik definiuje pola używane przez interfejs wiersza polecenia usługi Databricks, gdy jest uruchamiane polecenie bundle init, takie jak tekst monitu.

Poniższy podstawowy plik databricks_template_schema.json definiuje zmienną wejściową project_name dla projektu pakietu, która zawiera komunikat monitu i wartość domyślną. Następnie definiuje komunikat o powodzeniu inicjowania projektu bunde, który używa wartości zmiennej wejściowej w komunikacie.

{
  "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."
}

Pola schematu szablonu

Plik databricks_template_schema.json obsługuje definiowanie zmiennych wejściowych do zbierania informacji podczas inicjowania pakietu od użytkownika w polu properties, a także dodatkowe pola w celu dostosowania inicjowania.

Zmienne wejściowe są definiowane w polu properties schematu szablonu. Każda zmienna wejściowa definiuje metadane potrzebne do przedstawienia użytkownikowi monitu podczas inicjowania pakietu. Wartość zmiennej jest następnie dostępna przy użyciu składni zmiennej szablonu, takiej jak {{.project_name}}.

Można również ustawić wartości niektórych pól, aby dostosować proces inicjowania pakietu.

Obsługiwane pola schematu są wymienione w poniższej tabeli.

szablony konfiguracji

Szablon pakietu niestandardowego powinien zawierać plik databricks.yml.tmpl w folderze template w projekcie szablonu pakietu, który jest używany do tworzenia pliku konfiguracji projektu pakietu databricks.yml. Szablony plików konfiguracji dla zasobów można utworzyć w folderze resources. Wypełnij te pliki szablonu przy użyciu szablonu konfiguracji YAML.

Poniższe proste, przykładowe szablony konfiguracji dla databricks.yml i skojarzone *_job.yml ustalają nazwę pakietu oraz dwa środowiska docelowe, a także definiują zadanie uruchamiające notatnik w ramach pakietu, dla pakietów utworzonych przy użyciu tego szablonu. Te szablony konfiguracji korzystają z podstawień pakietów i pomocników szablonów pakietów .

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

Pomocnicy szablonów i zmienne

Pomocnicy szablonów to funkcje udostępniane przez usługę Databricks, których można używać w plikach szablonów, aby uzyskać informacje specyficzne dla użytkownika podczas wykonywania lub interakcji z silnikiem szablonów. Możesz również zdefiniować własne zmienne szablonu.

Następujące pomocniki szablonów są dostępne dla projektów szablonów pakietu usługi Databricks. Aby uzyskać informacje na temat używania szablonów i zmiennych języka Go, zobacz Szablony języka Go.

Niestandardowe pomocniki szablonów

Aby zdefiniować własne pomocniki szablonu, utwórz plik szablonu w folderze library projektu szablonu i użyj składni szablonu Języka Go, aby zdefiniować pomocników. Na przykład następująca zawartość pliku library/variables.tmpl definiuje zmienne cli_version i model_name. Gdy ten szablon jest używany do inicjowania pakietu, wartość zmiennej model_name jest konstruowana przy użyciu pola input_project_name zdefiniowanego w pliku schematu szablonu. Wartość tego pola to dane wejściowe użytkownika po wyświetleniu monitu.

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

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

Aby wyświetlić pełny przykład, zapoznaj się z plikiem zmiennych szablonu mlops-stacks.

Testowanie szablonu pakietu

Na koniec upewnij się, że szablon został przetestowany. Na przykład użyj interfejsu wiersza polecenia usługi Databricks, aby zainicjować nowy pakiet przy użyciu szablonu zdefiniowanego w poprzednich sekcjach:

databricks bundle init basic-bundle-template

Dla monitu What is your bundle project name? wpisz my_test_bundle.

Po utworzeniu pakietu testowego zostanie wyświetlony komunikat o powodzeniu z pliku schematu. Jeśli zbadasz zawartość my_test_bundle folderu, powinny zostać wyświetlone następujące elementy:

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

Plik i zadanie databricks.yml są teraz dostosowane:

# 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

Udostępnianie szablonu

Jeśli chcesz udostępnić ten szablon pakietu innym osobom, możesz przechowywać go w kontroli wersji za pomocą dowolnego dostawcy obsługiwanego przez usługę Git i do którego użytkownicy mają dostęp. Aby uruchomić polecenie bundle init z adresem URL Git, upewnij się, że plik databricks_template_schema.json znajduje się w katalogu głównym względem tego adresu URL Git.

Następne kroki

• Przeglądaj dodatkowe szablony tworzone i obsługiwane przez usługę Databricks. Zobacz repozytorium przykładów pakietów w usłudze GitHub.
• Aby używać stosów MLOps z szablonami pakietów zasobów usługi Databricks, zobacz Pakiety zasobów usługi Databricks dla stosów MLOps.
• Dowiedz się więcej o tworzeniu szablonów pakietów języka Go. Zapoznaj się z dokumentacją szablonu pakietu Go.