Modelos de projeto do Databricks Asset Bundle

Os Databricks Asset Bundles descrevem recursos do Databricks, como trabalhos, pipelines e blocos de anotações, como arquivos de origem, permitem incluir metadados ao lado desses arquivos de origem para provisionar infraestrutura e outros recursos e fornecem uma definição completa de um projeto, tudo empacotado como um único projeto implantável. Consulte O que são Databricks Asset Bundles?.

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

Por exemplo, se você executar rotineiramente trabalhos do Databricks que exigem pacotes personalizados com uma etapa de compilação demorada após a instalação, poderá acelerar o loop de desenvolvimento criando um modelo de pacote que especifique um ambiente de contêiner personalizado.

O Databricks fornece um conjunto de modelos de pacote padrão, mas você também pode criar modelos de pacote personalizados. Os usuários podem então inicializar pacotes usando o comando bundle init, especificando um modelo padrão ou seu modelo personalizado.

Criar um pacote usando um modelo

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

databricks bundle init default-python

Para usar um modelo de pacote personalizado, passe o caminho local ou a URL remota do modelo para o comando bundle init da CLI do Databricks.

Por exemplo, o comando a seguir 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

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

Modelos de pacote padrão

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

Modelos de pacote personalizados

Os modelos de pacote usam a sintaxe de modelos de pacote Go, que fornece flexibilidade nos modelos de pacote personalizados que você pode criar. Consulte a documentação do modelo de pacote Go.

Estrutura do projeto de modelo

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

• Um ficheiro databricks_template_schema.json na raiz do projeto que define uma propriedade de solicitação do utilizador para o nome do projeto de pacote. Consulte Esquema de modelo.
• Um databricks.yml.tmpl arquivo localizado em uma template pasta que define a configuração para quaisquer pacotes criados com o modelo. Se o databricks.yml.tmpl ficheiro fizer referência a modelos de configuração *.yml.tmpl adicionais, especifique a localização destes no mapeamento include. Consulte Modelos de configuração.

Além disso, a estrutura das pastas e os arquivos incluídos do projeto de modelo de pasta do pacote template são refletidos nos pacotes criados com o modelo. Por exemplo, se você quiser que o modelo gere um pacote com um bloco de anotações simples na pasta src e uma definição de trabalho que execute o bloco de anotações na pasta resources, organize seu projeto de modelo da seguinte forma:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb

Esquema de modelo

Um projeto de modelo de pacote personalizado deve conter um arquivo JSON databricks_template_schema.json na raiz do projeto. Esse arquivo define campos usados pela CLI do Databricks quando o comando bundle init é executado, como texto de prompt.

O seguinte arquivo databricks_template_schema.json básico define uma variável de entrada project_name para o projeto de pacote, que inclui a mensagem de prompt e um valor padrão. Em seguida, ele define uma mensagem de êxito para a inicialização do projeto bunde que usa o valor da variável de entrada dentro da mensagem.

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

Campos do esquema de modelo

O arquivo databricks_template_schema.json suporta a definição de variáveis de entrada para coletar informações durante a inicialização do pacote do usuário dentro do campo properties, bem como campos adicionais para personalizar a inicialização.

As variáveis de entrada são definidas no campo properties do esquema do modelo. Cada variável de entrada define os metadados necessários para apresentar um prompt ao usuário durante a iniciação do pacote. O valor da variável é então acessível usando a sintaxe da variável de modelo, como {{.project_name}}.

Você também pode definir os valores de alguns campos para personalizar o processo de inicialização do pacote.

Os campos de esquema suportados estão listados na tabela a seguir.

Modelos de configuração

Um modelo de pacote personalizado deve conter um ficheiro de databricks.yml.tmpl numa pasta template no projeto de modelo de pacote, que é usado para criar o ficheiro de configuração do projeto de pacote databricks.yml. Modelos para arquivos de configuração para recursos podem ser criados na pasta resources. Preencha esses arquivos de modelo com o modelo de configuração YAML.

Os seguintes modelos simples de configuração de exemplo para databricks.yml e o *_job.yml associado estabelecem o nome do pacote e dois ambientes de implementação, e definem um trabalho que executa o notebook no pacote, para pacotes criados usando este modelo. Esses modelos de configuração tiram partido das substituições de pacotes com e dos auxiliares de modelo de pacotes com.

template/{{.project_name}}/databricks.yml.tmpl:

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

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

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

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.project_name}}_job.yml
# 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

Auxiliares de modelo e variáveis

Os auxiliares de modelo são funções fornecidas pelo Databricks que você pode usar em seus arquivos de modelo para obter informações específicas do usuário em tempo de execução ou interagir com o mecanismo de modelo. Você também pode definir suas próprias variáveis de modelo.

Os seguintes auxiliares de modelo estão disponíveis para projetos de modelo de pacote Databricks. Para obter informações sobre como usar modelos e variáveis Go, consulte Modelos Go.

Auxiliares de modelo personalizados

Para definir seus próprios auxiliares de modelo, crie um arquivo de modelo na pasta library do projeto de modelo e use a sintaxe de modelagem Go para definir auxiliares. Por exemplo, o conteúdo a seguir de um arquivo de library/variables.tmpl define as variáveis cli_version e model_name. Quando esse modelo é usado para inicializar um pacote, o valor da variável model_name é construído usando o campo input_project_name definido no arquivo de esquema do modelo. O valor desse valor de campo é a entrada do usuário após um prompt.

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

Para ver um exemplo completo, consulte o arquivo de variáveis de modelo mlops-stacks.

Testar o modelo de pacote

Finalmente, certifique-se de testar seu modelo. Por exemplo, use a CLI do Databricks para inicializar um novo pacote usando o modelo definido nas seções anteriores:

databricks bundle init basic-bundle-template

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

Depois que o pacote de teste é criado, a mensagem de sucesso do arquivo de esquema é saída. Se você examinar o my_test_bundle conteúdo da pasta, você verá o seguinte:

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

E o arquivo databricks.yml e o trabalho agora são personalizados:

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

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

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

# my_test_bundle_job.yml
# 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

Partilhar o modelo

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 bundle init comando com uma URL do Git, verifique se o databricks_template_schema.json arquivo está no local raiz relativo a essa URL do Git.

Próximos passos

• Procure modelos adicionais criados e mantidos pelo Databricks. Consulte o repositório de amostras do pacote no GitHub.
• Para usar as pilhas de MLOps com modelos de pacotes de ativos Databricks, consulte Pacotes de Ativos Databricks para Pilhas de MLOps.
• Saiba mais sobre a templatização de pacotes Go. Consulte a documentação do modelo de pacote Go.