Librerie Python con ambito notebook

  • Articolo

Le librerie con ambito notebook consentono di creare, modificare, salvare, riutilizzare e condividere ambienti Python personalizzati specifici di un notebook. Quando si installa una libreria con ambito notebook, solo il notebook corrente e tutti i processi associati a tale notebook hanno accesso a tale libreria. L'operazione non incide sugli altri notebook collegati allo stesso cluster.

Le librerie con ambito notebook non vengono mantenute tra le sessioni. È necessario reinstallare le librerie con ambito notebook all'inizio di ogni sessione o ogni volta che il notebook viene scollegato da un cluster.

Databricks consiglia di usare il %pip comando magic per installare librerie Python con ambito notebook.

È possibile usare %pip nei notebook pianificati come processi. Se è necessario gestire l'ambiente Python in un notebook Scala, SQL o R, usare il %python comando magic insieme a %pip.

Durante l'uso delle installazioni della libreria con ambito notebook, potrebbe verificarsi un maggiore traffico verso il nodo driver. Vedere Quanto grande deve essere il nodo driver quando si lavora con le librerie con ambito notebook?.

Per installare librerie per tutti i notebook collegati a un cluster, usare le librerie cluster. Vedere Librerie cluster.

Per una panoramica completa delle opzioni disponibili per l'installazione delle librerie Python in Databricks, vedere Gestione dell'ambiente Python.

Nota

In Databricks Runtime 10.4 LTS e versioni successive è possibile usare l'utilità di libreria di Azure Databricks (legacy). L'utilità di libreria è supportata solo in Databricks Runtime e non in Databricks Runtime ML. Vedere Utilità libreria (dbutils.library) (legacy).

Gestire le librerie con %pip i comandi

Il %pip comando è equivalente al comando pip e supporta la stessa API. Le sezioni seguenti illustrano esempi di come è possibile usare %pip i comandi per gestire l'ambiente. Per altre informazioni sull'installazione di pacchetti Python con pip, vedere la documentazione sull'installazione pip e le pagine correlate.

Importante

  • A partire dai comandi di Databricks Runtime 13.0 %pip , il processo Python non viene riavviato automaticamente. Se si installa un nuovo pacchetto o si aggiorna un pacchetto esistente, potrebbe essere necessario usare dbutils.library.restartPython() per visualizzare i nuovi pacchetti. Vedere Riavviare il processo Python in Azure Databricks.
  • In Databricks Runtime 12.2 LTS e versioni successive Databricks consiglia di inserire tutti i %pip comandi all'inizio del notebook. Lo stato del notebook viene reimpostato dopo qualsiasi %pip comando che modifica l'ambiente. Se si creano metodi o variabili Python in un notebook e quindi si usano %pip comandi in una cella successiva, i metodi o le variabili andranno persi.
  • L'aggiornamento, la modifica o la disinstallazione dei pacchetti Python di base (ad esempio IPython) con %pip può causare l'interruzione del funzionamento di alcune funzionalità come previsto. Se si verificano problemi di questo tipo, reimpostare l'ambiente scollegando e ricollegando il notebook o riavviando il cluster.

Installare una libreria con %pip

%pip install matplotlib

Installare un pacchetto wheel Python con %pip

%pip install /path/to/my_package.whl

Disinstallare una libreria con %pip

Nota

Non è possibile disinstallare una libreria inclusa nelle versioni delle note sulla versione di Databricks Runtime e sulla compatibilità o una libreria installata come libreria cluster. Se è stata installata una versione di libreria diversa da quella inclusa in Databricks Runtime o quella installata nel cluster, è possibile usare %pip uninstall per ripristinare la versione predefinita in Databricks Runtime o la versione installata nel cluster, ma non è possibile usare un %pip comando per disinstallare la versione di una libreria inclusa in Databricks Runtime o installata nel cluster.

%pip uninstall -y matplotlib

L'opzione -y è obbligatoria.

Installare una libreria da un sistema di controllo della versione con %pip

%pip install git+https://github.com/databricks/databricks-cli

È possibile aggiungere parametri all'URL per specificare elementi come la versione o la sottodirectory Git. Per altre informazioni e per esempi sull'uso di altri sistemi di controllo della versione, vedere il supporto di VCS.

Installare un pacchetto privato con credenziali gestite dai segreti di Databricks con %pip

Pip supporta l'installazione di pacchetti da origini private con autenticazione di base, inclusi i sistemi di controllo della versione privata e i repository di pacchetti privati, ad esempio Nexus e Artifactory. La gestione dei segreti è disponibile tramite l'API Dei segreti di Databricks, che consente di archiviare token di autenticazione e password. Usare l'API DBUtils per accedere ai segreti dal notebook. Si noti che è possibile usare $variables nei comandi magic.

