Migrera från dbx till paket

Artikel
10/09/2024

Viktigt!

Databricks rekommenderar att du använder Databricks-tillgångspaket i stället för dbx av Databricks Labs. Relaterade artiklar om dbx har dragits tillbaka och kanske inte uppdateras.

Den här artikeln beskriver hur du migrerar projekt för dbx databricks labs till Databricks-tillgångspaket. Se Introduktion till dbx från Databricks Labs och Vad är Databricks-tillgångspaket?.

Observera följande begränsningar och funktionsjämförelser mellan dbx Databricks Labs och Databricks Asset Bundles innan du migrerar.

Begränsningar

Följande funktioner som stöds i dbx Databricks Labs är begränsade, finns inte eller kräver lösningar i Databricks-tillgångspaket.

Det går inte att skapa JAR-artefakter i paket.
FUSE-notation för arbetsytesökvägar stöds inte i paket (till exempel /Workspace/<path>/<filename>). Du kan dock instruera paket att generera fuse-liknande arbetsytesökvägar under distributioner med hjälp av notation som /Workspace/${bundle.file_path}/<filename>.

Funktionsjämförelser

Innan du migrerar bör du tänka på hur följande funktioner för dbx Databricks Labs implementeras i Databricks Asset Bundles.

Mallar och projekt

dbx ge stöd för Jinja-mallar. Du kan inkludera Jinja-mallar i distributionskonfigurationen och skicka miljövariabler antingen infogade eller via en variabelfil. Även om det inte rekommenderas, dbx ger även experimentellt stöd för anpassade användarfunktioner.

Paket ger stöd för Go-mallar för återanvändning av konfiguration. Användare kan skapa paket baserat på fördefinierade mallar. Det finns nästan fullständig paritet för mallning, förutom anpassade användarfunktioner.

Bygghantering

dbx tillhandahåller byggstöd via pip wheel, Poesi och Flit. Användare kan ange byggalternativet build i avsnittet i ett projekts deployment.yml fil.

Med paket kan användare skapa, distribuera och köra Python-hjulfiler. Användare kan använda den inbyggda posten i whl en paketfil databricks.yml .

Synkronisera, distribuera och köra kod

dbx aktiverar uppladdning av kod separat från att generera arbetsyteresurser, till exempel Azure Databricks-jobb.

Paket laddar alltid upp kod och skapar eller uppdaterar arbetsyteresurser samtidigt. Detta förenklar distributioner och undviker blockeringsvillkor för jobb som redan pågår.

Migrera ett dbx-projekt till ett paket

När du har observerat de föregående begränsningarna och funktionsjämförelserna mellan dbx Databricks Labs och Databricks Asset Bundles är du redo att migrera från dbx till paket.

Databricks rekommenderar att du påbörjar en dbx projektmigrering genom att behålla dbx projektet i den ursprungliga mappen och att du har en separat tom mapp där du kopierar det ursprungliga dbx projektets innehåll. Den här separata mappen blir ditt nya paket. Du kan stöta på oväntade problem om du börjar konvertera projektet dbx i den ursprungliga mappen till ett paket och sedan gör några misstag eller vill börja om från början.

Steg 1: Installera och konfigurera Databricks CLI

Databricks-tillgångspaket är allmänt tillgängliga i Databricks CLI version 0.218.0 och senare. Om du redan har installerat och konfigurerat Databricks CLI version 0.218.0 eller senare går du vidare till steg 2.

Kommentar

Paket är inte kompatibla med Databricks CLI-versionerna 0.18 och senare.

Installera eller uppdatera till Databricks CLI version 0.218.0 eller senare. Se Installera eller uppdatera Databricks CLI.
Konfigurera Databricks CLI för autentisering med dina Azure Databricks-målarbetsytor, till exempel med hjälp av personlig åtkomsttokenautentisering i Azure Databricks. Andra autentiseringstyper för Azure Databricks finns i Autentisering för Databricks CLI.

Steg 2: Skapa paketkonfigurationsfilen

Om du använder en IDE som Visual Studio Code, PyCharm Professional eller IntelliJ IDEA Ultimate som ger stöd för YAML-filer och JSON-schemafiler kan du använda din IDE inte bara för att skapa paketkonfigurationsfilen utan för att kontrollera filens syntax och formatering och ge tips om kodkomplettering, enligt följande.

Visual Studio-koden

Lägg till stöd för YAML-språkservern i Visual Studio Code, till exempel genom att installera YAML-tillägget från Visual Studio Code Marketplace.
Generera JSON-schemafilen för Databricks Asset Bundle-konfigurationen med hjälp av Databricks CLI för att köra bundle schema kommandot och omdirigera utdata till en JSON-fil. Generera till exempel en fil med namnet bundle_config_schema.json i den aktuella katalogen enligt följande:
```
databricks bundle schema > bundle_config_schema.json
```
Använd Visual Studio Code för att skapa eller öppna en paketkonfigurationsfil i den aktuella katalogen. Enligt konventionen heter databricks.ymlden här filen .
Lägg till följande kommentar i början av paketkonfigurationsfilen:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Kommentar

Om din JSON-schemafil för Databricks Asset Bundle finns i en annan sökväg i föregående kommentar ersätter du bundle_config_schema.json med den fullständiga sökvägen till schemafilen.
Använd yaml-språkserverfunktionerna som du lade till tidigare. Mer information finns i yaml-språkserverns dokumentation.

PyCharm Professional

