Compartilhar via

Recursos dos Pacotes de Ativos do Databricks

  • Artigo

Os Pacotes de Ativos do Databricks permitem especificar informações sobre os recursos do Azure Databricks usados pelo pacote no mapeamento de resources na configuração do pacote. Confira o mapeamento dos recursos e a referência de chave dos recursos.

Este artigo descreve os tipos de recursos com suporte para pacotes e fornece detalhes e um exemplo para cada tipo com suporte. Para obter exemplos adicionais, confira Exemplos de configuração do pacote.

Dica

Para gerar YAML para qualquer recurso existente, use o comando databricks bundle generate. Confira Gerar um arquivo de configuração de pacote.

Recursos com suporte

A tabela a seguir lista os tipos de recursos com suporte para pacotes. Alguns recursos podem ser criados definindo-os em um pacote e implantando o pacote, e alguns recursos só dão suporte à referência a um recurso existente para incluir no pacote.

Os recursos são definidos usando a carga útil da solicitação de operação de criação do objeto da API REST do Databricks, em que os campos com suporte do objeto, expressos como YAML, são as propriedades com suporte do recurso. Os links para a documentação dos conteúdos correspondentes de cada recurso são listados na tabela.

Dica

O comando databricks bundle validate retornará avisos se propriedades de recurso desconhecidas forem encontradas em arquivos de configuração de pacote.

