Modèles de projets de packs de ressources Databricks

Les bundles de ressources Databricks décrivent les ressources Databricks, telles que les travaux, les pipelines et les notebooks en tant que fichiers sources, vous permettent d’inclure des métadonnées en même temps que ces fichiers sources pour approvisionner l’infrastructure et d’autres ressources, et fournir une définition de bout en bout d’un projet, toutes empaquetées en tant que projet déployable unique. Consultez Que sont les packs de ressources Databricks ?.

Les modèles de bundle permettent aux utilisateurs de créer des bundles de manière cohérente et reproductible, en établissant des structures de dossiers, des étapes de génération et des tâches, des tests et d’autres attributs IaC (Infrastructure-as-code) DevOps courants dans un pipeline de déploiement.

Par exemple, si vous exécutez régulièrement des travaux Databricks qui nécessitent des packages personnalisés avec une étape de compilation fastidieuse lors de l’installation, vous pouvez accélérer votre boucle de développement en créant un modèle de bundle qui spécifie un environnement de conteneur personnalisé.

Databricks fournit un ensemble de modèles de bundle par défaut, mais vous pouvez également créer modèles de bundle personnalisés. Les utilisateurs peuvent ensuite initialiser des offres groupées à l’aide de la commande init , en spécifiant un modèle par défaut ou votre modèle personnalisé.

Créer un bundle à l’aide d’un modèle

Pour utiliser un modèle de package Azure Databricks pour créer votre package, utilisez la commande de l'interface en ligne de commande Databricks bundle init, en spécifiant le nom du modèle à utiliser. Par exemple, la commande suivante crée un pack en utilisant le modèle de pack Python par défaut :

databricks bundle init default-python

Pour utiliser un modèle de bundle personnalisé, fournissez le chemin local ou l’URL distante du modèle à la commande Databricks CLIbundle init.

Par exemple, la commande suivante utilise le modèle dab-container-template créé dans le tutoriel Modèle de pack personnalisé :

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

Si vous ne spécifiez pas de modèle, la commande bundle init vous invite avec l’ensemble des modèles par défaut disponibles parmi lesquels vous pouvez choisir.

Modèles de pack par défaut

Azure Databricks fournit les modèles de pack par défaut suivants :

Modèles de packs personnalisés

Les modèles de bundle utilisent la syntaxe de création de modèles de package Go, qui offrent une flexibilité sur les modèles de bundle personnalisés que vous pouvez créer. Consultez la documentation du Modèle de package Go.

structure de projet modèle

Au minimum, un projet de modèle de pack doit avoir :

• Un fichier databricks_template_schema.json à la racine du projet qui définit une propriété d’invite utilisateur pour le nom du projet de pack. Consultez le schéma de modèle .
• Un fichier databricks.yml.tmpl qui se trouve dans un dossier template, qui définit la configuration des packs créés avec le modèle. Si votre fichier databricks.yml.tmpl fait référence à des modèles de configuration de *.yml.tmpl supplémentaires, spécifiez l’emplacement de ces modèles dans le mappage include. Consultez les modèles de configuration .

En outre, la structure de dossiers et les fichiers inclus du projet de modèle groupé template dossier sont mis en miroir par les bundles créés avec le modèle. Par exemple, si vous souhaitez que le modèle génère un bundle avec un bloc-notes simple dans le dossier src et une définition de travail qui exécute le bloc-notes dans le dossier resources, vous organisez votre projet de modèle comme suit :

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

schéma de modèle

Un projet de modèle de bundle personnalisé doit contenir un fichier JSON databricks_template_schema.json à la racine du projet. Ce fichier définit les champs utilisés par l’interface CLI Databricks lorsque la commande bundle init est exécutée, par exemple le texte d’invite.

Le fichier de base databricks_template_schema.json suivant définit une variable d’entrée project_name pour le projet groupé, qui inclut le message d’invite et une valeur par défaut. Il définit ensuite un message de réussite pour l’initialisation du projet bunde qui utilise la valeur de variable d’entrée dans le message.

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

Champs de modèle de schéma

