Modelos de projeto do Pacote de Ativos do Databricks

Artigo
09/19/2024

Este artigo descreve a sintaxe usada para os modelos do Pacote de Ativos do Databricks. Os pacotes permitem o gerenciamento programático de fluxos de trabalho do Azure Databricks. Confira O que são Pacotes de Ativos do Databricks?

Os modelos de pacote permitem que os usuários criem pacotes de maneira consistente e repetível, estabelecendo estruturas de pastas, tarefas e etapas de build, testes e outros atributos de IaC (infraestrutura como código) de DevOps comuns em um pipeline de implantação do ambiente de desenvolvimento.

Por exemplo, se você executa rotineiramente trabalhos do Databricks que exigem pacotes personalizados com uma etapa de compilação demorada na instalação, poderá acelerar o loop de desenvolvimento criando um modelo de pacote que tenha suporte para ambientes de contêineres personalizados.

Os modelos de pacote definem a estrutura de diretório do pacote que será criado e incluem um modelo de arquivo de configuração databricks.yml.tmpl, bem como um arquivo databricks_template_schema.json que contém variáveis de prompt do usuário.

Usar um modelo de pacote padrão

Para usar um modelo de pacote padrão do Azure Databricks para criar seu pacote, use o comando da CLI do Databricks bundle init, especificando o nome do modelo padrão a ser usado. Por exemplo, o comando a seguir cria um pacote usando o modelo de pacote do Python padrão:

databricks bundle init default-python

Se você não especificar um modelo padrão, o comando bundle init apresentará o conjunto de modelos disponíveis dentre os quais você poderá escolher.

O Azure Databricks fornece os seguintes modelos de pacote padrão:

Modelo	Descrição
`default-python`	Um modelo para usar o Python com o Databricks. Esse modelo cria um pacote com um trabalho e um pipeline de Delta Live Tables. Confira default-python.
`default-sql`	Um modelo para usar o SQL com o Databricks. Esse modelo contém um arquivo de configuração que define um trabalho que executa consultas SQL em um SQL warehouse. Confira default-sql.
`dbt-sql`	Um modelo que aproveita o dbt-core para desenvolvimento local e pacotes para implantação. Esse modelo contém a configuração que define um trabalho com uma tarefa dbt, bem como um arquivo de configuração que define perfis dbt para trabalhos de dbt implantados. Confira dbt-sql.
`mlops-stacks`	Um modelo de pilha completa avançado para iniciar novos projetos do MLOps Stacks. Confira mlops-stacks e Pacotes de ativos do Databricks para o MLOps Stacks.

Usar um modelo de pacote personalizado

Para utilizar um modelo de pacote diferente dos modelos de pacote padrão do Azure Databricks, passe o caminho local ou a URL remota do modelo para o comando da CLI do Databricks bundle init.

Por exemplo, o seguinte comando usa o modelo dab-container-template criado no tutorial de modelo de pacote personalizado:

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Criar um modelo de pacote personalizado

Os modelos de pacote usam a sintaxe de modelagem do pacote Go. Consulte a documentação do modelo de pacote Go

No mínimo, um projeto de modelo de pacote precisa ter:

Um arquivo databricks_template_schema.json na raiz do projeto que define uma variável de prompt de usuário para o nome do projeto do pacote.
Um arquivo databricks.yml.tmpl localizado em uma pasta template que define a configuração de todos os pacotes criados com o modelo. Se o arquivo databricks.yml.tmpl fizer referência a outros modelos de configuração de *.yml.tmpl, especifique o local deles no mapeamento de include.

Opcionalmente, você pode adicionar à pasta template subpastas e arquivos que deseja que sejam espelhados em pacotes criados pelo modelo.

Definir variáveis de prompt do usuário

A primeira etapa na criação de um modelo de pacote básico é criar uma pasta de projeto de modelo e um arquivo chamado databricks_template_schema.json na raiz do projeto. Esse arquivo contém as variáveis para as quais os usuários fornecem valores de entrada quando usam o modelo para criar um pacote usando bundle init. O formato desse arquivo segue a especificação de esquema JSON.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Adicione o seguinte ao arquivo databricks_template_schema.json e, em seguida, salve o arquivo:

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