Per installare un pacchetto da un repository privato, specificare l'URL del repository con l'opzione --index-url %pip install o aggiungerlo al pip file di configurazione in ~/.pip/pip.conf.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install --index-url https://<user>:$token@<your-package-repository>.com/<path/to/repo> <package>==<version> --extra-index-url https://pypi.org/simple/

Analogamente, è possibile usare la gestione dei segreti con i comandi magic per installare pacchetti privati dai sistemi di controllo della versione.

token = dbutils.secrets.get(scope="scope", key="key")

%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Installare un pacchetto da DBFS con %pip

Importante

Qualsiasi utente dell'area di lavoro può modificare i file archiviati in DBFS. Azure Databricks consiglia di archiviare i file nelle aree di lavoro o nei volumi di Unity Catalog.

È possibile usare %pip per installare un pacchetto privato salvato in DBFS.

Quando si carica un file in DBFS, il file viene rinominato automaticamente, sostituendo spazi, punti e trattini con caratteri di sottolineatura. Per i file con rotellina Python, pip richiede che il nome dei punti di utilizzo del file nella versione (ad esempio, 0.1.0) e trattini invece di spazi o caratteri di sottolineatura, quindi questi nomi file non vengono modificati.

%pip install /dbfs/mypackage-0.0.1-py3-none-any.whl

Installare un pacchetto da un volume con %pip

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Con Databricks Runtime 13.3 LTS e versioni successive, è possibile usare %pip per installare un pacchetto privato salvato in un volume.

Quando si carica un file in un volume, il file viene rinominato automaticamente, sostituendo spazi, punti e trattini con caratteri di sottolineatura. Per i file con rotellina Python, pip richiede che il nome dei punti di utilizzo del file nella versione (ad esempio, 0.1.0) e trattini invece di spazi o caratteri di sottolineatura, quindi questi nomi file non vengono modificati.

%pip install /Volumes/<catalog>/<schema>/<path-to-library>/mypackage-0.0.1-py3-none-any.whl

Installare un pacchetto archiviato come file dell'area di lavoro con %pip

Con Databricks Runtime 11.3 LTS e versioni successive, è possibile usare %pip per installare un pacchetto privato salvato come file dell'area di lavoro.

%pip install /Workspace/<path-to-whl-file>/mypackage-0.0.1-py3-none-any.whl

Salvare le librerie in un file dei requisiti

%pip freeze > /Workspace/shared/prod_requirements.txt

Tutte le sottodirectory nel percorso del file devono già esistere. Se si esegue %pip freeze > /Workspace/<new-directory>/requirements.txt, il comando non riesce se la directory /Workspace/<new-directory> non esiste già.

Usare un file dei requisiti per installare le librerie

Un file dei requisiti contiene un elenco di pacchetti da installare tramite pip. Un esempio di utilizzo di un file di requisiti è:

%pip install -r /Workspace/shared/prod_requirements.txt

Per altre informazioni sui requirements.txt file, vedere Formato file requisiti.

Quanto è grande il nodo driver quando si lavora con le librerie con ambito notebook?

L'uso di librerie con ambito notebook potrebbe comportare un maggior traffico verso il nodo driver perché funziona per mantenere coerente l'ambiente tra i nodi executor.

Quando si usa un cluster con 10 o più nodi, Databricks consiglia queste specifiche come requisito minimo per il nodo driver:

  • Per un cluster CPU a 100 nodi, usare Standard_DS5_v2.
  • Per un cluster GPU a 10 nodi, usare Standard_NC12.

Per i cluster di dimensioni maggiori, usare un nodo driver più grande.

È possibile usare %sh pip, !pipo pip? Qual è la differenza?

%shed ! eseguire un comando shell in un notebook. Il primo è un comando magic ausiliario di Databricks, mentre quest'ultimo è una funzionalità di IPython. pip è una sintassi abbreviata per %pip quando automagic è abilitato, ovvero l'impostazione predefinita nei notebook Python di Azure Databricks.

In Databricks Runtime 11.3 LTS e versioni successive, %pip, %sh pipe !pip tutte installano una libreria come libreria Python con ambito notebook. In Databricks Runtime 10.4 LTS e versioni successive Databricks consiglia di usare solo %pip o pip per installare librerie con ambito notebook. Il comportamento di %sh pip e !pip non è coerente in Databricks Runtime 10.4 LTS e versioni successive.

Problemi noti

  • In Databricks Runtime 9.1 LTS le librerie con ambito notebook non sono compatibili con i processi di streaming batch. Databricks consiglia invece di usare librerie cluster o il kernel IPython.