Python-Bibliotheken im Notebook-Bereich

  • Artikel
  • 10 Minuten Lesedauer

Mit Bibliotheken im Notebook-Bereich können Sie benutzerdefinierte Python-Umgebungen erstellen, ändern, speichern, wiederverwenden und freigeben, die für ein Notebook spezifisch sind. Wenn Sie eine Bibliothek im Notebook-Bereich installieren, haben nur das aktuelle Notebook und alle diesem Notebook zugeordneten Aufträge Zugriff auf diese Bibliothek. Andere Notebooks, die an denselben Cluster angefügt sind, sind nicht betroffen.

Bibliotheken im Notebook-Bereich werden nicht sitzungsübergreifend beibehalten. Sie müssen Bibliotheken im Notebook-Bereich zu Beginn jeder Sitzung oder immer dann neu installieren, wenn das Notebook von einem Cluster getrennt wird.

Es gibt zwei Methoden zum Installieren von Bibliotheken im Notebook-Bereich:

  • Den %pip-Magic-Befehl in einem Notebook ausführen. Der %pip-Befehl wird für Databricks Runtime 7.1 und höher sowie für Databricks Runtime 6.4 ML und höher unterstützt. Databricks empfiehlt die Verwendung dieses Vorgehen für neue Workloads. In diesem Artikel wird beschrieben, wie Sie diese Magic-Befehle verwenden.
  • Das Azure Databricks-Bibliothekshilfsprogramm verwenden. Das Bibliothekshilfsprogramm wird nur auf Databricks Runtime unterstützt, nicht auf Databricks Runtime ML oder Databricks Runtime für Genomics. Weitere Informationen finden Sie unter Bibliothekshilfsprogramm (dbutils.library).

Verwenden Sie die im Arbeitsbereich oder im Cluster installierten Bibliotheken, um Bibliotheken für alle Notebooks zu installieren, die einem Cluster zugeordnet sind.

Requirements (Anforderungen)

Bibliotheken im Notebook-Bereich, die Magic-Befehle verwenden, sind in Databricks Runtime 7.1 und höher, Databricks Runtime 7.1 ML und höher und Databricks Runtime 7.1 für Genomics und höher standardmäßig aktiviert.

Sie sind über eine Konfigurationseinstellung auch in Databricks Runtime 6.4 ML bis 7.0 ML und Databricks Runtime 6.4 für Genomics bis Databricks Runtime 7.0 für Genomics verfügbar. Legen Sie die Spark-Konfigurationspark.databricks.conda.condaMagic.enabled auf true fest.

In einem Cluster mit hoher Parallelität, auf dem Databricks Runtime 7.4 ML oder Databricks Runtime 7.4 für Genomics oder höher ausgeführt wird, sind Bibliotheken im Notebook-Bereich nicht mit der Tabellenzugriffssteuerung oder dem Passthrough von Anmeldeinformationen kompatibel. Alternativ können Sie das Bibliothekshilfsprogramm (dbutils.library) in einem Databricks Runtime Cluster verwenden oder ihren Cluster auf Databricks Runtime 7.5 ML oder Databricks Runtime 7.5 für Genomics oder höher aktualisieren.

Um Bibliotheken im Notebook-Bereich mit Databricks Connect verwenden zu können, müssen Sie das Bibliothekshilfsprogramm (dbutils.library) verwenden.

Treiberknoten

Die Verwendung von Bibliotheken im Notebook-Bereich kann zu mehr Datenverkehr zum Treiberknoten führen, da die Umgebung über alle Executorknoten hinweg konsistent bleibt.

Wenn Sie einen Cluster mit 10 oder mehr Knoten verwenden, empfiehlt Databricks folgende Spezifikationen als Mindestanforderung für den Treiberknoten:

  • Verwenden Sie für einen CPU-Cluster mit 100 Knoten Standard_DS5_v2.
  • Verwenden Sie für einen GPU-Cluster mit 10 Knoten Standard_NC12.

Verwenden Sie für größere Cluster einen größeren Treiberknoten.

Bibliotheken im Notebook-Bereich mit %pip

Wichtig

  • Sie sollten alle %pip Befehle an den Anfang des Notebooks stellen. Der Notebookzustand wird nach jedem %pip-Befehl zurückgesetzt, der die Umgebung ändert. Wenn Sie Python-Methoden oder -Variablen in einem Notebook erstellen und dann %pip-Befehle in einer späteren Zelle verwenden, gehen die Methoden oder Variablen verloren.
  • Das Upgraden, Ändern oder Deinstallieren von Python-Kernpaketen (z. B. IPython) mit %pip kann dazu führen, dass einige Features nicht mehr wie erwartet funktionieren. Beispielsweise sind IPython 7.21 und höher nicht mit Databricks Runtime 8.1 und niedriger kompatibel. Wenn solche Probleme auftreten, setzen Sie die Umgebung zurück, indem Sie das Notebook trennen und erneut anfügen oder den Cluster neu starten.

