Python-bibliotheken binnen Notebook

Met notebookbibliotheken kunt u aangepaste Python-omgevingen maken, wijzigen, opslaan, hergebruiken en delen die specifiek zijn voor een notebook. Wanneer u een bibliotheek met notebookbereik installeert, hebben alleen het huidige notitieblok en alle taken die aan dat notitieblok zijn gekoppeld, toegang tot die bibliotheek. Andere notebooks die aan hetzelfde cluster zijn gekoppeld, worden niet beïnvloed.

Notebook-scoped bibliotheken blijven niet behouden tussen sessies. U moet notebook-scoped bibliotheken opnieuw installeren aan het begin van elke sessie, of wanneer het notebook wordt losgekoppeld van een cluster.

Er zijn twee methoden voor het installeren van notebookbibliotheken:

  • Voer de %pip magic-opdracht uit in een notebook. Databricks raadt aan deze benadering te gebruiken voor nieuwe workloads. In dit artikel wordt beschreven hoe u deze magische opdrachten gebruikt.
  • In Databricks Runtime 10.5 en lager kunt u het azure Databricks-bibliotheekhulpprogramma gebruiken. Het bibliotheekhulpprogramma wordt alleen ondersteund in Databricks Runtime, niet in Databricks Runtime ML of Databricks Runtime voor Genomics. Zie Bibliotheekhulpprogramma (dbutils.library).

Als u bibliotheken wilt installeren voor alle notebooks die aan een cluster zijn gekoppeld, gebruikt u bibliotheken die in een werkruimte of een cluster zijn geïnstalleerd .

Belangrijk

dbutils.library.install en dbutils.library.installPyPI API's worden verwijderd in Databricks Runtime 11.0.

Vereisten

Notebookbibliotheken die magic-opdrachten gebruiken, zijn standaard ingeschakeld.

Op een cluster met hoge gelijktijdigheid waarop Databricks Runtime 7.4 ML of Databricks Runtime 7.4 voor Genomics of lager wordt uitgevoerd, zijn notebookbibliotheken niet compatibel met tabeltoegangsbeheer of referentiepassthrough. Een alternatief is om het bibliotheekhulpprogramma (dbutils.library) te gebruiken op een Databricks Runtime-cluster of om uw cluster te upgraden naar Databricks Runtime 7.5 ML of Databricks Runtime 7.5 voor Genomics of hoger.

Als u notebookbibliotheken wilt gebruiken met Databricks Connect, moet u het hulpprogramma Bibliotheek (dbutils.library) gebruiken.

Stuurprogrammaknooppunt

Het gebruik van notebookbibliotheken kan leiden tot meer verkeer naar het knooppunt van het stuurprogramma omdat dit werkt om de omgeving consistent te houden op alle uitvoerknooppunten.

Wanneer u een cluster met 10 of meer knooppunten gebruikt, raadt Databricks deze specificaties aan als minimale vereiste voor het stuurprogrammaknooppunt:

  • Gebruik voor een CPU-cluster met 100 knooppunten Standard_DS5_v2.
  • Gebruik Standard_NC12 voor een GPU-cluster met 10 knooppunten.

Gebruik voor grotere clusters een groter stuurprogrammaknooppunt.

Notebook-scoped bibliotheken installeren met %pip

Belangrijk

  • U moet alle %pip opdrachten aan het begin van het notitieblok plaatsen. De notebookstatus wordt opnieuw ingesteld na een %pip opdracht waarmee de omgeving wordt gewijzigd. Als u Python-methoden of -variabelen in een notebook maakt en vervolgens opdrachten in een latere cel gebruikt %pip , gaan de methoden of variabelen verloren.
  • Het upgraden, wijzigen of verwijderen van python-kernpakketten (zoals IPython) met %pip kan ertoe leiden dat sommige functies niet meer werken zoals verwacht. IPython 7.21 en hoger zijn bijvoorbeeld niet compatibel met Databricks Runtime 8.1 en lager. Als u dergelijke problemen ondervindt, stelt u de omgeving opnieuw in door het notebook los te koppelen en los te koppelen of door het cluster opnieuw op te starten.

