Migrowanie z bazy danych dbx do pakietów

Artykuł
10/09/2024

Ważne

Usługa Databricks zaleca używanie pakietów zasobów usługi Databricks zamiast dbx przez usługę Databricks Labs. Powiązane artykuły o dbx zostały wycofane i mogą nie zostać zaktualizowane.

W tym artykule opisano sposób migrowania projektów usługi dbx Databricks Labs do pakietów zasobów usługi Databricks. Zobacz Wprowadzenie do dbx by Databricks Labs i Co to są pakiety zasobów usługi Databricks?.

Przed migracją należy pamiętać o następujących ograniczeniach i porównaniach funkcji między usługami dbx Databricks Labs i Databricks Asset Bundles.

Ograniczenia

Następujące funkcje obsługiwane przez dbx usługę Databricks Labs są ograniczone, nie istnieją lub wymagają obejść w pakietach zasobów usługi Databricks.

Tworzenie artefaktów JAR nie jest obsługiwane w pakietach.
Notacja FUSE dla ścieżek obszaru roboczego nie jest obsługiwana w pakietach (na przykład /Workspace/<path>/<filename>). Można jednak poinstruować pakiety, aby wygenerować ścieżki obszaru roboczego w stylu FUSE podczas wdrożeń przy użyciu notacji, takiej jak /Workspace/${bundle.file_path}/<filename>.

Porównania funkcji

Przed przeprowadzeniem migracji zwróć uwagę, jak w pakietach zasobów usługi Databricks są implementowane następujące funkcje usługi dbx Databricks Labs.

Szablony i projekty

dbx zapewniają obsługę tworzenia szablonów Jinja. Szablony Jinja można uwzględnić w konfiguracji wdrożenia i przekazać zmienne środowiskowe w tekście lub za pośrednictwem pliku zmiennych. Chociaż nie jest to zalecane, dbx zapewnia również eksperymentalną obsługę niestandardowych funkcji użytkownika.

Pakiety zapewniają obsługę szablonów języka Go w celu ponownego użycia konfiguracji. Użytkownicy mogą tworzyć pakiety na podstawie wstępnie utworzonych szablonów. Istnieje prawie pełna parzystość tworzenia szablonów, z wyjątkiem niestandardowych funkcji użytkownika.

Zarządzanie kompilacjami

dbx Zapewnia obsługę kompilacji za pośrednictwem pip wheel, poezji i Flit. Użytkownicy mogą określić opcję kompilacji w build sekcji pliku projektu deployment.yml .

Pakiety umożliwiają użytkownikom tworzenie, wdrażanie i uruchamianie plików wheel języka Python. Użytkownicy mogą korzystać z wbudowanego whl wpisu w pliku pakietu databricks.yml .

Synchronizowanie, wdrażanie i uruchamianie kodu

dbxUmożliwia przekazywanie kodu niezależnie od generowania zasobów obszaru roboczego, takich jak zadania usługi Azure Databricks.

Pakiety zawsze przekazują kod i tworzą lub aktualizują zasoby obszaru roboczego w tym samym czasie. Upraszcza to wdrożenia i pozwala uniknąć blokowania warunków dla zadań, które są już w toku.

Migrowanie projektu dbx do pakietu

Po zanotowaniu powyższych ograniczeń i porównań funkcji między usługami dbx Databricks Labs i Databricks Asset Bundles możesz przystąpić do migracji z dbx pakietów.

Usługa Databricks zaleca, aby rozpocząć migrację dbx projektu, zachować dbx projekt w oryginalnym folderze i mieć oddzielny, pusty folder, do którego kopiujesz zawartość oryginalnego dbx projektu. Ten oddzielny folder będzie nowym pakietem. Jeśli rozpoczniesz konwertowanie dbx projektu w oryginalnym folderze na pakiet, możesz napotkać nieoczekiwane problemy, a następnie popełnić błędy lub zacząć od początku.

Krok 1. Instalowanie i konfigurowanie interfejsu wiersza polecenia usługi Databricks

Pakiety zasobów usługi Databricks są ogólnie dostępne w interfejsie wiersza polecenia usługi Databricks w wersji 0.218.0 lub nowszej. Jeśli masz już zainstalowane i skonfigurowano interfejs wiersza polecenia usługi Databricks w wersji 0.218.0 lub nowszej, przejdź do kroku 2.

Uwaga

Pakiety nie są zgodne z interfejsem wiersza polecenia usługi Databricks w wersji 0.18 lub nowszej.