Verwalten von Bibliotheken mit %pip-Befehlen

Der %pip-Befehl entspricht dem pip-Befehl und unterstützt dieselbe API. Die folgenden Abschnitte zeigen Beispiele für die Verwendung von %pip-Befehlen zum Verwalten Ihrer Umgebung. Weitere Informationen zum Installieren von Python-Paketen mit pip finden Sie in der Dokumentation zur pip-Installation und auf zugehörigen Seiten.

In diesem Abschnitt

Installieren einer Bibliothek mit %pip

%pip install matplotlib

Installieren eines Wheel-Pakets mit %pip

%pip install /path/to/my_package.whl

Deinstallieren einer Bibliothek mit %pip

Hinweis

Bibliotheken, die in Databricks Runtime enthalten sind, oder eine Bibliothek, die als Clusterbibliothek installiert wurde, können nicht deinstalliert werden. Wenn Sie eine andere Bibliotheksversion als die in Databricks Runtime enthaltene oder die auf dem Cluster installierte Version installiert haben, können Sie %pip uninstall verwenden, um die Bibliothek auf die Standardversion in Databricks Runtime oder die auf dem Cluster installierte Version zurückzusetzen, aber Sie können keinen %pip-Befehl verwenden, um die Version einer in Databricks Runtime enthaltenen oder auf dem Cluster installierten Bibliothek zu deinstallieren.

%pip uninstall -y matplotlib

Die -y-Option ist erforderlich.

Installieren einer Bibliothek aus einem Versionskontrollsystem mit %pip

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

Sie können Parameter zur URL hinzufügen, um Elemente wie die Version oder das Git-Unterverzeichnis anzugeben. Weitere Informationen und Beispiele zur Verwendung anderer Versionskontrollsysteme finden Sie unter VCS-Unterstützung.

Installieren eines privaten Pakets mit Anmeldeinformationen, die von Databricks-Geheimnissen verwaltet werden, mit %pip

Pip unterstützt die Installation von Paketen aus privaten Quellen mit Standardauthentifizierung, einschließlich privater Versionskontrollsysteme und privater Paketrepositorys wie Nexus und Artifactory. Die Geheimnisverwaltung ist über die Databricks Secrets-API verfügbar, mit der Sie Authentifizierungstoken und Kennwörter speichern können. Verwenden Sie die DBUtils-API, um über Ihr Notebook auf Geheimnisse zuzugreifen. Beachten Sie, dass Sie bei Magic-Befehlen $variables verwenden können.

Um ein Paket aus einem privaten Repository zu installieren, geben Sie die Repository-URL mit der --index-url Option zu %pip install an, oder fügen Sie sie der pip Konfigurationsdatei unter ~/.pip/pip.confhinzu.

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/

Auf ähnliche Weise können Sie die Geheimnisverwaltung mit Magic-Befehlen verwenden, um private Pakete aus Versionskontrollsystemen zu installieren.

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

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

Installieren eines Pakets aus DBFS mit %pip

Sie können %pip verwenden, um ein privates Paket zu installieren, das in DBFS gespeichert wurde.

Wenn Sie eine Datei in DBFS hochladen, wird die Datei automatisch umbenannt, wobei Leerzeichen, Zeiträume und Bindestriche durch Unterstriche ersetzt werden. pip erfordert, dass der Name der Wheel-Datei Punkte in der Version (z. B. 0.1.0) und Bindestriche anstelle von Leerzeichen oder Unterstrichen verwendet. Um das Paket mit einem %pip-Befehl zu installieren, müssen Sie die Datei umbenennen, um diese Anforderungen zu erfüllen.

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

Speichern von Bibliotheken in einer Anforderungsdatei

%pip freeze > /dbfs/requirements.txt

Alle Unterverzeichnisse im Dateipfad müssen bereits vorhanden sein. Wenn Sie %pip freeze > /dbfs/<new-directory>/requirements.txt ausführen, schlägt der Befehl fehl, wenn das Verzeichnis /dbfs/<new-directory> noch nicht vorhanden ist.

Verwenden einer Anforderungsdatei zum Installieren von Bibliotheken

Eine Anforderungsdatei enthält eine Liste der Pakete, die mit pip installiert werden. Ein Beispiel für die Verwendung einer Anforderungsdatei ist:

