Gestisci le dipendenze per un'applicazione Databricks

Un'app Databricks può includere dipendenze Python, dipendenze Node.js o entrambe. Dichiari le dipendenze nei file specifici del linguaggio che Azure Databricks installa quando distribuisci l'app:

• Usa un file requirements.txt per i pacchetti Python installati con pip. Vedere Definire le dipendenze python con pip.
• Utilizzare un file pyproject.toml per i pacchetti Python installati con uv. Vedere Definire le dipendenze python con uv.
• Utilizza un file package.json per i pacchetti Node.js installati con npm o pnpm. Vedere Definire le dipendenze Node.js.

Definire le dipendenze python con pip

Le app che usano pip sono dotate di un set di librerie Python preinstallate. Per definire librerie Python aggiuntive, usare un requirements.txt file. Se uno dei pacchetti elencati corrisponde a quelli preinstallati, le versioni nel file sostituiscono le impostazioni predefinite.

Le app con scalabilità orizzontale (Beta) convertite da app standard possono rifiutare esplicitamente le librerie preinstallate ed eseguite in un'immagine pulita del sistema operativo di base. Vedi Disattivare le librerie Python preinstallate per le app Databricks.

Per esempio:

# 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

Librerie Python preinstallate

Le app basate su pip includono le seguenti librerie Python preinstallate. Non è necessario aggiungerli al tuo requirements.txt, a meno che non sia necessaria una versione diversa.

Definire le dipendenze python con uv

Se l'app usa uv per la gestione delle dipendenze, definire le dipendenze Python in un pyproject.toml file anziché requirements.txt. Le app basate su uv non includono librerie preinstallate, quindi è necessario dichiarare tutte le dipendenze nel file pyproject.toml. È anche possibile specificare qualsiasi versione Python usando il requires-python campo , a differenza pipdelle app basate su , che usano Python 3.11.

Lo stesso vale per le app con scalabilità orizzontale che hanno rifiutato esplicitamente le librerie preinstallate. Vedi Disattivare le librerie Python preinstallate per le app Databricks.

Durante la distribuzione, Databricks Apps seleziona una strategia di installazione in base ai file presenti:

• Se requirements.txt esiste, l'app usa pip per installare le dipendenze, indipendentemente dal fatto che pyproject.toml sia presente anche. requirements.txt ha sempre la precedenza.
• Se requirements.txt non esiste e sia pyproject.toml sia uv.lock esistono, l'app usa uv per installare le dipendenze dal file di blocco.

Il uv programma di installazione crea e gestisce il proprio ambiente virtuale, quindi non è necessario creare una .venv directory.

L'esempio seguente mostra un valore minimo pyproject.toml per un'app Databricks:

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

Per usare uv, è necessario includere un uv.lock file insieme a pyproject.toml. Generarlo eseguendo uv lock in locale e includerlo nella directory dell'app.

Definire le dipendenze Node.js

Per definire le librerie Node.js, includere un file package.json nella directory principale dell'applicazione. Azure Databricks supporta sia npm e pnpme seleziona la gestione pacchetti in base al file di blocco incluso:

• Se pnpm-lock.yaml è presente, l'app usa pnpm. Vedere Usare pnpm.
• In caso contrario, l'app usa npm.
• pnpm-lock.yaml Se e package-lock.json sono presenti, pnpm ha la precedenza.

Ad esempio, un package.json file per un'app React che usa Vite potrebbe essere simile al seguente:

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

Per compilare con pnpm, includere un file pnpm-lock.yaml accanto al tuo package.json. Generarlo eseguendo pnpm install in locale e includerlo nella directory dell'app. Azure Databricks fornisce pnpm tramite Corepack.

Si notino i requisiti seguenti per pnpm le app:

• Le dipendenze vengono installate con pnpm install --frozen-lockfile, quindi pnpm-lock.yaml devono rimanere sincronizzate con package.json. In caso di deviazione, la compilazione non riesce anziché aggiornare il file di blocco. Rigenerare il file di blocco con pnpm install dopo aver modificato le dipendenze.
• È necessario specificare il comando start in app.yaml. A differenza delle app npm, le app pnpm non usano uno script start predefinito come fallback. Vedere Configurare l'esecuzione dell'app Databricks con app.yaml.

Per i progetti pnpm dell'area di lavoro (in cui è presente un file pnpm-workspace.yaml), alcuni comandi app.yaml vengono eseguiti ricorsivamente pnpm. Ad esempio, un passaggio di compilazione o avvio potrebbe eseguire pnpm -r run build. Questi comandi devono chiamare corepack pnpm invece di pnpm in modo che i comandi annidati vengano risolti correttamente.

Evitare conflitti di versione

Seguire queste linee guida per evitare conflitti di versione:

• Per le app pip-basate, la sostituzione dei pacchetti preinstallati può causare incompatibilità se la versione specificata differisce significativamente da quella preinstallata.
• Testare sempre l'app per verificare che le modifiche apportate alla versione del pacchetto non introducono errori.
• L'aggiunta di versioni esplicite in requirements.txt consente di mantenere un comportamento coerente delle app tra le distribuzioni.
• Quando si utilizza uv, includere un file uv.lock per installazioni pienamente riproducibili tra diversi ambienti di distribuzione.

Installazione e gestione delle dipendenze

Azure Databricks installa le librerie definite in requirements.txt, pyproject.tomle package.json direttamente nel contenitore in esecuzione nel calcolo dedicato. È tua responsabilità gestire e applicare patch a queste dipendenze.

È possibile specificare librerie da più origini nei file di dipendenza:

• Librerie scaricate da repository pubblici come PyPI e npm
• Repository privati che eseguono l'autenticazione usando le credenziali archiviate nei segreti di Azure Databricks
• Librerie archiviate nella /Volumes/ directory (ad esempio, /Volumes/<catalog>/<schema>/<volume>/<path>)

Eseguire l'installazione da repository privati

Per installare i pacchetti da un repository privato, configurare le variabili di ambiente per l'autenticazione. Ad esempio, imposta PIP_INDEX_URL in modo che punti al tuo repository privato:

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

La configurazione di rete dell'area di lavoro deve consentire l'accesso al repository privato. Vedere Configurare la rete per le app di Databricks.

Installare i file wheel nei volumi di Unity Catalog

Per installare i pacchetti Python dai file wheel archiviati nei volumi del catalogo Unity:

1. Aggiungi il volume del catalogo Unity come risorsa per la tua app. Vedere Volume del catalogo Unity.
2. Fare riferimento al percorso del file full wheel direttamente in requirements.txt:

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

Per migliorare la sicurezza quando si accede ai repository di pacchetti esterni, usare i controlli in uscita serverless per limitare l'accesso ai repository pubblici e configurare la rete privata. Vedere Configurare la rete per le app di Databricks.