Le fichier databricks_template_schema.json prend en charge la définition de variables d’entrée pour la collecte d’informations lors de l’initialisation de bundle à partir de votre utilisateur dans le champ properties, ainsi que d’autres champs pour personnaliser l’initialisation.

Les variables d’entrée sont définies dans le champ properties du schéma de modèle. Chaque variable d’entrée définit les métadonnées nécessaires pour présenter une invite à l’utilisateur lors de l’initalisation de l’offre groupée. La valeur de la variable est ensuite accessible à l’aide de la syntaxe de variable de modèle, telle que {{.project_name}}.

Vous pouvez également définir les valeurs de certains champs pour personnaliser le processus d’initialisation de bundle.

Les champs de schéma pris en charge sont répertoriés dans le tableau suivant.

modèles de configuration de

Un modèle de bundle personnalisé doit contenir un fichier databricks.yml.tmpl dans un dossier template dans le projet de modèle de bundle utilisé pour créer le projet groupé databricks.yml fichier de configuration. Les modèles de fichiers de configuration pour les ressources peuvent être créés dans le dossier resources. Remplissez ces fichiers de modèle avec le modèle de configuration YAML.

Les modèles de configuration d'exemples simples suivants pour databricks.yml et le *_job.yml associé établissent le nom du bundle et deux environnements cibles, et définissent un travail qui exécute le notebook dans le bundle, pour les bundles créés à l'aide de ce modèle. Ces modèles de configuration tirent parti des substitutions de bundle et des assistants de modèles de bundle.

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

Assistants et variables de modèle

Les helpers de modèle sont des fonctions fournies par Databricks que vous pouvez utiliser dans vos fichiers modèles pour obtenir des informations spécifiques à l’utilisateur au moment de l’exécution ou interagir avec le moteur de modèle. Vous pouvez également définir vos propres variables de modèle.

Les assistants de modèle suivants sont disponibles pour les modèles de paquet Databricks. Pour plus d’informations sur l’utilisation de modèles et de variables Go, consultez modèles Go.

Assistants de modèles personnalisés

Pour définir vos propres helpers de modèle, créez un fichier de modèle dans le dossier library du projet de modèle et utilisez la syntaxe de création de modèles Go pour définir des helpers. Par exemple, le contenu suivant d’un fichier library/variables.tmpl définit les variables cli_version et model_name. Lorsque ce modèle est utilisé pour initialiser un bundle, la valeur de la variable model_name est construite à l’aide du champ input_project_name défini dans le fichier de schéma du modèle. La valeur de ce champ correspond à la saisie de l’utilisateur après une invite.

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

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

Pour voir un exemple complet, consultez le fichier des variables de modèle mlops-stacks .

Tester un modèle de pack

Enfin, veillez à tester votre modèle. Par exemple, utilisez l’interface CLI Databricks pour initialiser un nouveau bundle à l’aide du modèle défini dans les sections précédentes :

databricks bundle init basic-bundle-template

À l’invite What is your bundle project name?, tapez my_test_bundle.

Une fois le pack de test créé, le message de réussite du fichier de schéma est affiché. Si vous examinez le contenu du dossier my_test_bundle, vous voyez normalement ceci :

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

Le fichier et le travail databricks.yml sont désormais personnalisés :

# 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

Partager le modèle

Si vous souhaitez partager ce modèle de bundle avec d’autres personnes, vous pouvez le stocker dans la gestion de version avec n’importe quel fournisseur pris en charge par Git et auquel vos utilisateurs ont accès. Pour exécuter la commande bundle init avec une URL Git, assurez-vous que le fichier databricks_template_schema.json se trouve à l’emplacement racine par rapport à cette URL Git.

Étapes suivantes

• Parcourez les modèles supplémentaires créés et gérés par Databricks. Consultez le référentiel d'exemples d'ensembles sur GitHub.
• Pour utiliser les piles MLOps avec les modèles de packs de ressources Databricks, reportez-vous aux packs de ressources Databricks pour les piles MLOps.
• En savoir plus sur le templating des packages Go. Consultez la documentation du Modèle de package Go.