Migrar de dbx para pacotes

Importante

O Databricks recomenda que você use os Pacotes de Ativos do Databricks em vez do dbx by Databricks Labs. Os artigos relacionados a dbx foram desativados e podem não estar atualizados.

Este artigo descreve como migrar projetos do dbx by Databricks Labs para os Pacotes de Ativos do Databricks. Confira Introdução ao dbx by Databricks Labs e O que são Pacotes de Ativos do Databricks?.

Antes de migrar, observe as limitações e as comparações de recursos a seguir entre o dbx by Databricks Labs e os Pacotes de Ativos do Databricks.

Comparações entre recursos

Antes de migrar, observe como os recursos do dbx by Databricks Labs a seguir são implementados nos Pacotes de Ativos do Databricks.

Modelos e projetos

dbx dá suporte à modelagem Jinja. Você pode incluir modelos Jinja na configuração de implantação e transmitir variáveis de ambiente em linha ou por meio de um arquivo de variáveis. Embora não seja recomendado, o dbx também dá suporte experimental a funções de usuário personalizadas.

Os pacotes dão suporte a modelos Go para reutilização de configuração. Os usuários podem criar pacotes com base em modelos predefinidos. Há uma paridade quase completa para modelagem, exceto em relação a funções de usuário personalizadas.

Gerenciamento do build

dbx dá suporte ao build por meio de pip wheel, Poetry e Flit. Os usuários podem especificar a opção de build na seção build do arquivo deployment.yml de um projeto.

Os pacotes permitem que os usuários criem, implantem e executem arquivos wheel do Python. Os usuários podem aproveitar a entrada interna whl no arquivo databricks.yml de um pacote.

Sincronizar, implantar e executar código

dbx permite carregar o código separadamente da geração de recursos de workspace, como tarefas do Lakeflow.

Os pacotes sempre carregam código e criam ou atualizam recursos de workspace ao mesmo tempo. Isso simplifica as implantações e evita o bloqueio de condições em trabalhos que já estão em andamento.

Migrar um projeto dbx para um pacote

Depois de observar as limitações e as comparações de recursos acima entre o dbx by Databricks Labs e os Pacotes de Ativos do Databricks, você já estará pronto para fazer a migração do dbx para os pacotes.

O Databricks recomenda que, para iniciar uma dbx migração de projeto, você mantenha seu dbx projeto em sua pasta original e que tenha uma pasta separada em branco na qual você copia o conteúdo do projeto original dbx . Essa pasta separada será seu novo pacote. Você poderá encontrar problemas inesperados se começar a converter o projeto dbx na pasta original em um pacote e, em seguida, cometer alguns erros ou desejar começar do zero.

Etapa 1: instalar e configurar a CLI do Databricks

Os Databricks Asset Bundles estão geralmente disponíveis na CLI do Databricks versão 0.218.0 e superior. Se você já instalou e configurou a CLI do Databricks versão 0.218.0 ou superior, vá para a Etapa 2.

Observação

Os pacotes não são compatíveis com as versões 0.18 ou inferiores da CLI do Databricks.

Instale ou atualize para a CLI do Databricks versão 0.218.0 ou superior. Confira Instalar ou atualizar a CLI do Databricks.
Configure a CLI do Databricks para autenticação com seus workspaces do Azure Databricks de destino, por exemplo, usando a autenticação de token de acesso pessoal (preterida). Para outros tipos de autenticação do Azure Databricks, consulte Autenticação para a CLI do Databricks.

Etapa 2: Criar o arquivo de configuração do pacote

Se você estiver usando um IDE, como Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate que fornece suporte para arquivos YAML e arquivos de esquema JSON, você pode usar o IDE não apenas para criar o arquivo de configuração do pacote, mas para verificar a sintaxe e a formatação do arquivo e fornecer dicas de conclusão de código, da seguinte maneira.

Visual Studio Code

Adicione suporte ao servidor de linguagem YAML ao Visual Studio Code, por exemplo, instalando a extensão YAML do Visual Studio Code Marketplace.
Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks para executar o comando bundle schema e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:
```
databricks bundle schema > bundle_config_schema.json
```
Use o Visual Studio Code para criar ou abrir um arquivo de configuração de pacote no diretório atual. Por convenção, esse arquivo é nomeado databricks.yml.
Adicione o seguinte comentário ao início do arquivo de configurações do pacote:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Observação

No comentário anterior, se o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks estiver em um caminho diferente, substitua bundle_config_schema.json pelo caminho completo para o arquivo de esquema.
Use os recursos do servidor de linguagem YAML adicionados anteriormente. Para obter mais informações, consulte a documentação do servidor de idiomas YAML.

PyCharm Professional

Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks para executar o comando bundle schema e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:
```
databricks bundle schema > bundle_config_schema.json
```
Configure o PyCharm para reconhecer o arquivo de esquema JSON de configuração de pacote e conclua o mapeamento de esquema JSON seguindo as instruções em Configurar um esquema JSON personalizado.
Use o PyCharm para criar ou abrir um arquivo de configuração de pacote. Por convenção, esse arquivo é nomeado databricks.yml. Conforme você digita, o PyCharm verifica a sintaxe e a formatação do esquema JSON e fornece dicas de conclusão de código.