Bibliotheken beheren met %pip opdrachten

De %pip opdracht is gelijk aan de pip-opdracht en ondersteunt dezelfde API. In de volgende secties ziet u voorbeelden van hoe u opdrachten kunt gebruiken %pip om uw omgeving te beheren. Zie de pip-installatiedocumentatie en gerelateerde pagina's voor meer informatie over het installeren van Python-pakketten metpip.

In deze sectie:

Een bibliotheek installeren met %pip

%pip install matplotlib

Een wielpakket installeren met %pip

%pip install /path/to/my_package.whl

Een bibliotheek verwijderen met %pip

Notitie

U kunt een bibliotheek die is opgenomen in Databricks Runtime of een bibliotheek die als clusterbibliotheek is geïnstalleerd, niet verwijderen. Als u een andere bibliotheekversie hebt geïnstalleerd dan de versie die is opgenomen in Databricks Runtime of de versie die op het cluster is geïnstalleerd, kunt u gebruiken %pip uninstall om de bibliotheek terug te zetten naar de standaardversie in Databricks Runtime of de versie die op het cluster is geïnstalleerd, maar u kunt een opdracht niet gebruiken %pip om de versie van een bibliotheek te verwijderen die is opgenomen in Databricks Runtime of die op het cluster is geïnstalleerd.

%pip uninstall -y matplotlib

De -y optie is vereist.

Een bibliotheek installeren vanuit een versiebeheersysteem met %pip

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

U kunt parameters toevoegen aan de URL om zaken op te geven, zoals de versie of git-submap. Zie vcs-ondersteuning voor meer informatie en voor voorbeelden van het gebruik van andere versiebeheersystemen.

Een privépakket installeren met referenties die worden beheerd door Databricks-geheimen met %pip

Pip ondersteunt het installeren van pakketten uit privébronnen met basisverificatie, waaronder systemen voor privéversiebeheer en opslagplaatsen voor privépakketten, zoals Nexus en Artifactory. Geheimbeheer is beschikbaar via de Databricks Secrets-API, waarmee u verificatietokens en wachtwoorden kunt opslaan. Gebruik de DBUtils-API voor toegang tot geheimen vanuit uw notebook. Houd er rekening mee dat u kunt gebruiken $variables in magic-opdrachten.

Als u een pakket wilt installeren vanuit een privéopslagplaats, geeft u de url van de opslagplaats op met de --index-url optie voor %pip install of voegt u het toe aan het pip configuratiebestand op ~/.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/

Op dezelfde manier kunt u geheimbeheer met magische opdrachten gebruiken om privépakketten van versiebeheersystemen te installeren.

token = dbutils.secrets.get(scope="scope", key="key")
%pip install git+https://<user>:$token@<gitprovider>.com/<path/to/repo>

Een pakket van DBFS installeren met %pip

U kunt gebruiken %pip om een privépakket te installeren dat is opgeslagen in DBFS.

Wanneer u een bestand uploadt naar DBFS, wordt de naam van het bestand automatisch gewijzigd, waarbij spaties, punten en afbreekstreepjes worden vervangen door onderstrepingstekens. Voor wielbestanden pip moet de naam van het bestand punten in de versie (bijvoorbeeld 0.1.0) en afbreekstreepjes gebruiken in plaats van spaties of onderstrepingstekens, zodat deze bestandsnamen niet worden gewijzigd.

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

Bibliotheken opslaan in een bestand met vereisten

%pip freeze > /dbfs/requirements.txt

Alle submappen in het bestandspad moeten al bestaan. Als u uitvoert %pip freeze > /dbfs/<new-directory>/requirements.txt, mislukt de opdracht als de map /dbfs/<new-directory> nog niet bestaat.

Een bestand met vereisten gebruiken om bibliotheken te installeren

Een bestand met vereisten bevat een lijst met pakketten die moeten worden geïnstalleerd met behulp van pip. Een voorbeeld van het gebruik van een vereistenbestand is:

%pip install -r /dbfs/requirements.txt

