Библиотеки Python на уровне ноутбука

Библиотеки уровня записной книжки позволяют создавать, изменять, сохранять, повторно использовать и предоставлять общий доступ к пользовательским средам Python, специфичным для конкретной записной книжки. Когда вы устанавливаете библиотеку, ограниченную этим ноутбуком, доступ к ней имеют только текущий ноутбук и все задания, связанные с ним. На другие записные книжки, подключенные к тому же кластеру, это не повлияет.

Библиотеки уровня блокнота не сохраняются между сеансами. Необходимо переустанавливать библиотеки, область действия которых ограничена записной книжкой, в начале каждого сеанса или при отсоединении записной книжки от кластера.

Databricks рекомендует использовать магическую команду %pip для установки библиотек Python, ограниченных областью действия ноутбука. На бессерверных записных книжках, работающих под управлением среды 5 или более поздней, можно также использовать %uv pip для более быстрых установок.

Вы можете использовать %pip в записных книжках, запланированных как задания. Если вам нужно управлять средой Python в ноутбуке Scala, SQL или R, используйте магическую команду %python вместе с %pip.

При работе с библиотеками, установленными на уровне записной книжки, объём трафика к узлу драйвера может увеличиться. Ознакомьтесь с рекомендациями по размеру узла драйвера.

Чтобы установить библиотеки для всех записных книжек, подключенных к кластеру, используйте библиотеки кластера. См. библиотеки для вычислительных процессов.

Полный обзор параметров, доступных для установки библиотек Python в Databricks, см. в статье об управлении средой Python.

Управление библиотеками с помощью команд %pip

Команда %pip эквивалентна команде pip и поддерживает тот же API. В следующих разделах приведены примеры использования команд %pip для управления средой. Для получения дополнительной информации об установке пакетов Python с использованием pip см. документацию по установке pip и связанные с ней страницы.

Внимание

• команды %pip не перезапускают процесс Python автоматически. Если вы устанавливаете новый пакет или обновляете существующий пакет, может потребоваться использовать dbutils.library.restartPython() для просмотра новых пакетов. См . статью "Перезапуск процесса Python" в Azure Databricks.
• Обновление, изменение или удаление основных пакетов Python (например, IPython) с помощью %pip может привести к тому, что некоторые функции перестанут работать должным образом. При возникновении таких проблем сбросьте среду, перезагрузив кластер или запустив новый сеанс.

Быстрые установки с помощью %uv pip

Примечание.

%uv pip доступен только в бессерверных ноутбуках с версией среды 5 и выше. Классические вычислительные ресурсы и более ранние версии бессерверных сред не поддерживают %uv pip.

Магическая %uv pip команда является более быстрой альтернативой %pip. %uv pip работает на основе менеджера пакетов uv и использует ту же виртуальную среду notebook, что и %pip, поэтому пакеты, установленные с помощью одного инструмента, доступны и в другом.

%uv pip быстрее, чем %pip для установок и операций только для чтения, таких как list. Это делает его хорошо подходящим для итерации поверх спецификации среды.

%uv pip поддерживает стандартные подкоманды pip: install, uninstall, list, show, freeze, check и tree.

%uv pip install simplejson

%uv pip list

Другие шаблоны установки на этой странице (тома, файлы рабочей области, файлы требований, управление версиями, частные репозитории) работают с %uv pip. В любом из этих примеров можно заменить %pip на %uv pip.

%uv pip Ограничения

• %uv pip uninstall не удается полностью удалить библиотеки, предварительно установленные в бессерверной среде. Удаляются только метаданные пакета. Базовые файлы остаются в файловой системе, и пакет по-прежнему импортируется.
• %uv pip не проверяет наличие конфликтов зависимостей в предварительно установленных библиотеках.
• После выполнения команд %uv pip на боковой панели среды блокнота некоторые предустановленные библиотеки могут отображаться как установленные пользователем. Это проблема с отображением и не влияет на функциональные возможности пакета.
• %uv pip предназначен для быстрой интерактивной итерации. Чтобы настроить воспроизводимую среду для блокнота, добавьте зависимости на боковой панели Environment блокнота.

Установка библиотеки с помощью %pip

%pip install matplotlib

Установите пакет wheel для Python с помощью %pip

%pip install /path/to/my_package.whl

Удалите библиотеку с помощью %pip

Примечание.

Вы не можете удалить библиотеку, включенную в примечания к выпуску Databricks Runtime: версии и совместимость, или библиотеку, установленную как библиотека кластера. Если установлена версия библиотеки, отличная от версии, входящей в Databricks Runtime или установленной в кластере, можно использовать %pip uninstall для возврата библиотеки к версии по умолчанию в Databricks Runtime или версии, установленной в кластере, но нельзя использовать команду %pip для удаления версии библиотеки, входящей в Databricks Runtime или установленной в кластере.