%pip install -r /dbfs/requirements.txt

Weitere Informationen zu Dateien finden Sie unter Format der Anforderungsdateirequirements.txt.

Verwalten von Bibliotheken mit %conda-Befehlen

Wichtig

%conda-Befehle sind veraltet und werden nach Databricks Runtime ML 8.4 nicht mehr unterstützt. Databricks empfiehlt die Verwendung von %pip zum Verwalten von Bibliotheken im Notebook-Bereich. Wenn Sie Python-Bibliotheken benötigen, die nur mit conda installiert werden können, können Sie conda-basierte Docker-Container verwenden, um die benötigten Bibliotheken vorab zu installieren.

Anaconda Inc. hat die Vertragsbedingungen für die Kanäle von anaconda.org im September 2020 aktualisiert. Gemäß den neuen Vertragsbedingungen benötigen Sie nun möglicherweise eine kommerzielle Lizenz für die Nutzung der Paket- und Verteilungslösung von Anaconda. Weitere Informationen finden Sie unter Anaconda Commercial Edition FAQ (Häufig gestellte Fragen zu Anaconda Commercial Edition). Jegliche Nutzung von Anaconda-Kanälen unterliegt den Anaconda-Vertragsbedingungen.

Aufgrund dieser Änderung hat Databricks die Standardkanalkonfiguration für den Conda-Paket-Manager entfernt. Dies ist eine wichtige Änderung.

Um Pakete mit dem %conda-Befehl zu installieren oder zu aktualisieren, müssen Sie einen Kanal mit -c angeben. Sie müssen außerdem die gesamte Verwendung von %conda install und %sh conda install aktualisieren, um einen Kanal mit -c anzugeben. Wenn Sie keinen Kanal angeben, wird für Conda-Befehle der Fehler PackagesNotFoundError angezeigt.

Der %conda-Befehl entspricht dem conda-Befehl und unterstützt dieselbe API mit einigen der unten aufgeführten Einschränkungen. Die folgenden Abschnitte enthalten Beispiele für die Verwendung von %conda-Befehlen zum Verwalten Ihrer Umgebung. Weitere Informationen zum Installieren von Python-Paketen mit conda finden Sie in der Dokumentation zur conda-Installation.

Beachten Sie, dass %conda-Magic-Befehle auf Databricks Runtime nicht verfügbar sind. Sie sind nur für Databricks Runtime ML bis Databricks Runtime ML 8.4 und für Databricks Runtime für Genomics verfügbar. Databricks empfiehlt die Verwendung von pip zum Installieren von Bibliotheken. Weitere Informationen finden Sie unter Grundlegendes zu Conda und pip.

Wenn Sie sowohl %pip- als auch %conda-Befehle in einem Notebook verwenden müssen, siehe Interaktionen zwischen pip- und conda-Befehlen.

Hinweis

Die folgenden conda-Befehle werden nicht unterstützt, wenn sie mit %condaverwendet werden:

  • activate
  • create
  • init
  • run
  • env create
  • env remove

In diesem Abschnitt

Installieren einer Bibliothek mit %conda

%conda install matplotlib -c conda-forge

Deinstallieren einer Bibliothek mit %conda

%conda uninstall matplotlib

Speichern und Wiederverwenden oder Freigeben einer Umgebung

Wenn Sie ein Notebook von einem Cluster trennen, wird die Umgebung nicht gespeichert. Führen Sie die folgenden Schritte aus, um eine Umgebung zu speichern, damit Sie sie später wiederverwenden oder für eine andere Person freigeben können.

Databricks empfiehlt, Umgebungen nur zwischen Clustern freizugeben, auf denen die gleiche Version von Databricks Runtime ML oder die gleiche Version von Databricks Runtime for Genomics ausgeführt wird.

  1. Speichern Sie die Umgebung als Conda-YAML-Spezifikation.

    %conda env export -f /dbfs/myenv.yml

  2. Importieren Sie die Datei über conda env update in ein anderes Notebook.

    %conda env update -f /dbfs/myenv.yml

Auflisten der Python-Umgebung eines Notebooks

Verwenden Sie %conda list, um die einem Notebook zugeordnete Python-Umgebung anzuzeigen:

%conda list

Interaktionen zwischen pip- und conda-Befehlen

