Plantillas de proyecto de agrupación de recursos de Databricks
Los conjuntos de recursos de Databricks describen los recursos de Databricks, como trabajos, canalizaciones y cuadernos como archivos de origen, lo que le permite incluir metadatos junto con estos archivos de origen para aprovisionar infraestructura y otros recursos, y proporcionar una definición de un extremo a otro de un proyecto, todos empaquetados como un único proyecto implementable. Consulte ¿Qué son los conjuntos de recursos de Databricks?
Las plantillas de agrupación permiten a los usuarios crear agrupaciones de forma coherente y repetible mediante el establecimiento de estructuras de carpetas, pasos de compilación y tareas, pruebas y otros atributos de infraestructura como código (IaC) de DevOps comunes en una canalización de implementación.
Por ejemplo, si ejecuta periódicamente trabajos de Databricks que requieren paquetes personalizados con un paso de compilación lento tras la instalación, puede acelerar el bucle de desarrollo mediante la creación de una plantilla de agrupación que especifique un entorno de contenedor personalizado.
Databricks proporciona un conjunto de plantillas de agrupación predeterminadas, pero también puede crear plantillas de agrupación personalizadas. A continuación, los usuarios pueden inicializar agrupaciones mediante el comando bundle init, especificando una plantilla predeterminada o la plantilla personalizada.
Creación de una agrupación mediante una plantilla
Para usar una plantilla de agrupación de Azure Databricks para crear la agrupación, use el comando cli de Databricksbundle init
, especificando el nombre de la plantilla que se va a usar. Por ejemplo, el siguiente comando crea una agrupación mediante la plantilla de agrupación de Python predeterminada:
databricks bundle init default-python
Para utilizar una plantilla de paquete personalizada, pase la ruta de acceso local o la URL remota de la plantilla al comando CLI de Databricksbundle init
.
Por ejemplo, el siguiente comando usa la plantilla dab-container-template
creada en el Tutorial de plantilla de agrupación personalizada:
databricks bundle init /projects/my-custom-bundle-templates/dab-container-template
Si no especifica una plantilla, el comando bundle init
muestra un conjunto de plantillas predeterminadas disponibles entre las que puede elegir.
plantillas de paquetes predeterminadas
Azure Databricks proporciona las siguientes plantillas de agrupación predeterminadas:
Plantilla | Descripción |
---|---|
default-python |
Plantilla para usar Python con Databricks. Esta plantilla crea una agrupación con un trabajo y una canalización de DLT. Consulte default-python. |
default-sql |
Plantilla para usar SQL con Databricks. Esta plantilla contiene un archivo de configuración que define un trabajo que ejecuta consultas SQL en un almacén de SQL. Consulte default-sql. |
dbt-sql |
Plantilla que aprovecha dbt-core para el desarrollo local y las agrupaciones para la implementación. Esta plantilla contiene la configuración que define un trabajo con una tarea dbt, así como un archivo de configuración que define perfiles de dbt para trabajos dbt implementados. Consulte dbt-sql. |
mlops-stacks |
Plantilla de pila completa avanzada para iniciar nuevos proyectos de MLOps Stacks. Consulte mlops-stacks y Agrupaciones de recursos de Databricks para pilas de MLOps. |
plantillas de paquetes personalizadas
Las plantillas de agrupación usan la sintaxis de plantillas de paquetes de Go, que proporcionan flexibilidad en las plantillas de agrupación personalizadas que puede crear. Consulte la documentación de la plantilla de paquete de Go.
Estructura del proyecto de plantilla
Como mínimo, un proyecto de plantilla de agrupación debe tener:
- Un archivo
databricks_template_schema.json
en la raíz del proyecto que define una propiedad de solicitud de usuario para el nombre del proyecto de agrupación. Consulte Esquema de plantilla. - Un archivo
databricks.yml.tmpl
ubicado en una carpetatemplate
que define la configuración de los conjuntos creados con la plantilla. Si el archivodatabricks.yml.tmpl
hace referencia a plantillas de configuración adicionales*.yml.tmpl
, especifique la ubicación de estos en la asignacióninclude
. Consulte Plantillas de configuración de YML.
Además, la estructura de carpetas y los archivos incluidos del proyecto de plantilla de paquetes de la carpeta template
se reflejan en los paquetes creados con la plantilla. Por ejemplo, si desea que la plantilla genere una agrupación con un cuaderno simple en la carpeta src
y una definición de trabajo que ejecute el cuaderno en la carpeta resources
, organizaría el proyecto de plantilla de la siguiente manera:
basic-bundle-template
├── databricks_template_schema.json
└── template
├── databricks.yml.tmpl
├── resources
│ └── {{.project_name}}_job.yml.tmpl
└── src
└── simple_notebook.ipynb
Sugerencia
El nombre del archivo de definición de trabajo de esta plantilla de agrupación usa una variable de plantilla. Para obtener información sobre las variables y los asistentes de plantilla, consulte Asistentes de plantillas y variables.
Esquema de plantilla
Un proyecto de plantilla de agrupación personalizado debe contener en la raíz del proyecto un databricks_template_schema.json
[archivo JSON](https://json-schema.org/specification.html). Este archivo define los campos usados por la CLI de Databricks cuando se ejecuta el comando bundle init
, como el texto de aviso.
El siguiente archivo de databricks_template_schema.json
básico define una variable de entrada project_name
para el proyecto de agrupación, que incluye el mensaje de aviso y un valor predeterminado. A continuación, define un mensaje de operación correcta para la inicialización del proyecto de agrupación que usa el valor de la variable de entrada dentro del mensaje.
{
"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 de esquema de plantilla
El archivo databricks_template_schema.json
admite la definición de variables de entrada para recopilar información del usuario durante la inicialización del paquete dentro del campo properties
, así como para definir campos adicionales que personalicen la inicialización.
Las variables de entrada se definen en el campo properties
del esquema de plantilla. Cada variable de entrada define los metadatos necesarios para presentar un indicador al usuario durante la inicialización del paquete. A continuación, se puede acceder al valor de la variable mediante la sintaxis de variable de plantilla, como {{.project_name}}
.
También puede establecer los valores de algunos campos para personalizar el proceso de inicialización del paquete.
Los campos de esquema admitidos se enumeran en la tabla siguiente.
Campo de esquema | Descripción |
---|---|
properties |
Definiciones de variable de entrada de plantilla de agrupación. Databricks recomienda definir al menos una variable de entrada que sea el nombre del proyecto de agrupación. |
properties.<variable_name> |
Nombre de la variable de entrada. |
properties.<variable_name>.default |
Valor predeterminado que se va a usar si el usuario no proporciona un valor con --config-file como parte del comando bundle init o en la línea de comandos cuando se le solicite. |
properties.<variable_name>.description |
Mensaje de solicitud de usuario asociado a la variable de entrada. |
properties.<variable_name>.enum |
Lista de valores posibles para la propiedad, como "enum": ["azure", "aws", "gcp"] . Si se define este campo, la CLI de Databricks presenta los valores de una lista en la línea de comandos para pedir al usuario que seleccione un valor. |
properties.<variable_name>.order |
Entero que define el orden relativo de las propiedades de entrada. Esto controla el orden en el que se muestran las indicaciones de estas variables de entrada en la línea de comandos. |
properties.<variable_name>.pattern |
Patrón regexp que se va a usar para validar la entrada del usuario, por ejemplo, "pattern": "^[^ .\\\\/]{3,}$" . Para ver la sintaxis regexp admitida, consulte https://github.com/google/re2/wiki/Syntax. |
properties.<variable_name>.pattern_match_failure_message |
Mensaje que se muestra al usuario si el valor especificado por el usuario no coincide con el patrón especificado, por ejemplo, Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\"." . |
properties.<variable_name>.skip_prompt_if |
Omita la solicitud de la variable de entrada si esta configuración ya satisface el esquema. En ese caso, se usa el valor predeterminado de la propiedad en su lugar. Para obtener un ejemplo, consulte la plantilla mlops-stacks. Solo se admiten comparaciones de const . |
properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const |
Si el valor de <previous_variable_name> coincide con la constante configurada en skip_prompt_if , se omitirá la solicitud de <variable_name> . |
welcome_message |
Primer mensaje que se va a generar antes de pedir al usuario que escriba. |
success_message |
Mensaje que se va a imprimir después de inicializar correctamente la plantilla. |
min_databricks_cli_version |
La versión mínima del SemVer de esta CLI de Databricks que requiere la plantilla. databricks bundle init produce un error si la versión de la CLI es menor que esta versión. |
version |
Reservado para uso futuro. Versión del esquema. Esto se usa para determinar si el esquema es compatible con la versión actual de la CLI. |
Plantillas de configuración de YML
Una plantilla de agrupación personalizada debe contener un archivo databricks.yml.tmpl
en una carpeta template
del proyecto de plantilla de agrupación que se usa para crear el proyecto de agrupación databricks.yml
. Rellene este archivo de plantilla con la plantilla de configuración básica YAML.
En el ejemplo siguiente, las plantillas de configuración para databricks.yml y el *_job.yml asociado, establecen el nombre del lote y dos entornos de destino, y definen un trabajo que ejecuta el cuaderno en la agrupación, para los conjuntos creados con esta plantilla. Estas plantillas de configuración aprovechan las sustituciones de paquetes y los auxiliares de plantillas de paquetes. Consulte sustituciones de paquetes y asistentes de plantilla de paquete.
# 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 -}}
# {{.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
Asistentes y variables de plantilla
Los asistentes de plantilla son funciones proporcionadas por Databricks que puede usar dentro de los archivos de plantilla para obtener información específica del usuario en tiempo de ejecución o interactuar con el motor de plantillas. También puede definir sus propias variables de plantilla.
Los siguientes asistentes de plantilla están disponibles para los proyectos de plantilla de agrupación de Databricks. Para obtener información sobre el uso de plantillas y variables de Go, consulte plantillas de Go.
Ayudante | Descripción |
---|---|
{{url}} |
Un alias para https://pkg.go.dev/net/url#Parse. Esto permite el uso de todos los métodos de url.URL . |
{{regexp}} |
Un alias para https://pkg.go.dev/regexp#Compile. Esto permite el uso de todos los métodos de regexp.Regexp . |
{{random_int}} |
Devuelve, como int, un número pseudoaleatorio no negativo en el intervalo medio abierto (0,n). |
{{uuid}} |
Devuelve, como una cadena, un UUID que es un identificador único universal de 128 bits (16 bytes) tal como se define en RFC 4122.Este identificador es estable durante la ejecución de la plantilla y se puede usar para rellenar el campo bundle.uuid en databricks.yml por autores de plantillas. |
{{bundle_uuid}} |
Un identificador único para la agrupación. Varias invocaciones de esta función devolverán el mismo UUID. |
{{pair}} |
Un par clave-valor. Esto se usa con el asistente de map para generar mapas que se usarán dentro de una plantilla. |
{{map}} |
Convierte una lista de pares en un objeto de mapa. Esto resulta útil para pasar varios objetos a plantillas definidas en el directorio de biblioteca. Dado que la sintaxis de la plantilla de texto de Go para invocar una plantilla solo permite especificar un único argumento, esta función se puede usar para solucionar esa limitación. Por ejemplo, en la línea siguiente, se puede hacer referencia a {{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}} , $arg1 y $arg2 desde dentro de my_template como .foo y .bar . |
{{smallest_node_type}} |
Devuelve el tipo de nodo más pequeño. |
{{path_separator}} |
Carácter separador de ruta para el sistema operativo. Esto es / para sistemas basados en Unix y \ para Windows. |
{{workspace_host}} |
La dirección URL del host del área de trabajo en la que el usuario está autenticado actualmente. |
{{user_name}} |
Nombre completo del usuario que inicializa la plantilla. |
{{short_name}} |
Nombre corto del usuario que inicializa la plantilla. |
{{default_catalog}} |
Devuelve el catálogo de áreas de trabajo predeterminado. Si no hay ningún valor predeterminado o si el catálogo de Unity no está habilitado, devuelve una cadena vacía. |
{{is_service_principal}} |
Si el usuario actual es o no una entidad de servicio. |
{{ skip <glob-pattern-relative-to-current-directory> }} |
Hace que el motor de plantillas omita la generación de todos los archivos y directorios que coinciden con el patrón glob de entrada. Para obtener un ejemplo, consulte la plantilla mlops-stacks. |
Para definir sus propias variables, cree un archivo de plantilla en la carpeta library
del proyecto de plantilla y use la sintaxis de plantillas de Go para definir variables. Por ejemplo, el siguiente contenido de un archivo de library/variables.tmpl
define las variables cli_version
y model_name
. Cuando esta plantilla se usa para inicializar una agrupación, el valor de la variable model_name
se construye mediante el campo input_project_name
definido en el archivo de esquema de plantilla. El valor de este campo es la entrada del usuario después de un aviso.
{{ define `cli_version` -}}
v0.240.0
{{- end }}
{{ define `model_name` -}}
{{ .input_project_name }}-model
{{- end }}
Para ver un ejemplo completo, consulte el archivo de variables de plantilla de mlops-stacks.
Prueba la plantilla del paquete
Por último, asegúrese de probar la plantilla. Cree una nueva carpeta de proyecto de agrupación y, a continuación, use la CLI de Databricks para inicializar una nueva agrupación mediante la plantilla:
databricks bundle init basic-bundle-template
En el símbolo del sistema What is your bundle project name?
, escriba my_test_bundle
.
Una vez creada la agrupación de pruebas, se genera el mensaje de confirmación del archivo de esquema. Si examina el contenido de la carpeta my_test_bundle
, debería ver lo siguiente:
my_test_bundle
├── databricks.yml
├── resources
│ └── my_test_bundle_job.yml
└── src
└── simple_notebook.ipynb
Y ahora se han personalizado el archivo databricks.yml y el trabajo.
# 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
Uso compartido de la plantilla
Si desea compartir esta plantilla de agrupación con otros usuarios, puede almacenarla en el control de versiones con cualquier proveedor que Git admita y al que los usuarios tengan acceso. Para ejecutar el comando bundle init
con una dirección URL de Git, asegúrese de que el archivo databricks_template_schema.json
se encuentra en la ubicación raíz con respecto a esa dirección URL de Git.
Sugerencia
Puede colocar el archivo databricks_template_schema.json
en una carpeta diferente, en relación con la raíz del lote. A continuación, puede usar la opción bundle init
del comando --template-dir
para hacer referencia a esa carpeta, que contiene el archivo databricks_template_schema.json
.
Pasos siguientes
- Examine plantillas adicionales creadas y mantenidas por Databricks. Consulte el repositorio de ejemplos de agrupación en GitHub.
- Para usar MLOps Stacks con las plantillas de Paquetes de Recursos de Databricks, consulte Paquetes de Recursos de Databricks para MLOps Stacks.
- Obtenga más información sobre la plantillas de paquetes de Go. Consulte la documentación de la plantilla de paquete de Go.