Pular para o conteúdo principal

Migre do dbx para pacotes

important

Databricks recomenda que o senhor use Databricks ativo Bundles em vez de dbx da Databricks Labs. Os artigos relacionados sobre dbx foram retirados e podem não ser atualizados.

Este artigo descreve como migrar projetos para dbx do Databricks Labs para Databricks ativo Bundles. Consulte Introdução ao dbx por Databricks Labs e O que são Databricks ativo Bundles?

Antes de migrar, observe as seguintes limitações e comparações de recursos entre dbx by Databricks Labs e Databricks ativo Bundles.

comparações de recursos​

Antes de migrar, observe como os seguintes recursos para dbx do Databricks Labs são implementados no Databricks ativo Bundles.

padrão e projetos​

dbx fornecer suporte para modelagem de Jinja. O senhor pode incluir o padrão Jinja na configuração da implantação e passar a variável de ambiente em linha ou por meio de um arquivo de variáveis. Embora não seja recomendado, o dbx também fornece suporte experimental para funções personalizadas do usuário.

Os pacotes oferecem suporte ao padrão Go para reutilização da configuração. Os usuários podem criar pacotes com base em padrões pré-construídos. Há uma paridade quase total para modelagem, exceto para funções de usuário personalizadas.

Gerenciamento de compilações​

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

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

Código de sincronização, implantação e execução​

dbx permite o upload de código separadamente da geração de workspace recurso, como Databricks Job.

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

Migrar um projeto dbx para um pacote​

Depois de observar as limitações anteriores e as comparações de recursos entre dbx da Databricks Labs e Databricks ativo Bundles, o senhor estará pronto para migrar de dbx para bundles.

A Databricks recomenda que, para iniciar uma migração do projeto dbx, o senhor mantenha o projeto dbx na pasta original e tenha uma pasta separada e em branco para a qual copie o conteúdo do projeto dbx original. Essa pasta separada será seu novo pacote. O senhor poderá encontrar problemas inesperados se começar a converter o projeto dbx em sua pasta original para um pacote e, em seguida, cometer alguns erros ou quiser recomeçar do início,

Etapa 1: Instalar e configurar a CLI da Databricks​

Databricks Os pacotes ativos estão geralmente disponíveis em Databricks CLI versão 0.218.0 e acima. Se o senhor já tiver instalado e configurado o Databricks CLI versão 0.218.0 ou acima, pule para a Etapa 2.

nota

Os pacotes não são compatíveis com Databricks CLI versões 0.18 e abaixo.

  1. Instale ou atualize para Databricks CLI versão 0.218.0 ou acima. Consulte Instalar ou atualizar a CLI da Databricks.
  2. Configure o Databricks CLI para autenticação com seu espaço de trabalho de destino Databricks, por exemplo, usando a autenticação de tokens de acesso pessoalDatabricks. Para outros tipos de autenticação do Databricks, consulte Autenticação para a CLI do Databricks.

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

Se estiver usando um IDE, como Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate, que ofereça suporte a arquivos YAML e arquivos de esquema JSON, o senhor poderá usar o IDE não apenas para criar o arquivo de configuração do pacote, mas também para verificar a sintaxe e a formatação do arquivo e fornecer dicas de autocompletar código, como segue.

  1. Add YAML language server support to Visual Studio Code, for example by installing the YAML extension from the Visual Studio Code Marketplace.

  2. Generate the Databricks Asset Bundle configuration JSON schema file by using the Databricks CLI to run the bundle schema command and redirect the output to a JSON file. For example, generate a file named bundle_config_schema.json within the current directory, as follows:

    Bash
    databricks bundle schema > bundle_config_schema.json

  3. Use Visual Studio Code to create or open a bundle configuration file within the current directory. By convention, this file is named databricks.yml.

  4. Add the following comment to the beginning of your bundle configuration file:

    YAML
    # yaml-language-server: $schema=bundle_config_schema.json
nota

In the preceding comment, if your Databricks Asset Bundle configuration JSON schema file is in a different path, replace bundle_config_schema.json with the full path to your schema file.

  1. Use the YAML language server features that you added earlier. For more information, see your YAML language server’s documentation.

