Pular para o conteúdo principal
Última atualização em

Migre do dbx para pacotes

importante

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 LakeFlow Jobs.

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 Databricks de destino, por exemplo, usando a autenticação de tokens de acesso pessoal (obsoleta). 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. Adicione suporte ao servidor de linguagem YAML ao Visual Studio Code, por exemplo, instalando a extensão YAML do Visual Studio Code marketplace.

  2. Gere o arquivo de esquema de configuração do Databricks ativo Bundle JSON usando o Databricks CLI para executar o bundle schema comando 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 forma:

    Bash
    databricks bundle schema > bundle_config_schema.json

  3. 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 tem o nome databricks.yml.

  4. Adicione o seguinte comentário ao início do arquivo de configuração do pacote:

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

No comentário anterior, se o arquivo de esquema Databricks ativo Bundle configuration JSON estiver em um caminho diferente, substitua bundle_config_schema.json pelo caminho completo do arquivo de esquema.

  1. Use o recurso de servidor de linguagem YAML que o senhor adicionou anteriormente. Para obter mais informações, consulte a documentação do seu servidor de linguagem YAML.

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 :, 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 databricks bundle validate.

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 o pacote implantado no, consulte o pacote implantado no databricks.

dica

É possível vincular o trabalho e o pipeline definidos no pacote a um trabalho e pipeline existentes no Databricks workspace para mantê-los sincronizados. Consulte o vínculo de implantação do pacote databricks.

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 o pacote bundle run de execução do, consulte pacote de execução do Databricks.

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

Se você 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 do fluxo de trabalho GitHub e outros critérios. Veja GitHub Actions.

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

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

Para os pacotes, as configurações do pacote são feitas por default em um arquivo chamado 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 são feitas por 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

No caso dos 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
  • LakeFlow Formato Jobs 2.0 (em vez disso, use o formato Jobs 2.1)
  • dbx Recurso Jinja
  • Propriedades baseadas em nomes