Modelos de projeto do Databricks Asset Bundle

Artigo
10/15/2024

Este artigo descreve a sintaxe para modelos Databricks Asset Bundle . Os pacotes permitem o gerenciamento programático de fluxos de trabalho do Azure Databricks. 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 de ambiente de desenvolvimento.

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 seu loop de desenvolvimento criando um modelo de pacote que ofereça suporte a ambientes de contêiner personalizados.

Os modelos de pacote definem a estrutura de diretórios do pacote que será criado e incluem um databricks.yml.tmpl modelo de arquivo de configuração, bem como um databricks_template_schema.json arquivo contendo 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 Databricks CLIbundle 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 Python padrão:

databricks bundle init default-python

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

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

Modelo	Description
`default-python`	Um modelo para usar Python com Databricks. Este modelo cria um pacote com um trabalho e um pipeline Delta Live Tables. Consulte default-python.
`default-sql`	Um modelo para usar SQL com Databricks. Este modelo contém um arquivo de configuração que define um trabalho que executa consultas SQL em um SQL warehouse. Consulte default-sql.
`dbt-sql`	Um modelo que aproveita dbt-core para desenvolvimento local e pacotes para implantação. Este 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 dbt implantados. Consulte dbt-sql.
`mlops-stacks`	Um modelo de pilha completa avançado para iniciar novos projetos MLOps Stacks. Consulte mlops-stacks e Databricks Asset Bundles para MLOps Stacks.

Usar um modelo de pacote personalizado

Para usar 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 bundle init do Databricks.

Por exemplo, o comando a seguir usa o dab-container-template modelo 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 de pacote Go. Consulte a documentação do modelo de pacote Go.

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

Um databricks_template_schema.json arquivo na raiz do projeto que define uma variável de prompt do usuário para o nome do projeto do pacote.
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 arquivo fizer referência a include quaisquer modelos de configuração adicionais*.yml.tmpl, especifique o local deles no mapeamento.

Opcionalmente, você pode adicionar subpastas e arquivos à template pasta que deseja espelhar 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 nomeado 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 inito . O formato deste arquivo segue a especificação de esquema JSON.

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

Adicione o seguinte ao databricks_template_schema.json ficheiro e, em seguida, guarde-o:

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

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

Construir a estrutura de pastas

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

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

Adicione o seguinte ao simple_notebook.ipynb ficheiro:

print("Hello World!")

Preencher arquivos de modelo de configuração

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

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

Preencha este arquivo com o modelo de configuração básica YAML. Este modelo de configuração estabelece o nome do pacote, um trabalho usando o arquivo de bloco de anotações especificado e dois ambientes de destino para pacotes criados usando esse modelo. Também aproveita as substituições de pacotes, o que é altamente recomendado. Ver substituições de pacotes.

# 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 seu modelo. Crie uma nova pasta de projeto de pacote e, em seguida, 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

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
   └── src
      └── simple_notebook.ipynb

E o arquivo databricks.yml agora é 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 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.

Gorjeta

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

Próximos passos

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

Partilhar via

Modelos de projeto do Databricks Asset Bundle

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

Construir a estrutura de pastas

Preencher arquivos de modelo de configuração

Testar o modelo de pacote

Próximos passos

Comentários

Recursos adicionais

Partilhar via

Modelos de projeto do Databricks Asset Bundle

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

Construir a estrutura de pastas

Preencher arquivos de modelo de configuração

Testar o modelo de pacote

Partilhar o modelo

Próximos passos

Comentários

Recursos adicionais