Desenvolver um trabalho em Databricks usando Databricks ativo Bundles

Databricks ativo Bundles, também conhecidos simplesmente como bundles, contêm os artefatos que o senhor deseja implantar e as configurações de Databricks recurso, como o Job, que deseja executar, e permitem que o senhor os valide, implante e execute de forma programática. O senhor também pode usar os pacotes para gerenciar programaticamente o pipeline Delta Live Tables e trabalhar com as pilhas MLOps. Veja o que são Databricks ativo Bundles?

Este artigo descreve como criar um pacote para gerenciar programaticamente um trabalho. Veja programar e orquestrar fluxo de trabalho. O pacote é criado usando o Databricks ativo Bundles default bundle padrão para Python, que consiste em um Notebook emparelhado com a definição de um Job para executá-lo. Em seguida, o senhor valida, implanta e executa o Job implantado em seu site Databricks workspace.

Dica

Se o senhor tiver trabalhos existentes que foram criados usando a interface de usuário Databricks Jobs ou API e quiser movê-los para pacotes, deverá defini-los nos arquivos de configuração de um pacote. Databricks recomenda que o senhor crie primeiro um pacote usando os passos abaixo e depois valide se o pacote funciona. Em seguida, o senhor pode adicionar outras definições de trabalho, Notebook e outras fontes ao pacote. Consulte Adicionar uma definição de trabalho existente a um pacote.

Além de usar o Databricks CLI para executar um trabalho implantado por um pacote, o senhor também pode view e executar esse trabalho na UI Databricks Jobs. Veja a visualização e execução de um Job criado com um Databricks ativo Bundle.

Requisitos

Criar um pacote usando um padrão de projeto

Este tutorial cria um pacote usando o Databricks ativo Bundles default Python padrão. Para obter mais informações sobre o padrão bundle, consulte Databricks ativo Bundle project padrão.

Se você quiser criar um pacote do zero, consulte Criar um pacote manualmente.

o passo 1: Configurar a autenticação

Neste passo, o senhor configura a autenticação entre o Databricks CLI em sua máquina de desenvolvimento e o Databricks workspace. Este artigo pressupõe que o senhor deseja usar a autenticação OAuth user-to-machine (U2M) e um perfil de configuração Databricks correspondente denominado DEFAULT para autenticação.

Observação

A autenticação U2M é adequada para experimentar esses passos em tempo real. Para fluxo de trabalho totalmente automatizado, o site Databricks recomenda que o senhor use a autenticação máquina a máquina (M2M) OAuth. Consulte as instruções de configuração da autenticação M2M em Autenticação.

  1. Use a CLI do Databricks para iniciar o gerenciamento de tokens OAuth localmente executando o seguinte comando para cada workspace de destino.

    No comando a seguir, substitua <workspace-url> pelo URL da instância do seu workspace do Databricks, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com.

    databricks auth login --host <workspace-url>

  2. O site Databricks CLI solicita que o senhor salve as informações inseridas como um Databricks perfil de configuração. Pressione Enter para aceitar o nome de perfil sugerido ou insira o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome é substituído pelas informações que o senhor inseriu. O senhor pode usar perfis para alternar rapidamente o contexto de autenticação em vários espaços de trabalho.

    Para obter uma lista de todos os perfis existentes, em um terminal ou prompt de comando separado, use a CLI do Databricks para executar o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

  3. No navegador da web, conclua as instruções na tela para fazer log in no workspace do Databricks.

  4. Para visualizar o valor atual do token OAuth de um perfil e o registro de data e hora de expiração do token, execute um dos seguintes comandos:

    • databricks auth token --host <workspace-url>

    • databricks auth token -p <profile-name>

    • databricks auth token --host <workspace-url> -p <profile-name>

    Se você tiver vários perfis com o mesmo valor --host, talvez seja necessário especificar as opções --host e -p juntas para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

o passo 2: Inicializar o pacote