Zie Bestandsindeling voor vereisten voor meer informatie over requirements.txt bestanden.

Bibliotheken beheren met %conda opdrachten

Belangrijk

%conda opdrachten zijn afgeschaft en worden niet meer ondersteund na Databricks Runtime ML 8.4. Databricks raadt aan om te gebruiken %pip voor het beheren van notebookbibliotheken. Als u Python-bibliotheken nodig hebt die alleen kunnen worden geïnstalleerd met conda, kunt u docker-containers op basis van Conda gebruiken om de bibliotheken die u nodig hebt vooraf te installeren.

Anaconda Inc. heeft in september 2020 de servicevoorwaarden voor anaconda.org kanalen bijgewerkt. Op basis van de nieuwe servicevoorwaarden hebt u mogelijk een commerciële licentie nodig als u afhankelijk bent van de verpakking en distributie van Anaconda. Zie Veelgestelde vragen over Anaconda Commercial Edition voor meer informatie. Uw gebruik van Anaconda-kanalen is onderhevig aan hun servicevoorwaarden.

Als gevolg van deze wijziging heeft Databricks de standaardkanaalconfiguratie voor conda-pakketbeheer verwijderd. Dit is een belangrijke wijziging.

Als u pakketten wilt installeren of bijwerken met behulp van de %conda opdracht, moet u een kanaal opgeven met behulp van -c. U moet ook al het gebruik van %conda install en %sh conda install bijwerken om een kanaal op te geven met behulp van -c. Als u geen kanaal opgeeft, mislukken conda-opdrachten met PackagesNotFoundError.

De %conda opdracht is gelijk aan de conda-opdracht en ondersteunt dezelfde API met enkele beperkingen die hieronder worden vermeld. De volgende secties bevatten voorbeelden van het gebruik %conda van opdrachten om uw omgeving te beheren. Zie de conda-installatiedocumentatie voor meer informatie over het installeren van Python-pakketten metconda.

Houd er rekening mee dat %conda magic-opdrachten niet beschikbaar zijn in Databricks Runtime. Ze zijn alleen beschikbaar op Databricks Runtime ML tot Databricks Runtime ML 8.4 en op Databricks Runtime voor Genomics. Databricks raadt pip aan om bibliotheken te installeren. Zie Understanding conda and pip (Conda en pip) voor meer informatie.

Zie Interacties tussen pip- en conda-opdrachten als u zowel opdrachten als %pip%conda in een notebook moet gebruiken.

Notitie

De volgende conda opdrachten worden niet ondersteund bij gebruik met %conda:

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

In deze sectie:

Een bibliotheek installeren met %conda

%conda install matplotlib -c conda-forge

Een bibliotheek verwijderen met %conda

%conda uninstall matplotlib

Een omgeving opslaan en opnieuw gebruiken of delen

Wanneer u een notebook loskoppelt van een cluster, wordt de omgeving niet opgeslagen. Volg deze stappen om een omgeving op te slaan zodat u deze later opnieuw kunt gebruiken of met iemand anders kunt delen.

Databricks raadt aan omgevingen alleen te delen tussen clusters met dezelfde versie van Databricks Runtime ML of dezelfde versie van Databricks Runtime for Genomics.

  1. Sla de omgeving op als een Conda YAML-specificatie.

    %conda env export -f /dbfs/myenv.yml
    
  2. Importeer het bestand in een ander notitieblok met behulp van conda env update.

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

De Python-omgeving van een notebook weergeven

Als u de Python-omgeving wilt weergeven die is gekoppeld aan een notebook, gebruikt %conda listu :

%conda list

Interacties tussen pip opdrachten en conda