IntelliJ IDEA Ultimate (Edição Premium)

Gere o arquivo de esquema JSON de configuração do Pacote de Ativos do Databricks usando a CLI do Databricks para executar o comando bundle schema e redirecionar a saída para um arquivo JSON. Por exemplo, gere um arquivo chamado bundle_config_schema.json no diretório atual, da seguinte maneira:
```
databricks bundle schema > bundle_config_schema.json
```
Configure o IntelliJ IDEA para reconhecer o arquivo de esquema JSON de configuração de pacote e conclua o mapeamento de esquema JSON seguindo as instruções em Configurar um esquema JSON personalizado.
Use o IntelliJ IDEA para criar ou abrir um arquivo de configuração de pacote. Por convenção, esse arquivo é nomeado databricks.yml. Conforme você digita, o IntelliJ IDEA verifica a sintaxe e a formatação do esquema JSON e fornece dicas de conclusão de código.

Etapa 3: converter configurações de projeto dbx em databricks.yml

Converta as configurações no arquivo dbx do projeto .dbx/project.json para as configurações equivalentes no arquivo databricks.yml do pacote. Para obter detalhes, consulte Converter as configurações do projeto dbx em databricks.yml.

Etapa 4: converter configurações de implantação dbx em databricks.yml

Converta as configurações da pasta dbx do projeto conf nas configurações equivalentes do arquivo databricks.yml do pacote. Para obter detalhes, consulte Converter as configurações de implantação dbx em databricks.yml.

Etapa 5: validar o pacote

Antes de implantar artefatos ou executar um trabalho do Azure Databricks, um pipeline :ou MLOps, você deverá verificar se o arquivo de configuração do pacote está sintaticamente correto. Para isso, execute o comando bundle validate na raiz do pacote:

databricks bundle validate

Para obter informações sobre bundle validate, consulte databricks bundle validate.

Etapa 6: implantar o pacote

Para implantar artefatos locais especificados (se for o caso) no workspace remoto, execute o comando bundle deploy na raiz do pacote. Se nenhuma opção de comando for especificada, será usado o destino padrão declarado no arquivo de configuração do pacote:

databricks bundle deploy

Para implantar os artefatos no contexto de um destino específico, especifique a opção -t (ou --target) junto com o nome do destino, conforme declarado no arquivo de configuração do pacote. Por exemplo, para um destino declarado com o nome development:

databricks bundle deploy -t development

Para obter informações sobre bundle deploy, consulte databricks bundle deploy.

Dica

Você pode vincular os trabalhos e pipelines definidos por pacotes aos trabalhos e pipelines existentes no workspace do Azure Databricks para mantê-los em sincronia. Consulte associação de implantação do pacote do Databricks.

Etapa 7: executar o pacote

Para executar um trabalho ou pipeline específico, execute o comando bundle run na raiz do pacote. Você deve especificar o trabalho ou o pipeline declarado no arquivo de configuração do pacote. Se a opção -t não for especificada, será usado o destino padrão, conforme declarado no arquivo de configuração do pacote. Por exemplo, para executar um trabalho chamado hello_job dentro do contexto do destino padrão:

databricks bundle run hello_job

Para executar um trabalho chamado hello_job dentro do contexto de um destino declarado com o nome development:

databricks bundle run -t development hello_job

Para obter informações sobre bundle run, consulte o comando do pacote do Databricks.

(Opcional) Etapa 8: configurar o pacote para CI/CD com o GitHub

Se você usar o GitHub para CI/CD, poderá usar o GitHub Actions para executar os comandos databricks bundle deploy e databricks bundle run automaticamente com base em eventos específicos do fluxo de trabalho do GitHub e em outros critérios. Consulte o GitHub Actions.

Convertendo configurações de projeto dbx em databricks.yml

Para dbx, as configurações de projeto são por padrão em um arquivo nomeado project.json na pasta do .dbx projeto. Consulte a Referência do arquivo de projeto.

Para pacotes, as configurações de pacote são por padrão em um arquivo nomeado databricks.yml dentro da pasta raiz do pacote. Consulte Configurações do Pacote de Ativos do Databricks.

Para um arquivo conf/project.json com o seguinte conteúdo de exemplo:

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

O arquivo databricks.yml correspondente é o seguinte:

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.

Os seguintes objetos no arquivo anterior conf/project.json deste exemplo não têm suporte em databricks.yml arquivos e não têm soluções alternativas:

inplace_jinja_support
storage_type

Os seguintes objetos permitidos adicionais nos arquivos conf/project.json não são compatíveis com arquivos databricks.yml e não existem soluções alternativas:

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

Convertendo configurações de implantação dbx em databricks.yml

Para dbx, as configurações de implantação são por padrão em um arquivo dentro da pasta do conf projeto. Consulte a Referência do arquivo de implantação. O arquivo de configurações de implantação têm, por padrão, um dos seguintes nomes de arquivo:

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

Para pacotes, as configurações de implantação são por padrão em um arquivo nomeado databricks.yml dentro da pasta raiz do pacote. Consulte Configurações do Pacote de Ativos do Databricks.

Para um arquivo conf/deployment.yml com o seguinte conteúdo de exemplo:

build:
  python: 'pip'

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