Recurso Criar suporte Objeto da API REST correspondente
app ✓ Objeto de aplicativo
cluster ✓ objeto de cluster
dashboard Objeto de painel
experiment ✓ Objeto de experimento
job ✓ Objeto de trabalho
modelo (herdado) ✓ Objeto de modelo (herdado)
model_serving_endpoint ✓ Objeto de Ponto de extremidade do Serviço de Modelo
pipeline ✓ [Objeto de pipeline]](https://docs.databricks.com/api/azure/workspace/pipelines/create)
quality_monitor ✓ objeto de monitor de qualidade
registered_model (Catálogo do Unity) ✓ objeto de modelo registrado
schema (Catálogo do Unity) ✓ Objeto de esquema
volume (Catálogo do Unity) ✓ Objeto de volume

aplicação

O recurso de aplicativo define um aplicativo Databricks. Para obter informações sobre os Aplicativos do Databricks, consulte O que são os Aplicativos do Databricks?.

Dica

Você pode inicializar um pacote com um aplicativo Streamlit Databricks usando o seguinte comando:

databricks bundle init https://github.com/databricks/bundle-examples --template-dir contrib/templates/streamlit-app

Para adicionar um aplicativo, especifique os campos de objeto que definem o aplicativo, bem como o seguinte:

  • source_code_path - O caminho local ./app do código-fonte do aplicativo Databricks. Esse campo é necessário.
  • config – Os comandos de configuração do aplicativo e as variáveis de ambiente. Você pode usá-lo para especificar diferentes destinos de implantação de aplicativo.

Exemplo

O exemplo a seguir cria um aplicativo chamado my_app que gerencia um trabalho criado pelo pacote:

resources:
  jobs:
    # Define a job in the bundle
    hello_world:
      name: hello_world
      tasks:
        - task_key: task
          spark_python_task:
            python_file: ../src/main.py
          environment_key: default

      environments:
        - environment_key: default
          spec:
            client: "1"

  # Define an app that manages the job in the bundle
  apps:
    job_manager:
      name: "job_manager_app"
      description: "An app which manages a job created by this bundle"

      # The location of the source code for the app
      source_code_path: ../src/app

      # The configuration for running the app
      config:
        command:
          - flask
          - --app
          - app
          - run
          - --debug
        env:
          - name: JOB_ID
            value: ${resources.jobs.hello_world.id}

      # The resources in the bundle which this app has access to. This binds the resource in the app with the DABs resource.
      resources:
        - name: "app-job"
          job:
            id: ${resources.jobs.hello_world.id}
            permission: "CAN_MANAGE_RUN"

Para obter o pacote de exemplo completo do aplicativo Databricks, confira o Repositório do GitHub de exemplos de pacote.

cluster

O recurso de cluster define um cluster de uso geral .

Exemplo

O exemplo a seguir cria um cluster chamado my_cluster e define isso como o cluster a ser usado para executar o notebook no my_job:

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          notebook_task:
            notebook_path: "./src/my_notebook.py"

dashboard

O recurso de painel permite que você gerencie painéis de IA/BI em um pacote. Para obter informações sobre dashboards de IA/BI, consulte Dashboards.

Exemplo

O exemplo a seguir inclui e implanta o painel Análise de viagens de táxi em NYC de exemplo no workspace do Databricks.

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

Se você usar a interface do usuário para modificar o painel, as modificações feitas por meio da interface do usuário não serão aplicadas ao arquivo JSON do painel no pacote local, a menos que você o atualize explicitamente usando bundle generate. Você pode usar a opção --watch para sondar e recuperar continuamente as alterações no painel. Confira Gerar um arquivo de configuração de pacote.

Além disso, se você tentar implantar um pacote que contenha um arquivo JSON de painel diferente daquele no workspace remoto, ocorrerá um erro. Para forçar a implantação e substituir o painel no workspace remoto pelo painel local, use a opção --force. Confira Implantar um pacote.

experimentar

O recurso de experimento permite que você defina experimentos do MLflow em um pacote. Para obter informações sobre experimentos do MLflow, consulte Organizar execuções de treinamento com experimentos do MLflow.

Exemplo

O exemplo a seguir define um experimento que todos os usuários podem exibir:

resources:
  experiments:
    experiment:
      name: my_ml_experiment
      permissions:
        - level: CAN_READ
          group_name: users
      description: MLflow experiment used to track runs

emprego

O recurso de tarefas permite que você defina trabalhos e suas tarefas correspondentes no seu pacote. Para obter informações sobre trabalhos, confira Visão geral da orquestração no Databricks. Para obter um tutorial que usa um modelo de Pacotes de Ativos do Databricks para criar um trabalho, consulte Desenvolver um trabalho no Azure Databricks usando pacotes de ativos do Databricks.

Exemplo

O exemplo a seguir define um trabalho com a chave de recurso hello-job com uma tarefa de notebook:

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

Para obter informações sobre como definir tarefas de trabalho e substituir configurações de trabalho, consulte Adicionar Tarefas a Trabalhos nos Pacotes de Ativos do Databricks, Substituir Configurações de Tarefas de Trabalho nos Pacotes de Ativos do Databrickse Substituir as Configurações de Cluster nos Pacotes de Ativos do Databricks.

modelo (herdado)

O recurso de modelo permite definir modelos herdados em pacotes. O Databricks recomenda que, em vez disso, você use o Catálogo do Unity com os modelos registrados.

model_serving_endpoint

O recurso model_serving_endpoint permite que você defina um modelo que atende pontos de extremidade. Confira Gerenciar modelo que atende pontos de extremidade.

Exemplo

O exemplo a seguir define um modelo do Catálogo do Unity que serve o ponto de extremidade:

resources:
  model_serving_endpoints:
    uc_model_serving_endpoint:
      name: "uc-model-endpoint"
      config:
        served_entities:
        - entity_name: "myCatalog.mySchema.my-ads-model"
          entity_version: "10"
          workload_size: "Small"
          scale_to_zero_enabled: "true"
        traffic_config:
          routes:
          - served_model_name: "my-ads-model-10"
            traffic_percentage: "100"
      tags:
      - key: "team"
        value: "data science"

quality_monitor (Catálogo do Unity)

O recurso quality_monitor permite que você defina um monitoramento de tabela do Catálogo do Unity. Para obter informações sobre monitores, confira Qualidade do modelo de monitoramento e integridade do ponto de extremidade.

Exemplo

O exemplo a seguir define um monitor de qualidade:

resources:
  quality_monitors:
    my_quality_monitor:
      table_name: dev.mlops_schema.predictions
      output_schema_name: ${bundle.target}.mlops_schema
      assets_dir: /Users/${workspace.current_user.userName}/databricks_lakehouse_monitoring
      inference_log:
        granularities: [1 day]
        model_id_col: model_id
        prediction_col: prediction
        label_col: price
        problem_type: PROBLEM_TYPE_REGRESSION
        timestamp_col: timestamp
      schedule:
        quartz_cron_expression: 0 0 8 * * ? # Run Every day at 8am
        timezone_id: UTC

registered_model (Catálogo do Unity)

O recurso de modelo registrado permite que você defina modelos no Catálogo do Unity. Para obter informações sobre modelos registrados do Catálogo do Unity, confira Gerenciar o ciclo de vida do modelo no Catálogo do Unity.

Exemplo

O exemplo a seguir define um modelo registrado no Catálogo do Unity:

resources:
  registered_models:
      model:
        name: my_model
        catalog_name: ${bundle.target}
        schema_name: mlops_schema
        comment: Registered model in Unity Catalog for ${bundle.target} deployment target
        grants:
          - privileges:
              - EXECUTE
            principal: account users

pipeline

O recurso de pipeline permite que você crie pipelines de Delta Live Tables. Para obter informações sobre pipelines, consulte o tópico O que é o Delta Live Tables?. Para obter um tutorial que usa o modelo de Pacotes de Ativos do Databricks para criar um pipeline, confira Desenvolver pipelines de Delta Live Tables com Pacotes de Ativos do Databricks.

Exemplo

O exemplo a seguir define um pipeline com a chave de recurso hello-pipeline:

resources:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

schema (Catálogo do Unity)

O tipo de recurso de esquema permite que você defina esquemas do Catálogo do Unity para tabelas e outros ativos em seus fluxos de trabalho e pipelines criados como parte de um pacote. Um esquema, diferente de outros tipos de recursos, tem as seguintes limitações:

  • O proprietário de um recurso de esquema é sempre o usuário de implantação e não pode ser alterado. Se estiver especificado no pacote, run_as será ignorado pelas operações no esquema.
  • Somente os campos compatíveis com a API de criação do objeto de esquemas correspondente estão disponíveis para o recurso de esquema. Por exemplo, não há suporte para enable_predictive_optimization, pois ele só está disponível no da API de atualização.

Exemplos

O exemplo a seguir define um pipeline com a chave de recurso my_pipeline que cria um esquema do Catálogo do Unity com a chave my_schema como destino:

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

Não há suporte para um mapeamento de permissões de nível superior nos Pacotes de Ativos do Databricks, portanto, se você quiser definir permissões para um esquema, defina-as dentro do mapeamento schemas. Para obter mais informações sobre concessões, confira Mostrar, conceder e revogar privilégios.

O exemplo a seguir define um esquema do Catálogo do Unity com concessões:

resources:
  schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - SELECT
        - principal: my_team
          privileges:
            - CAN_MANAGE
      catalog_name: main

volume (Catálogo do Unity)

O tipo de recurso de volume permite que você defina e crie volumes do Unity Catalog como parte de um conjunto. Ao implantar um pacote com um volume definido, observe que:

  • Um volume não pode ser referenciado no artifact_path do conjunto até que ele exista no espaço de trabalho. Portanto, se você quiser usar os Pacotes de Ativos do Databricks para criar o volume, primeiro defina o volume no pacote, implante-o para criar o volume e, em seguida, referencie-o no artifact_path em implantações subsequentes.
  • Os volumes no pacote não são precedidos pelo prefixo dev_${workspace.current_user.short_name} quando o destino de implantação está configurado com mode: development. No entanto, você pode configurar manualmente esse prefixo. Confira Predefinições personalizadas.

Exemplo

O exemplo a seguir cria um volume do Catálogo do Unity com a chave my_volume:

resources:
  volumes:
    my_volume:
      catalog_name: main
      name: my_volume
      schema_name: my_schema

Para um pacote de exemplo que executa um trabalho que grava em um arquivo no volume do Unity Catalog, confira o repositório GitHub de pacotes de exemplo bundle-examples.