Python-Bibliotheken im Notebook-Bereich

  • Artikel

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.

Databricks empfiehlt die Verwendung des %pip-Magic-Befehls zum Installieren von Python-Bibliotheken im Notebookbereich.

Sie können %pip in Notebooks verwenden, geplant als Aufträge. Wenn Sie die Python-Umgebung in einem Scala-, SQL- oder R-Notebook verwalten müssen, verwenden Sie den %python-Magic-Befehl in Verbindung mit %pip.

Bei der Arbeit mit Bibliothekeninstallationen im Notebookbereich kann es zu mehr Datenverkehr zum Treiberknoten kommen. Weitere Informationen finden Sie unter Wie groß sollte der Treiberknoten bei der Arbeit mit Bibliotheken im Notebookbereich sein?.

Um Bibliotheken für alle Notebooks zu installieren, die einem Cluster zugeordnet sind, verwenden Sie Clusterbibliotheken. Weitere Informationen finden Sie unter Clusterbibliotheken.

Hinweis

Auf Databricks Runtime 10.4 LTS und früheren Versionen können Sie das (Legacy-)Azure Databricks-Bibliothekshilfsprogramm verwenden. Das Bibliothekshilfsprogramm wird nur in Databricks Runtime unterstützt, nicht in Databricks Runtime ML. Weitere Informationen finden Sie unter Bibliothekshilfsprogramm (dbutils.library) (Legacy).

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.

Wichtig

  • Ab Databricks Runtime 13.0 wird der Python-Prozess durch %pip-Befehle nicht automatisch neu gestartet. Wenn Sie ein neues Paket installieren oder ein vorhandenes Paket aktualisieren, müssen Sie möglicherweise dbutils.library.restartPython() verwenden, damit die neuen Pakete angezeigt werden. Weitere Informationen finden Sie unter Neustarten des Python-Prozesses in Azure Databricks.
  • Unter Databricks Runtime 12.2 LTS und niedriger sollten laut Databricks alle %pip-Befehle am Anfang des Notebooks stehen. 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. Wenn solche Probleme auftreten, setzen Sie die Umgebung zurück, indem Sie das Notebook trennen und erneut anfügen oder den Cluster neu starten.

Installieren einer Bibliothek mit %pip

%pip install matplotlib

Installieren eines Python-Wheel-Pakets mit %pip

%pip install /path/to/my_package.whl

Deinstallieren einer Bibliothek mit %pip

Hinweis

Bibliotheken, die in Versionshinweise zu Databricks Runtime-Versionen und -Kompatibilität enthalten sind, sowie Bibliotheken, die als Clusterbibliothek installiert wurden, 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

Wichtig

Alle Arbeitsbereichsbenutzer/-benutzerinnen können Dateien ändern, die im DBFS gespeichert sind. Azure Databricks empfiehlt das Speichern von Dateien in Arbeitsbereichen oder auf Unity Catalog-Volumes.

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. Bei Python-Wheel-Dateien erfordert pip, dass der Name der Datei Punkte in der Version (z. B. 0.1.0) und Bindestriche anstelle von Leerzeichen oder Unterstrichen verwendet, sodass diese Dateinamen nicht verändert werden.

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

Installieren eines Pakets von einem Volume mit %pip

Wichtig

Dieses Feature befindet sich in der Public Preview.

Mit Databricks Runtime 13.3 LTS und höher können Sie mithilfe von %pip ein privates Paket installieren, das auf einem Volume gespeichert wurde.

Wenn Sie eine Datei auf ein Volume hochladen, wird die Datei automatisch umbenannt. Dabei werden Leerzeichen, Punkte und Bindestriche durch Unterstriche ersetzt. Bei Python-Wheel-Dateien erfordert pip, dass der Name der Datei Punkte in der Version (z. B. 0.1.0) und Bindestriche anstelle von Leerzeichen oder Unterstrichen verwendet, sodass diese Dateinamen nicht verändert werden.

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

Installieren eines als Arbeitsbereichsdatei gespeicherten Pakets mit %pip

Mit Databricks Runtime 11.3 LTS und höher können Sie mithilfe von %pip ein privates Paket installieren, das als Arbeitsbereichsdatei gespeichert wurde.

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

Speichern von Bibliotheken in einer Anforderungsdatei

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

Alle Unterverzeichnisse im Dateipfad müssen bereits vorhanden sein. Wenn Sie %pip freeze > /Workspace/<new-directory>/requirements.txt ausführen, schlägt der Befehl fehl, wenn das Verzeichnis /Workspace/<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 /Workspace/shared/prod_requirements.txt

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

Wie groß sollte der Treiberknoten bei der Arbeit mit Bibliotheken im Notebookbereich sein?

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.

Kann ich %sh pip, !pip oder pip verwenden? Worin besteht der Unterschied?

%sh und ! führen einen Shell-Befehl in einem Notebook aus. Ersteres ist ein zusätzlicher Magic-Befehl von Databricks, während letzteres ein Feature von IPython ist. pip ist eine Abkürzung für %pip, wenn automagic aktiviert ist, was die Standardeinstellung in Azure Databricks Python-Notebooks ist.

Unter Databricks Runtime 11.3 LTS und höher installieren %pip, %sh pip und !pip eine Bibliothek als Python-Bibliothek im Notebookbereich. Für Databricks Runtime 10.4 LTS und niedriger empfiehlt Databricks, nur %pip oder pip zu verwenden, um auf den Notebookbereich bezogene Bibliotheken zu installieren. Das Verhalten von %sh pip und !pip ist in Databricks Runtime 10.4 LTS und niedriger nicht konsistent.

Bekannte Probleme

  • In Databricks Runtime 9.1 LTS sind Bibliotheken im Notebookbereich nicht mit Batchstreamingaufträgen kompatibel. Databricks empfiehlt stattdessen die Verwendung von Clusterbibliotheken oder dem IPython-Kernel.