Zainstaluj lub zaktualizuj interfejs wiersza polecenia usługi Databricks w wersji 0.218.0 lub nowszej. Zobacz Instalowanie lub aktualizowanie interfejsu wiersza polecenia usługi Databricks.
Skonfiguruj interfejs wiersza polecenia usługi Databricks na potrzeby uwierzytelniania z docelowymi obszarami roboczymi usługi Azure Databricks, na przykład przy użyciu uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks. Inne typy uwierzytelniania usługi Azure Databricks można znaleźć w temacie Authentication for the Databricks CLI (Uwierzytelnianie dla interfejsu wiersza polecenia usługi Databricks).

Krok 2. Tworzenie pliku konfiguracji pakietu

Jeśli używasz środowiska IDE, takiego jak Visual Studio Code, PyCharm Professional lub IntelliJ IDEA Ultimate , który zapewnia obsługę plików YAML i plików schematów JSON, możesz użyć środowiska IDE nie tylko do utworzenia pliku konfiguracji pakietu, ale także do sprawdzenia składni i formatowania pliku oraz zapewnienia wskazówek dotyczących uzupełniania kodu w następujący sposób.

Visual Studio Code

Dodaj obsługę serwera języka YAML do programu Visual Studio Code, na przykład przez zainstalowanie rozszerzenia YAML z witryny Visual Studio Code Marketplace.
Wygeneruj plik schematu JSON konfiguracji pakietu zasobów usługi Databricks przy użyciu interfejsu wiersza polecenia usługi Databricks, aby uruchomić bundle schema polecenie i przekierować dane wyjściowe do pliku JSON. Na przykład wygeneruj plik o nazwie bundle_config_schema.json w bieżącym katalogu w następujący sposób:
```
databricks bundle schema > bundle_config_schema.json
```
Użyj programu Visual Studio Code, aby utworzyć lub otworzyć plik konfiguracji pakietu w bieżącym katalogu. Zgodnie z konwencją ten plik ma nazwę databricks.yml.
Dodaj następujący komentarz na początku pliku konfiguracji pakietu:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Uwaga

W poprzednim komentarzu, jeśli plik schematu JSON konfiguracji pakietu zasobów usługi Databricks znajduje się w innej ścieżce, zastąp bundle_config_schema.json pełną ścieżką do pliku schematu.
Użyj dodanych wcześniej funkcji serwera języka YAML. Aby uzyskać więcej informacji, zobacz dokumentację serwera języka YAML.

PyCharm Professional

Wygeneruj plik schematu JSON konfiguracji pakietu zasobów usługi Databricks przy użyciu interfejsu wiersza polecenia usługi Databricks, aby uruchomić bundle schema polecenie i przekierować dane wyjściowe do pliku JSON. Na przykład wygeneruj plik o nazwie bundle_config_schema.json w bieżącym katalogu w następujący sposób:
```
databricks bundle schema > bundle_config_schema.json
```
Skonfiguruj narzędzie PyCharm do rozpoznawania pliku schematu JSON konfiguracji pakietu, a następnie ukończ mapowanie schematu JSON, postępując zgodnie z instrukcjami w temacie Konfigurowanie niestandardowego schematu JSON.
Użyj narzędzia PyCharm, aby utworzyć lub otworzyć plik konfiguracji pakietu. Zgodnie z konwencją ten plik ma nazwę databricks.yml. Podczas wpisywania narzędzie PyCharm sprawdza składnię i formatowanie schematu JSON oraz udostępnia wskazówki dotyczące uzupełniania kodu.

IntelliJ IDEA Ultimate

Wygeneruj plik schematu JSON konfiguracji pakietu zasobów usługi Databricks przy użyciu interfejsu wiersza polecenia usługi Databricks, aby uruchomić bundle schema polecenie i przekierować dane wyjściowe do pliku JSON. Na przykład wygeneruj plik o nazwie bundle_config_schema.json w bieżącym katalogu w następujący sposób:
```
databricks bundle schema > bundle_config_schema.json
```
Skonfiguruj środowisko IntelliJ IDEA do rozpoznawania pliku schematu JSON konfiguracji pakietu, a następnie ukończ mapowanie schematu JSON, postępując zgodnie z instrukcjami w temacie Konfigurowanie niestandardowego schematu JSON.
Użyj środowiska IntelliJ IDEA, aby utworzyć lub otworzyć plik konfiguracji pakietu. Zgodnie z konwencją ten plik ma nazwę databricks.yml. Podczas wpisywania środowisko IntelliJ IDEA sprawdza składnię i formatowanie schematu JSON oraz udostępnia wskazówki dotyczące uzupełniania kodu.

Krok 3. Konwertowanie ustawień projektu dbx na databricks.yml

Przekonwertuj ustawienia w dbx pliku projektu .dbx/project.json na równoważne ustawienia w pliku pakietu databricks.yml . Aby uzyskać szczegółowe informacje, zobacz Konwertowanie ustawień projektu dbx na databricks.yml.

Krok 4. Konwertowanie ustawień wdrożenia dbx na databricks.yml