Em seguida, crie um pacote usando o padrão de projeto default Python bundle.

  1. Use o terminal ou o prompt do comando para alternar para um diretório em seu computador de desenvolvimento local que conterá o pacote gerado pelo padrão.

  2. Use o endereço Databricks CLI para executar o comando bundle init:

    databricks bundle init

  3. Para Template to use, deixe o valor default de default-python pressionando Enter.

  4. Para Unique name for this project, deixe o valor default de my_project ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz desse pacote. Esse diretório raiz é criado em seu diretório de trabalho atual.

  5. Para Include a stub (sample) notebook, selecione yes e pressione Enter.

  6. Para Include a stub (sample) DLT pipeline, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não definir um pipeline de amostra do Delta Live Tables em seu pacote.

  7. Para Include a stub (sample) Python package, selecione no e pressione Enter. Isso instrui a CLI da Databricks a não adicionar arquivos de amostra do pacote Python wheel ou instruções de compilação relacionadas ao seu pacote.

o passo 3: Explore o pacote

Para acessar view os arquivos gerados pelo padrão, vá para o diretório raiz do pacote recém-criado e abra esse diretório com seu IDE preferido, por exemplo, o Visual Studio Code. Os arquivos de interesse particular incluem o seguinte:

  • databricks.yml: Esse arquivo especifica o nome programático do pacote, inclui uma referência à definição do trabalho e especifica as configurações sobre o destino workspace.

  • resources/<project-name>_job.yml: Esse arquivo especifica as configurações do trabalho, incluindo uma tarefa do default Notebook.

  • src/notebook.ipynb: Esse arquivo é um exemplo de Notebook que, quando executado, simplesmente inicializa um RDD que contém os números de 1 a 10.

Para personalizar o trabalho, os mapeamentos em uma declaração de trabalho correspondem à carga útil da solicitação, expressa no formato YAML, das operações de criação de trabalho, conforme documentado em POST /api/2.1/Job/create na referência REST API .

Dica

Você pode definir, combinar e substituir as configurações de novos clusters de jobs em pacotes usando as técnicas descritas em Substituir configurações de cluster nos Pacotes de Ativos do Databricks.

o passo 4: Validar o arquivo de configuração do pacote do projeto

Neste passo, o senhor verifica se a configuração do pacote é válida.

  1. No diretório raiz, use o endereço Databricks CLI para executar o comando bundle validate, como segue:

    databricks bundle validate

  2. Se um resumo da configuração do pacote for retornado, a validação foi bem-sucedida. Se algum erro for retornado, corrija os erros e repita este passo.

Se o senhor fizer alguma alteração no pacote após esse passo, deverá repetir esse passo para verificar se a configuração do pacote ainda é válida.

o passo 5: implantado o projeto local no remoto workspace

Neste passo, o senhor implantou o Notebook local em seu Databricks workspace remoto e criou o Databricks Job em seu workspace.

  1. Na raiz do pacote, use o endereço Databricks CLI para executar o comando bundle deploy da seguinte forma:

    databricks bundle deploy -t dev

  2. Verifique se o Notebook local foi implantado: Na barra lateral do workspace do Databricks, clique em workspace.

  3. Clique na pasta Users > <your-username> > .bundle > <project-name> > dev > files > src. O Notebook deve estar nessa pasta.

  4. Verifique se o Job foi criado: Na barra lateral do workspace do Databricks, clique em fluxo de trabalho.

  5. No site Jobs tab, clique em [dev <your-username>] <project-name>_job.

  6. Clique na tarefa tab. Deve haver uma tarefa: Notebook.

Se o senhor fizer alguma alteração no pacote após esse passo, deverá repetir os passos 4-5 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplantar o projeto.

o passo 6: execução do projeto implantado

Nesta passo, você executa o Job do Databricks em seu workspace.

  1. No diretório raiz, use o endereço Databricks CLI para executar o comando bundle run, como segue, substituindo <project-name> pelo nome do projeto do passo 2:

    databricks bundle run -t dev <project-name>_job

  2. Copie o valor de Run URL que aparece no terminal e cole-o no navegador da Web para abrir o site Databricks workspace.

  3. Em seu site Databricks workspace, depois que a tarefa do trabalho for concluída com êxito e mostrar uma barra de título verde, clique na tarefa do trabalho para ver os resultados.

Se o senhor fizer alguma alteração no pacote após esse passo, deverá repetir os passos 4 a 6 para verificar se a configuração do pacote ainda é válida, reimplantar o projeto e executar o projeto reimplantado.

o passo 7: Limpeza