Neste arquivo:

project_name é o único nome de variável de entrada.
default é um valor padrão opcional se um valor não é fornecido pelo usuário com --config-file como parte do comando bundle init ou substituído pelo usuário no prompt de comando.
description é o prompt do usuário associado à variável de entrada, se um valor não é fornecido pelo usuário com --config-file como parte do comando bundle init.
order é uma ordem opcional na qual cada prompt de usuário é exibido, se um valor não é fornecido pelo usuário com --config-file como parte do comando bundle init. Se order não for fornecido, os prompts do usuário serão exibidos na ordem em que estiverem listados no esquema.
success_message é uma mensagem opcional exibida após a criação bem-sucedida do projeto.

Criar a estrutura de pastas

Em seguida, crie a pasta template necessária e crie a estrutura de pastas dentro dela. Essa estrutura será espelhada por pacotes criados com esse modelo. Além disso, coloque todos os arquivos que você deseja incluir nessas pastas. Este modelo de pacote básico armazena arquivos em uma pasta src e inclui um notebook simples.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Adicione o seguinte ao arquivo simple_notebook.ipynb:

print("Hello World!")

Preencher arquivos do modelo de configuração

Agora, crie o arquivo databricks.yml.tmpl necessário na pasta template:

touch basic-bundle-template/template/databricks.yml.tmpl

Preencha esse arquivo com o modelo de configuração básico YAML. Esse modelo de configuração estabelece o nome do pacote, um trabalho usando o arquivo de notebook especificado e dois ambientes de destino para pacotes criados usando esse modelo. Ele também aproveita as substituições de pacote, o que é altamente recomendado. Consulte substituições de pacote.

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

Testar o modelo de pacote

Por fim, teste o modelo. Crie uma pasta de projeto de pacote e use a CLI do Databricks para inicializar um novo pacote usando o modelo:

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

No prompt What is your bundle project name?, digite my_test_bundle.

Depois que o pacote de teste é criado, a mensagem de êxito do arquivo de esquema é a saída. Se você examinar o conteúdo da pasta my-test-bundle, deverá ver o seguinte:

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

E o arquivo databricks.yml agora está personalizado:

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

Se você quiser compartilhar esse modelo de pacote com outras pessoas, poderá armazená-lo no controle de versão com qualquer provedor que o Git ofereça suporte e ao qual seus usuários tenham acesso. Para executar o comando bundle init com uma URL do Git, verifique se o arquivo databricks_template_schema.json está no local raiz relativo a essa URL do Git.

Dica

Você pode colocar o arquivo databricks_template_schema.json em uma pasta diferente, em relação à raiz do pacote. Em seguida, você pode usar a opção --template-dir do comando bundle init para fazer referência a essa pasta, que contém o arquivo databricks_template_schema.json.

Próximas etapas

Procure modelos adicionais que sejam criados e mantidos pelo Databricks. Consulte o repositório de amostras de pacote no GitHub.
Para usar o MLOps Stacks com modelos do Pacote de Ativos do Databricks, consulte Pacotes de Ativos do Databricks para o MLOps Stacks.
Saiba mais sobre a modelagem do pacote Go. Consulte a documentação do modelo de pacote Go

Compartilhar via

Modelos de projeto do Pacote de Ativos do Databricks

Usar um modelo de pacote padrão

Usar um modelo de pacote personalizado

Criar um modelo de pacote personalizado

Definir variáveis de prompt do usuário

Criar a estrutura de pastas

Preencher arquivos do modelo de configuração

Testar o modelo de pacote

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Modelos de projeto do Pacote de Ativos do Databricks

Usar um modelo de pacote padrão

Usar um modelo de pacote personalizado

Criar um modelo de pacote personalizado

Definir variáveis de prompt do usuário

Criar a estrutura de pastas

Preencher arquivos do modelo de configuração

Testar o modelo de pacote

Compartilhar o modelo

Próximas etapas

Comentários

Recursos adicionais