Przekonwertuj ustawienia w dbx folderze projektu conf na równoważne ustawienia w pliku pakietu databricks.yml . Aby uzyskać szczegółowe informacje, zobacz Konwertowanie ustawień wdrożenia dbx na databricks.yml.

Krok 5. Weryfikowanie pakietu

Przed wdrożeniem artefaktów lub uruchomieniem zadania usługi Azure Databricks, potoku delta live tables lub potoku METODYKI MLOps należy upewnić się, że plik konfiguracji pakietu jest syntaktycznie poprawny. W tym celu uruchom bundle validate polecenie z katalogu głównego pakietu:

databricks bundle validate

Aby uzyskać informacje na temat bundle validateprogramu , zobacz Weryfikowanie pakietu.

Krok 6. Wdrażanie pakietu

Aby wdrożyć wszystkie określone artefakty lokalne w zdalnym obszarze roboczym, uruchom bundle deploy polecenie z katalogu głównego pakietu. Jeśli nie określono żadnych opcji polecenia, zostanie użyty domyślny element docelowy zadeklarowany w pliku konfiguracji pakietu:

databricks bundle deploy

Aby wdrożyć artefakty w kontekście określonego obiektu docelowego, określ -t opcję (lub --target) wraz z nazwą obiektu docelowego zadeklarowaną w pliku konfiguracji pakietu. Na przykład dla obiektu docelowego zadeklarowanego z nazwą development:

databricks bundle deploy -t development

Aby uzyskać informacje na temat bundle deployprogramu , zobacz Wdrażanie pakietu.

Napiwek

Zadania i potoki zdefiniowane w pakiecie można połączyć z istniejącymi zadaniami i potokami w obszarze roboczym usługi Azure Databricks, aby zachować ich synchronizację. Zobacz Wiązanie zasobów pakietu.

Krok 7. Uruchamianie pakietu

Aby uruchomić określone zadanie lub potok, uruchom bundle run polecenie z katalogu głównego pakietu. Należy określić zadanie lub potok zadeklarowany w pliku konfiguracji pakietu. -t Jeśli opcja nie zostanie określona, zostanie użyty domyślny element docelowy zadeklarowany w pliku konfiguracji pakietu. Aby na przykład uruchomić zadanie o nazwie hello_job w kontekście domyślnego obiektu docelowego:

databricks bundle run hello_job

Aby uruchomić zadanie o nazwie hello_job w kontekście obiektu docelowego zadeklarowanego z nazwą development:

databricks bundle run -t development hello_job

Aby uzyskać informacje na temat bundle runprogramu , zobacz Uruchamianie zadania lub potoku.

(Opcjonalnie) Krok 8. Konfigurowanie pakietu ciągłej integracji/ciągłego wdrażania za pomocą usługi GitHub

Jeśli używasz usługi GitHub do ciągłej integracji/ciągłego wdrażania, możesz użyć funkcji GitHub Actions do automatycznego uruchamiania databricks bundle deploy poleceń i databricks bundle run na podstawie określonych zdarzeń przepływu pracy usługi GitHub i innych kryteriów. Zobacz Uruchamianie przepływu pracy ciągłej integracji/ciągłego wdrażania za pomocą pakietu zasobów usługi Databricks i funkcji GitHub Actions.

Konwertowanie ustawień projektu dbx na databricks.yml

W przypadku dbxprogramu ustawienia projektu są domyślnie w pliku o nazwie project.json w folderze projektu .dbx . Zobacz Dokumentacja pliku programu Project.

W przypadku pakietów konfiguracje pakietów są domyślnie w pliku o nazwie databricks.yml w folderze głównym pakietu. Zobacz Konfiguracja pakietu zasobów usługi Databricks.

conf/project.json W przypadku pliku z następującą przykładową zawartością:

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

Odpowiedni databricks.yml plik jest następujący:

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.

Następujące obiekty w powyższym conf/project.json przykładzie nie są obsługiwane w databricks.yml plikach i nie mają obejść:

inplace_jinja_support
storage_type

Następujące dodatkowe dozwolone obiekty w conf/project.json plikach nie są obsługiwane w databricks.yml plikach i nie mają obejść:

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

Konwertowanie ustawień wdrażania dbx na databricks.yml

W przypadku dbxprogramu ustawienia wdrożenia są domyślnie w pliku w folderze projektu conf . Zobacz Dokumentacja pliku wdrożenia. Plik ustawień wdrożenia domyślnie ma jedną z następujących nazw plików:

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

W przypadku pakietów ustawienia wdrożenia są domyślnie w pliku o nazwie databricks.yml w folderze głównym pakietu. Zobacz Konfiguracja pakietu zasobów usługi Databricks.

conf/deployment.yml W przypadku pliku z następującą przykładową zawartością:

build:
  python: "pip"

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