Um Konflikte zu vermeiden, befolgen Sie diese Richtlinien, wenn Sie pip oder conda verwenden, um Python-Pakete und -Bibliotheken zu installieren.

  • Bibliotheken, die mithilfe der API oder der Clusterbenutzeroberfläche installiert werden, werden mit pipinstalliert. Wenn Bibliotheken über die API oder die Clusterbenutzeroberfläche installiert wurden, sollten Sie beim Installieren von Bibliotheken im Notebook-Bereich nur %pip-Befehle verwenden.
  • Wenn Sie Bibliotheken im Notebook-Bereich in einem Cluster verwenden, können in diesem Cluster ausgeführte Initialisierungsskripts entweder conda- oder pip-Befehle verwenden, um Bibliotheken zu installieren. Wenn das Initialisierungsskript jedoch pip-Befehle enthält, verwenden Sie nur %pip-Befehle in Notebooks (nicht %conda).
  • Es empfiehlt sich, entweder ausschließlich pip-Befehle oder ausschließlich conda-Befehle zu verwenden. Wenn Sie einige Pakete mit conda und einige mit pip installieren müssen, führen Sie zuerst die conda-Befehle aus, und führen Sie danach die pip-Befehle aus. Weitere Informationen finden Sie unter Verwenden von Pip in einer Conda-Umgebung.

Häufig gestellte Fragen (FAQ)

Wie interagieren Bibliotheken, die über die Clusterbenutzeroberfläche/-API installiert werden, mit Bibliotheken im Notebook-Bereich?

Bibliotheken, die über die Clusterbenutzeroberfläche oder -API installiert werden, sind für alle Notebooks im Cluster verfügbar. Diese Bibliotheken werden mit pip installiert. Wenn Bibliotheken über die Clusterbenutzeroberfläche installiert werden, verwenden Sie daher nur %pip-Befehle in Notebooks.

Wie interagieren Bibliotheken, die mithilfe eines Initialisierungsskripts installiert werden, mit Bibliotheken im Notebook-Bereich?

Bibliotheken, die mit einem Initialisierungsskript installiert werden, sind für alle Notebooks im Cluster verfügbar.

Wenn Sie Bibliotheken im Notebook-Bereich in einem Cluster verwenden, auf dem Databricks Runtime ML oder Databricks Runtime für Genomics ausgeführt wird, können Initialisierungsskripts, die im Cluster ausgeführt werden, entweder conda- oder pip-Befehle verwenden, um Bibliotheken zu installieren. Wenn das Initialisierungsskript jedoch pip-Befehle enthält, dann verwenden Sie nur %pip-Befehle in Notebooks.

Mit diesem Notebook-Codeausschnitt wird beispielsweise ein Skript generiert, das fast.ai-Pakete auf allen Clusterknoten installiert.

dbutils.fs.put("dbfs:/home/myScripts/fast.ai", "conda install -c pytorch -c fastai fastai -y", True)

Kann ich %pip- und %conda-Befehle in Auftragsnotebooks verwenden?

Ja.

Kann ich %pip- und %conda-Befehle in R- oder Scala-Notebooks verwenden?

Ja, in einer Python-Magic-Zelle.

Kann ich %sh pip oder %sh conda verwenden?

Databricks rät von der Verwendung von %sh pip ab, da sie nicht mit der Verwendung von %pip kompatibel ist.

Kann ich R-Pakete mit %conda-Befehlen aktualisieren?

Nein.

Bekannte Probleme

  • Bei Databricks Runtime 7.0 ML und niedriger sowie Databricks Runtime 7.0 für Genomics und niedriger funktioniert eine registrierte benutzerdefinierte Funktion in %sql-Zellen nicht, wenn eine registrierte benutzerdefinierte Funktion von Python-Paketen abhängig ist, die mit %pip oder %conda installiert wurden. Verwenden Sie spark.sql stattdessen in einer Python-Befehlsshell.
  • Wenn Sie Databricks Runtime 7.2 ML und niedriger oder Databricks Runtime 7.2 für Genomics und niedriger aktualisieren, wird die neue Umgebung bei Python-Workerprozessen nicht aktiviert, wenn Sie die Notebook-Umgebung mit %conda aktualisieren. Dies kann zu Problemen führen, wenn eine PySpark-UDF-Funktion eine Drittanbieterfunktion aufruft, die Ressourcen verwendet, die in der Conda-Umgebung installiert sind.
  • Wenn Sie %conda env update verwenden, um eine Notebookumgebung zu aktualisieren, ist die Installationsreihenfolge von Paketen nicht garantiert. Dies kann zu Problemen für das horovod-Paket führen, welches erfordert, dass tensorflow und torch vor horovod installiert werden müssen, um horovod.tensorflow bzw. horovod.torch zu verwenden. Deinstallieren Sie in diesem Fall das horovod-Paket, und installieren Sie es neu, nachdem Sie sichergestellt haben, dass die Abhängigkeiten installiert sind.