Als u conflicten wilt voorkomen, volgt u deze richtlijnen bij het gebruik pip van of conda om Python-pakketten en -bibliotheken te installeren.

  • Bibliotheken die zijn geïnstalleerd met behulp van de API of met behulp van de gebruikersinterface van het cluster, worden geïnstalleerd met behulp van pip. Als er bibliotheken zijn geïnstalleerd vanuit de API of de gebruikersinterface van het cluster, moet u alleen %pip opdrachten gebruiken bij het installeren van notebookbibliotheken.
  • Als u notebookbibliotheken in een cluster gebruikt, kunnen init-scripts die op dat cluster worden uitgevoerd, of opdrachten gebruiken condapip om bibliotheken te installeren. Als het init-script echter opdrachten bevat pip , gebruikt u alleen %pip opdrachten in notebooks (niet %conda).
  • U kunt het beste opdrachten uitsluitend of conda uitsluitend opdrachten gebruikenpip. Als u sommige pakketten moet installeren met conda en andere met pip, voert u eerst de conda opdrachten uit en voert u vervolgens de pip opdrachten uit. Zie Pip gebruiken in een Conda-omgeving voor meer informatie.

Veelgestelde vragen

Hoe communiceren bibliotheken die zijn geïnstalleerd vanuit de gebruikersinterface/API van het cluster met notebookbibliotheken?

Bibliotheken die zijn geïnstalleerd vanuit de gebruikersinterface of API van het cluster, zijn beschikbaar voor alle notebooks in het cluster. Deze bibliotheken worden geïnstalleerd met behulp van pip. Als bibliotheken worden geïnstalleerd met behulp van de gebruikersinterface van het cluster, gebruikt u daarom alleen %pip opdrachten in notebooks.

Hoe communiceren bibliotheken die zijn geïnstalleerd met behulp van een init-script met bibliotheken binnen notebookbereik?

Bibliotheken die zijn geïnstalleerd met behulp van een init-script, zijn beschikbaar voor alle notebooks in het cluster.

Als u notebookbibliotheken gebruikt in een cluster waarop Databricks Runtime ML of Databricks Runtime voor Genomics wordt uitgevoerd, kunnen init-scripts die op het cluster worden uitgevoerd, of opdrachten gebruiken condapip om bibliotheken te installeren. Als het init-script echter opdrachten bevat pip , gebruikt u alleen %pip opdrachten in notebooks.

Dit codefragment van het notebook genereert bijvoorbeeld een script waarmee fast.ai pakketten op alle clusterknooppunten worden geïnstalleerd.

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

Kan ik opdrachten en %conda gebruiken %pip in taaknotitieblokken?

Ja.

Kan ik opdrachten en %conda gebruiken %pip in R- of Scala-notebooks?

Ja, in een Python-magische cel.

Kan ik , !pipof pipgebruiken%sh pip? Wat is het verschil?

%sh en ! voer een shell-opdracht uit in een notebook; de eerste is een hulpmagieopdracht van Databricks, terwijl de laatste een functie van IPython is. pip is een afkorting voor %pip wanneer automagic is ingeschakeld. Dit is de standaardinstelling in Python-notebooks van Azure Databricks.

Op Databricks Runtime 11.0 en hoger %pipinstalleren , %sh pipen !pip allemaal een bibliotheek als een Python-bibliotheek met notebookbereik. In Databricks Runtime 10.4 LTS en lager raadt Databricks aan om alleen %pip of pip te gebruiken voor het installeren van notebookbibliotheken. Het gedrag van %sh pip en !pip is niet consistent in Databricks Runtime 10.4 LTS en lager.

Kan ik R-pakketten bijwerken met behulp van %conda opdrachten?

Nee.

Bekende problemen

  • Wanneer u gebruikt %conda env update om een notebookomgeving bij te werken, wordt de installatievolgorde van pakketten niet gegarandeerd. Dit kan problemen veroorzaken voor het horovod pakket, waarvoor dat tensorflow en torch vóór moeten worden geïnstalleerd horovod om respectievelijk of horovod.torch te kunnen gebruikenhorovod.tensorflow. Als dit gebeurt, verwijdert u het horovod pakket en installeert u het opnieuw nadat u ervoor hebt gezorgd dat de afhankelijkheden zijn geïnstalleerd.
  • In Databricks Runtime 10.3 en lager zijn notebookbibliotheken niet compatibel met batchstreamingtaken. Databricks raadt aan in plaats daarvan clusterbibliotheken of de IPython-kernel te gebruiken .