Generera JSON-schemafilen för Databricks Asset Bundle-konfigurationen med hjälp av Databricks CLI för att köra bundle schema kommandot och omdirigera utdata till en JSON-fil. Generera till exempel en fil med namnet bundle_config_schema.json i den aktuella katalogen enligt följande:
```
databricks bundle schema > bundle_config_schema.json
```
Konfigurera PyCharm för att identifiera JSON-schemafilen för paketkonfiguration och slutför sedan JSON-schemamappningen genom att följa anvisningarna i Konfigurera ett anpassat JSON-schema.
Använd PyCharm för att skapa eller öppna en paketkonfigurationsfil. Enligt konventionen heter databricks.ymlden här filen . När du skriver söker PyCharm efter JSON-schemasyntax och formatering och tillhandahåller kodkompletteringstips.

IntelliJ IDEA Ultimate

Generera JSON-schemafilen för Databricks Asset Bundle-konfigurationen med hjälp av Databricks CLI för att köra bundle schema kommandot och omdirigera utdata till en JSON-fil. Generera till exempel en fil med namnet bundle_config_schema.json i den aktuella katalogen enligt följande:
```
databricks bundle schema > bundle_config_schema.json
```
Konfigurera IntelliJ IDEA för att identifiera JSON-schemafilen för paketkonfiguration och slutför sedan JSON-schemamappningen genom att följa anvisningarna i Konfigurera ett anpassat JSON-schema.
Använd IntelliJ IDEA för att skapa eller öppna en paketkonfigurationsfil. Enligt konventionen heter databricks.ymlden här filen . När du skriver söker IntelliJ IDEA efter JSON-schemasyntax och formatering och tillhandahåller kodkompletteringstips.

Steg 3: Konvertera dbx-projektinställningar till databricks.yml

Konvertera inställningarna i dbx projektets .dbx/project.json fil till motsvarande inställningar i paketets databricks.yml fil. Mer information finns i Konvertera dbx-projektinställningar till databricks.yml.

Steg 4: Konvertera dbx-distributionsinställningar till databricks.yml

Konvertera inställningarna i dbx projektets conf mapp till motsvarande inställningar i paketets databricks.yml fil. Mer information finns i Konvertera dbx-distributionsinställningar till databricks.yml.

Steg 5: Verifiera paketet

Innan du distribuerar artefakter eller kör ett Azure Databricks-jobb, en Delta Live Tables-pipeline eller en MLOps-pipeline bör du se till att paketkonfigurationsfilen är syntaktiskt korrekt. Det gör du genom att bundle validate köra kommandot från paketroten:

databricks bundle validate

Mer information om bundle validatefinns i Verifiera ett paket.

Steg 6: Distribuera paketet

Om du vill distribuera angivna lokala artefakter till fjärrarbetsytan kör bundle deploy du kommandot från paketroten. Om inga kommandoalternativ anges används standardmålet som deklareras i paketkonfigurationsfilen:

databricks bundle deploy

Om du vill distribuera artefakterna inom ramen för ett specifikt mål anger du -t alternativet (eller --target) tillsammans med målets namn som deklarerats i paketkonfigurationsfilen. Till exempel för ett mål som deklarerats med namnet development:

databricks bundle deploy -t development

Mer information om bundle deployfinns i Distribuera ett paket.

Dricks

Du kan länka paketdefinierade jobb och pipelines till befintliga jobb och pipelines på Azure Databricks-arbetsytan för att hålla dem synkroniserade. Se Bind paketresurser.

Steg 7: Kör paketet

Kör kommandot från paketroten bundle run för att köra ett visst jobb eller en pipeline. Du måste ange jobbet eller pipelinen som deklarerats i paketkonfigurationsfilen. Om alternativet -t inte anges används standardmålet som deklarerats i paketkonfigurationsfilen. Om du till exempel vill köra ett jobb med namnet hello_job i kontexten för standardmålet:

databricks bundle run hello_job

Så här kör du ett jobb med namnet hello_job inom kontexten för ett mål som deklarerats med namnet development:

databricks bundle run -t development hello_job

Mer information om bundle runfinns i Kör ett jobb eller en pipeline.

(Valfritt) Steg 8: Konfigurera paketet för CI/CD med GitHub

Om du använder GitHub för CI/CD kan du använda GitHub Actions för att köra databricks bundle deploy kommandona och databricks bundle run automatiskt, baserat på specifika GitHub-arbetsflödeshändelser och andra kriterier. Se Köra ett CI/CD-arbetsflöde med ett Databricks-tillgångspaket och GitHub Actions.

Konvertera dbx-projektinställningar till databricks.yml

För dbxär projektinställningarna som standard i en fil med namnet project.json i projektets .dbx mapp. Se Referens för Project-fil.

För paket är paketkonfigurationer som standard i en fil med namnet databricks.yml i paketets rotmapp. Se Konfiguration av Databricks-tillgångspaket.

För en conf/project.json fil med följande exempelinnehåll:

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

Motsvarande databricks.yml fil är följande:

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.

Följande objekt i det här exemplets föregående conf/project.json fil stöds inte i databricks.yml filer och har inga lösningar:

inplace_jinja_support
storage_type

Följande ytterligare tillåtna objekt i conf/project.json filer stöds inte i databricks.yml filer och har inga lösningar:

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

Konvertera dbx-distributionsinställningar till databricks.yml

För dbxär distributionsinställningarna som standard i en fil i projektets conf mapp. Se Referens för distributionsfil. Filen för distributionsinställningar har som standard något av följande filnamn:

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

För paket är distributionsinställningarna som standard i en fil med namnet databricks.yml i paketets rotmapp. Se Konfiguration av Databricks-tillgångspaket.

För en conf/deployment.yml fil med följande exempelinnehåll:

build:
  python: "pip"

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