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:

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.

Libreria Versione
databricks-sql-connector 3.4.0
Databricks SDK 0.33.0
mlflow-skinny 2.16.2
gradio 4.44.0
streamlit 1.38.0
brillante 1.1.0
trattino 2.18.1
flacone 3.0.3
fastapi 0.115.0
uvicorn[standard] 0.30.6
gunicorn 23.0.0
huggingface-hub 0.35.3
dash-ag-grid 31.2.0
dash-mantine-components 0.14.4
dash-bootstrap-components 1.6.0
plotly (software di visualizzazione dati) 5.24.1
plotly-resampler 0.10.0

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

Annotazioni

Elencare tutti i pacchetti necessari per il passaggio di compilazione in dependencies, non devDependencies. Se si impostano NODE_ENV=production nelle variabili di ambiente, il processo di distribuzione ignora l'installazione di devDependencies.

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.

Usare repository di pacchetti predefiniti a livello di area di lavoro

Importante

Questa funzionalità è in versione beta. Per utilizzarlo, un amministratore dell'area di lavoro deve abilitare Abilita la configurazione del repository dell'area di lavoro per le App Databricks dalla pagina Anteprime. Vedere Gestire le anteprime di Azure Databricks.

Se un amministratore dell'area di lavoro configura i repository di pacchetti predefiniti per l'area di lavoro, le app in tale area di lavoro installano Python e Node.js pacchetti dai repository configurati dall'area di lavoro anziché dai registri PyPI e npm pubblici. In questo modo gli sviluppatori di app ereditano automaticamente le impostazioni del repository di pacchetti aziendali senza duplicare la configurazione in ogni app, consentendo comunque le sostituzioni per app.

Per configurare queste impostazioni a livello di area di lavoro, vedere Configurare i repository di pacchetti predefiniti.

pacchetti Python

Durante la fase di installazione del pacchetto della build, Databricks Apps eredita le impostazioni del workspace relative alle seguenti variabili di ambiente:

  • PIP_INDEX_URL
  • PIP_EXTRA_INDEX_URL
  • PIP_CERT
  • UV_INDEX_URL
  • UV_EXTRA_INDEX_URL
  • SSL_CERT_FILE

La configurazione specifica dell'app ha la precedenza sulle impostazioni predefinite dell'area di lavoro. Se imposti una delle variabili di ambiente precedenti (ad eccezione delle impostazioni del certificato indicate di seguito) nel file dell'app, i valori in app.yaml sostituiscono le impostazioni dell'area di app.yaml lavoro per tale app.

Annotazioni

Le impostazioni del certificato PIP_CERT e SSL_CERT_FILE utilizzano sempre i valori configurati per lo spazio di lavoro e non possono essere sovrascritte in app.yaml.

Avvertimento

Testa le tue app dopo che l'amministratore dello spazio di lavoro abilita l'anteprima e imposta PIP_INDEX_URL in app.yaml se devi continuare a eseguire l'installazione da un indice diverso.

pacchetti Node.js

Quando un amministratore dell'area di lavoro configura un registro npm predefinito, Databricks Apps scrive la configurazione del Registro di sistema dell'area di lavoro nel file dell'app .npmrc durante la distribuzione. Ciò consente alle app di installare pacchetti Node.js, inclusi i pacchetti privati, dal Registro di sistema configurato per l'area di lavoro senza che ogni app archivii i propri URL del Registro di sistema o token di autenticazione.

Per usare un registro diverso per un'app specifica, impostare la NPMRC variabile di ambiente nel file dell'app app.yaml per fare riferimento alla propria configurazione npm. La configurazione specifica dell'app ha la precedenza sulle impostazioni predefinite dell'area di lavoro.

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

Annotazioni

I riferimenti alle variabili di ambiente non sono supportati in requirements.txt. È necessario codificare in modo esplicito il percorso completo del file wheel.

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.

  • Last updated on