Administración de dependencias para una aplicación de Databricks

Una aplicación de Databricks puede incluir Python dependencias, Node.js dependencias o ambas. Se declaran dependencias en archivos específicos del lenguaje que Azure Databricks instala al implementar la aplicación:

• Use un archivo requirements.txt para los paquetes de Python instalados con pip. Consulte Definición de dependencias de Python con pip.
• Utiliza un pyproject.toml archivo para los paquetes de Python instalados con uv. Consulte Definición de dependencias de Python con uv.
• Usa un archivo package.json para los paquetes de Node.js instalados con npm o pnpm. Consulte Definición de dependencias de Node.js.

Definición de dependencias de Python con pip

Las aplicaciones que usan pip incluyen un conjunto de bibliotecas de Python preinstaladas. Para definir bibliotecas adicionales de Python, use un requirements.txt archivo . Si alguno de los paquetes enumerados coincide con los instalados previamente, las versiones del archivo invalidan los valores predeterminados.

Las aplicaciones escaladas horizontalmente (Beta) convertidas desde aplicaciones estándar pueden optar por no tener bibliotecas preinstaladas y ejecutarse en una imagen de sistema operativo base limpia en su lugar. Consulte Cómo excluir las bibliotecas de Python preinstaladas para las aplicaciones de Databricks.

Por ejemplo:

# Override default version of dash
dash==2.10.0

# Add additional libraries not pre-installed
requests==2.31.0
numpy==1.24.3

# Specify a compatible version range
scikit-learn>=1.2.0,<1.3.0

Bibliotecas de Python preinstaladas

Las aplicaciones basadas en pip incluyen las siguientes bibliotecas de Python preinstaladas. No necesita añadirlos a requirements.txt a menos que necesite una versión diferente.

Definición de dependencias de Python con uv

Si la aplicación usa uv para la administración de dependencias, defina las dependencias de Python en un pyproject.toml archivo en lugar de requirements.txt. Las aplicaciones basadas en uv no incluyen bibliotecas preinstaladas, por lo que debe declarar todas las dependencias en su pyproject.toml. También puede especificar cualquier versión de Python mediante el campo requires-python, a diferencia de las aplicaciones basadas en pip, que usan Python 3.11.

Lo mismo se aplica a las aplicaciones escaladas horizontalmente que han optado por no tener bibliotecas preinstaladas. Consulte Cómo excluir las bibliotecas de Python preinstaladas para las aplicaciones de Databricks.

Durante la implementación, Databricks Apps selecciona una estrategia de instalación en función de los archivos que están presentes:

• Si requirements.txt existe, la aplicación usa pip para instalar dependencias, independientemente de si pyproject.toml también está presente. requirements.txt siempre tiene prioridad.
• Si requirements.txt no existe y ambos pyproject.toml y uv.lock existen, la aplicación usa uv para instalar dependencias desde el archivo de bloqueo.

El uv instalador crea y administra su propio entorno virtual, por lo que no es necesario crear un .venv directorio.

En el ejemplo siguiente se muestra un mínimo pyproject.toml para una aplicación de Databricks:

[project]
name = "my-app"
requires-python = ">=3.11"
dependencies = [
    "dash==2.10.0",
    "requests==2.31.0",
]

Para usar uv, debe incluir un uv.lock archivo junto con pyproject.toml. Genéralo ejecutándolo localmente e inclúyelo en el directorio de tu aplicación.

Definición de dependencias de Node.js

Para definir bibliotecas Node.js, incluye un archivo package.json en la raíz de tu aplicación. Azure Databricks admite tanto npm como pnpm, y selecciona el administrador de paquetes en función del archivo de bloqueo que incluya:

• Si pnpm-lock.yaml está presente, la aplicación usa pnpm. Consulte Uso de pnpm.
• De lo contrario, la aplicación usa npm.
• Si ambos pnpm-lock.yaml y package-lock.json están presentes, pnpm tiene prioridad.