%pip uninstall -y matplotlib

Параметр -y является обязательным.

Установка библиотеки из системы управления версиями с помощью %pip

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

Вы можете добавить параметры в URL-адрес, чтобы указать такие элементы, как версия или подкаталог Git. Для получения дополнительной информации и примеров использования других систем управления версиями см. Поддержка VCS.

Установите приватный пакет с учетными данными, управляемыми секретами Databricks, с помощью %pip

pip поддерживает установку пакетов из частных источников с помощью базовой проверки подлинности, включая системы управления частными версиями и репозитории частных пакетов, такие как Nexus и Artifactory. Управление секретами доступно через API Databricks Secrets, который позволяет хранить токены аутентификации и пароли. Используйте DBUtils API для доступа к секретам из записной книжки. Обратите внимание, что в магических командах можно использовать $variables.

Чтобы установить пакет из частного репозитория, укажите URL-адрес репозитория с параметром --index-url до %pip install или добавьте его в файл конфигурации pip в ~/.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/

Аналогичным образом можно использовать управление секретами с помощью магических команд для установки частных пакетов из систем управления версиями.

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

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

Установка пакета из DBFS с помощью %pip

Внимание

Любой пользователь рабочей области может изменять файлы, хранящиеся в DBFS. Azure Databricks рекомендует хранить файлы в рабочих пространствах или в томах Unity Catalog.

С помощью %pip можно установить частный пакет, сохраненный в DBFS.

При отправке в DBFS файл автоматически переименовывается, заменяя пробелы, точки и дефисы символами подчеркивания. Для файлов pip колес Python требуется, чтобы имя файла использовало периоды в версии (например, 0.1.0) и дефисы вместо пробелов или подчеркивания, поэтому эти имена файлов не изменяются.

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

Установка пакета из тома с помощью %pip

Внимание

Эта функция предоставляется в режиме общедоступной предварительной версии.

В Databricks Runtime версии 13.3 LTS и выше можно использовать %pip, чтобы установить приватный пакет, сохраненный в томе.

Когда вы загружаете файл в том, он автоматически переименовывается: пробелы, точки и дефисы заменяются на символы подчёркивания. Для файлов pip колес Python требуется, чтобы имя файла использовало периоды в версии (например, 0.1.0) и дефисы вместо пробелов или подчеркивания, поэтому эти имена файлов не изменяются.

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

Установить пакет, сохранённый как файл рабочей области, с помощью %pip

Начиная с Databricks Runtime 11.3 LTS, вы можете использовать %pip, чтобы установить закрытый пакет, сохранённый как файл рабочей области.

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

Сохранение библиотек в файле требований

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

Все подкаталоги в пути к файлу должны уже существовать. Выполнение команды %pip freeze > /Workspace/<new-directory>/requirements.txt завершится ошибкой, если каталог /Workspace/<new-directory> еще не существует.

Использование файла требований для установки библиотек

Файл требований содержит список пакетов к установке с помощью pip. Пример использования файла требований:

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

См. Формат файла требований для получения дополнительной информации о requirements.txt файлах.

Рекомендации по размеру узла драйвера

Использование библиотек, ограниченных записной книжкой, может привести к увеличению трафика на узел драйвера, поскольку на него ложится задача поддерживать согласованность среды на узлах-исполнителях.

При использовании кластера с 10 или более узлами в Databricks рекомендуется использовать следующие спецификации в качестве минимальных требований для узла драйвера:

• Для кластера ЦП 100 узлов используйте Standard_D8ds_v5.
• Для кластера GPU из 10 узлов используйте Standard_NC12.

Для кластеров большего объема используйте узел драйвера большего размера.

Различия между %pip, %sh pipи !pip

%sh и ! выполняют команду оболочки в ноутбуке; первый — это вспомогательная магическая команда Databricks, а второй — функция IPython. pip — это сокращённая форма записи для %pip, когда automagic включён, что используется по умолчанию в Python-ноутбуках Azure Databricks.

В Databricks Runtime 11.3 LTS и выше %pip, %sh pip и !pip все устанавливают библиотеку Python с областью действия в рамках записной книжки. В Databricks Runtime 10.4 LTS и более ранних версиях Databricks рекомендует использовать только %pip или pip для установки библиотек уровня записной книжки. Поведение %sh pip и !pip не согласовано в Databricks Runtime 10.4 LTS и ниже.

Известные проблемы

• В среде Databricks Runtime 9.1 LTS библиотеки уровня записной книжки несовместимы с пакетными заданиями потоковой обработки. Databricks рекомендует вместо этого использовать библиотеки кластеров или ядро IPython.