Etapa 3: Converter as configurações do projeto dbx em databricks.yml​

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

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

Converta as configurações na pasta conf do seu projeto dbx para as configurações equivalentes no arquivo databricks.yml do seu pacote. Para obter detalhes, consulte Convertendo as configurações de implantação do dbx em databricks.yml.

Etapa 5: validar o pacote​

Antes de implantar artefatos ou executar um Databricks Job, um DLT pipeline, ou um MLOps pipeline, o senhor deve certificar-se de que o arquivo de configuração do pacote está sintaticamente correto. Para fazer isso, execute o comando bundle validate a partir da raiz do pacote:

Bash
databricks bundle validate

Para obter informações sobre bundle validate, consulte Validate a bundle (Validar um pacote).

Etapa 6: implantar o feixe​

Para implantar qualquer artefato local especificado no site remoto workspace, execute o comando bundle deploy na raiz do pacote. Se nenhuma opção de comando for especificada, será usado o destino default declarado no arquivo de configuração do pacote:

Bash
databricks bundle deploy

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

Bash
databricks bundle deploy -t development

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

dica

O senhor pode vincular o trabalho e o pipeline definidos pelo pacote ao trabalho e ao pipeline existentes no site Databricks workspace para mantê-los sincronizados. Consulte Bind bundle recurso.

Etapa 7: execução do pacote​

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

Bash
databricks bundle run hello_job

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

Bash
databricks bundle run -t development hello_job

Para obter informações sobre bundle run, consulte executar um Job ou pipeline.

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

Se o senhor usar GitHub para CI/CD, poderá usar GitHub Actions para executar os comandos databricks bundle deploy e databricks bundle run automaticamente, com base em eventos específicos de fluxo de trabalho GitHub e outros critérios. Veja a execução a CI/CD fluxo de trabalho com um Databricks ativo Bundle e GitHub Actions.

Convertendo as configurações do projeto dbx em databricks.yml​

Para dbx, as configurações do projeto estão em default em um arquivo denominado project.json na pasta .dbx do projeto. Consulte Referência do arquivo do projeto.

Para os pacotes, as configurações do pacote são default em um arquivo denominado databricks.yml na pasta raiz do pacote. Consulte Databricks ativo Bundle configuration.

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

JSON
{
  "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:

YAML
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 conf/project.json anterior deste exemplo não são suportados nos arquivos databricks.yml e não têm soluções alternativas:

  • inplace_jinja_support
  • storage_type

Os seguintes objetos adicionais permitidos nos arquivos conf/project.json não são suportados nos arquivos databricks.yml e não têm soluções alternativas:

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

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

Para dbx, as configurações de implantação estão em default em um arquivo na pasta conf do projeto. Consulte Referência do arquivo de implantação. O arquivo de configurações de implementação em default tem um dos seguintes nomes de arquivo:

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

Para os pacotes, as configurações de implantação estão em default em um arquivo denominado databricks.yml na pasta raiz do pacote. Consulte Databricks ativo Bundle configuration.

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

YAML
build:
  python: 'pip'

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

O arquivo databricks.yml correspondente é o seguinte:

YAML
bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      # See an example "workspace" mapping in the preceding section.
    resources:
      jobs:
        workflow1:
          tasks:
            - task_key: task1
              python_wheel_task:
                package_name: some-pkg
                entry_point: some-ep

O objeto a seguir no arquivo conf/deployment.yml anterior deste exemplo não tem suporte nos arquivos databricks.yml e não tem soluções alternativas:

Os seguintes objetos e funcionalidades adicionais permitidos nos arquivos conf/deployment.yml não são suportados nos arquivos databricks.yml e não têm soluções alternativas, a menos que seja indicado o contrário:

  • access_control_list
  • custom (em vez disso, use âncoras YAML padrão)
  • deployment_config
  • Formato Databricks Jobs 2.0 (em vez disso, use o formato Jobs 2.1)
  • dbx Recurso Jinja
  • Propriedades baseadas em nomes
Última atualização em