Por ejemplo, un package.json archivo para una aplicación react con Vite podría tener este aspecto:

{
  "name": "react-fastapi-app",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "npm run build:frontend",
    "build:frontend": "vite build frontend"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.2.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0"
  }
}

Usa pnpm

Para compilar con pnpm, incluya un pnpm-lock.yaml archivo junto con package.json. Genéralo ejecutándolo localmente e inclúyelo en el directorio de tu aplicación. Azure Databricks proporciona pnpm a través de Corepack.

Tenga en cuenta los siguientes requisitos para las aplicaciones pnpm:

• Las dependencias se instalan con pnpm install --frozen-lockfile, por lo que pnpm-lock.yaml deben estar sincronizados con package.json. Si se desincronizan, la compilación falla en lugar de actualizar el archivo de bloqueo. Vuelva a generar el archivo de bloqueo con pnpm install después de cambiar las dependencias.
• Debe especificar el comando start en app.yaml. A diferencia de las aplicaciones npm, las aplicaciones pnpm no recurren a una secuencia de comandos start predeterminada. Vea Configurar la ejecución de la aplicación de Databricks con app.yaml.

Para los proyectos de espacio de trabajo pnpm (donde está presente un archivo pnpm-workspace.yaml), algunos comandos app.yaml se ejecutan pnpm recursivamente. Por ejemplo, un paso de compilación o inicio podría ejecutar pnpm -r run build. Estos comandos deben llamar a corepack pnpm en lugar de pnpm para que los comandos anidados se resuelvan correctamente.

Evitar conflictos de versiones

Siga estas instrucciones para evitar conflictos de versiones:

• Para aplicaciones basadas en pip, sobrescribir paquetes preinstalados puede causar problemas de compatibilidad si la versión especificada difiere significativamente de la versión preinstalada.
• Pruebe siempre la aplicación para comprobar que los cambios en la versión del paquete no presentan errores.
• Anclar versiones explícitas en requirements.txt ayuda a mantener un comportamiento coherente de la aplicación en todas las implementaciones.
• Al usar uv, incluya un uv.lock archivo para instalaciones totalmente reproducibles en todas las implementaciones.

Instalación y administración de dependencias

Azure Databricks instala bibliotecas definidas en requirements.txt, pyproject.tomly package.json directamente en el contenedor que se ejecuta en el proceso dedicado. Usted es responsable de gestionar y aplicar parches a estas dependencias.

Puede especificar bibliotecas de varios orígenes en los archivos de dependencia:

• Bibliotecas descargadas de repositorios públicos como PyPI y npm
• Repositorios privados que se autentican mediante credenciales almacenadas en secretos de Azure Databricks
• Bibliotecas almacenadas en el /Volumes/ directorio (por ejemplo, /Volumes/<catalog>/<schema>/<volume>/<path>)

Instalación desde repositorios privados

Para instalar paquetes desde un repositorio privado, configure variables de entorno para la autenticación. Por ejemplo, establezca PIP_INDEX_URL para que apunte al repositorio privado:

env:
  - name: PIP_INDEX_URL
    valueFrom: my-pypi-secret

La configuración de red del área de trabajo debe permitir el acceso al repositorio privado. Consulte Configuración de redes para Aplicaciones de Databricks.

Instalación de archivos wheel desde los volúmenes del Catálogo de Unity

Para instalar paquetes de Python desde archivos Wheel almacenados en volúmenes del Catálogo de Unity:

1. Agregue el volumen del catálogo de Unity como un recurso a la aplicación. Consulte Volumen del catálogo de Unity.
2. Haga referencia directamente a la ruta completa del archivo wheel en requirements.txt:

/Volumes/<catalog>/<schema>/<volume>/my_package-1.0.0-py3-none-any.whl

Para mejorar la seguridad al acceder a repositorios de paquetes externos, use controles de salida sin servidor para restringir el acceso a repositorios públicos y configurar redes privadas. Consulte Configuración de redes para Aplicaciones de Databricks.