Neste passo, o senhor exclui o Notebook implantado e o Job do seu site workspace.

  1. No diretório raiz, use o endereço Databricks CLI para executar o comando bundle destroy, como segue:

    databricks bundle destroy

  2. Confirme a solicitação de exclusão do trabalho: Quando solicitado a destruir permanentemente o recurso, digite y e pressione Enter.

  3. Confirme a solicitação de exclusão do Notebook: Quando solicitado a destruir permanentemente a pasta implantada anteriormente e todos os seus arquivos, digite y e pressione Enter.

  4. Se o senhor também quiser excluir o pacote da máquina de desenvolvimento, poderá excluir o diretório local do passo 2.

Adicionar uma definição de trabalho existente a um pacote

O senhor pode usar um Job existente como base para definir um Job em um arquivo de configuração de pacote. Para obter uma definição de trabalho existente, o senhor pode recuperá-la manualmente usando a interface do usuário ou pode gerá-la programaticamente usando o site Databricks CLI.

Para obter informações sobre a definição de trabalho em pacotes, consulte Trabalho.

Obter uma definição de trabalho existente usando a UI

Para obter a representação YAML de uma definição de trabalho existente na interface do usuário Databricks workspace :

  1. Na barra lateral do site Databricks workspace , clique em fluxo de trabalho.

  2. No site Jobs tab, clique no link Job's Name (Nome do trabalho).

  3. Ao lado do botão Executar agora, clique no botão e, em seguida, clique em Alternar para código (YAML).

  4. Em Create tab, copie o YAML da definição do trabalho para a área de transferência local clicando em Copy.

No arquivo de configuração do pacote, adicione o YAML que o senhor copiou à configuração do pacote onde o Job está definido:

resources:
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      <job-yaml>

targets:
  dev:
    resources:
      jobs:
        <some-unique-programmatic-identifier-for-this-job>:
          <job-yaml>

Em seguida, acesse download e adicione todos os arquivos Python e o Notebook referenciados no Job existente à fonte do projeto do pacote. Normalmente, os artefatos do pacote estão no diretório src/ em um pacote.

O senhor pode exportar um Notebook existente de um Databricks workspace para o formato .ipynb clicando em File > Export > IPython Notebook na interface do usuário do Databricks Notebook.

Depois de adicionar o Notebook, os arquivos Python e outros artefatos ao pacote, certifique-se de que a definição do trabalho os referencie adequadamente. Por exemplo, para um Notebook chamado hello.ipynb que está no diretório src/ do pacote:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
      - task_key: hello-task
        notebook_task:
          notebook_path: ./src/hello.ipynb

Gerar uma definição de trabalho existente usando o site Databricks CLI

Para gerar programaticamente a configuração do pacote para um trabalho existente:

  1. Obtenha o ID do trabalho existente no painel lateral de detalhesJob do trabalho na interface do usuário de trabalhos ou use o comando Databricks CLI databricks jobs list.

  2. executar o bundle generate job Databricks CLI comando, definindo o ID do trabalho:

databricks bundle generate job --existing-job-id 6565621249

Esse comando cria um arquivo de configuração de pacote para o Job na pasta resources do pacote.

Dica

Se o senhor usar bundle deployment bind pela primeira vez para vincular um recurso em um pacote a um recurso no site workspace, o recurso no site workspace será atualizado com base na configuração definida no pacote ao qual está vinculado após o próximo bundle deploy. Para obter informações sobre bundle deployment bind, consulte Bind bundle recurso.

Configurar um trabalho que usa o site serverless compute

Os exemplos a seguir demonstram as configurações do pacote para criar um trabalho que usa o site serverless compute.

Para usar o site serverless compute para executar um trabalho que inclua a tarefa Notebook, omita a configuração job_clusters do arquivo de configuração do pacote.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job-serverless:
      name: retrieve-filter-baby-names-job-serverless
      tasks:
        - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          notebook_task:
            notebook_path: ./filter-baby-names.py

  targets:
    development:
      workspace:
        host: <workspace-url>

Para usar serverless compute para executar um trabalho que inclua Python tarefa, inclua a configuração environments.

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: serverless-python-tasks

resources:
jobs:
  serverless-python-job:
    name: serverless-job-with-python-tasks

    tasks:
      - task_key: wheel-task-1
        python_wheel_task:
          entry_point: main
          package_name: wheel_package
        environment_key: Default

    environments:
      - environment_key: Default
        spec:
          client: "1"
          dependencies:
            - workflows_authoring_toolkit==0.0.1

targets:
  development:
    workspace:
      host: <workspace-url>

Consulte Executar seu job do Databricks com computação serverless para fluxos de trabalho.