# Установка Transformers работает с [PyTorch](https://pytorch.org/get-started/locally/). Он был протестирован на Python 3.11+ и PyTorch 2.6+. ## Виртуальное окружение [uv](https://docs.astral.sh/uv/) — это чрезвычайно быстрый менеджер пакетов и проектов Python на базе Rust, который по умолчанию требует [виртуальное окружение](https://docs.astral.sh/uv/pip/environments/) для управления различными проектами и позволяет избежать проблем совместимости между зависимостями. Его можно использовать как прямую замену для [pip](https://pip.pypa.io/en/stable/), но если вы предпочитаете использовать pip, удалите `uv` из команд ниже. > [!TIP] > См. документацию по [установке](https://docs.astral.sh/uv/guides/install-python/) uv, чтобы установить uv. Создайте виртуальное окружение для установки Transformers. ```bash uv venv .env source .env/bin/activate ``` ## Python Установите Transformers с помощью следующей команды. [uv](https://docs.astral.sh/uv/) — это быстрый менеджер пакетов и проектов для Python, написанный на Rust. Чтобы установить Transformers с PyTorch для GPU NVIDIA (CUDA), установите соответствующие драйверы CUDA для [PyTorch](https://pytorch.org/get-started/locally). Выполните команду ниже, чтобы проверить, обнаруживает ли ваша система GPU от NVIDIA. ```bash nvidia-smi ``` ```bash uv pip install "transformers[torch]" ``` Чтобы установить Transformers с PyTorch на устройства NVIDIA Spark (например, ноутбук RTX Spark) с архитектурой ARM64, установите PyTorch из индекса PyPI от NVIDIA. Эти устройства требуют ARM64-сборки PyTorch от NVIDIA, которые недоступны в стандартном индексе PyPI или в обычном индексе колёс PyTorch. Выполните команду ниже, чтобы проверить, обнаруживает ли ваша система GPU от NVIDIA. ```bash nvidia-smi ``` Установите PyTorch из индекса PyPI от NVIDIA, затем установите Transformers. ```bash uv pip install torch --index-url https://pypi.nvidia.com uv pip install transformers ``` Чтобы установить версию Transformers только для CPU, выполните следующую команду. ```bash uv pip install torch --index-url https://download.pytorch.org/whl/cpu uv pip install transformers ``` Чтобы установить Transformers с PyTorch для Intel GPU (XPU), установите соответствующие [драйверы Intel GPU (XPU) для PyTorch](https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-13.html) и добавьте URL-адрес индекса PyTorch для Intel GPU (XPU). После установки драйверов выполните команду ниже, чтобы [проверить, обнаруживает ли ваша система GPU Intel](https://dgpu-docs.intel.com/driver/verification.html). ```bash xpu-smi ``` ```bash uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu ``` Проверьте успешность установки с помощью следующей команды. Она должна вернуть метку и оценку для предоставленного текста. ```bash python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))" [{'label': 'POSITIVE', 'score': 0.9998704791069031}] ``` ### Установка из исходного кода Установка из исходного кода устанавливает *последнюю* версию библиотеки, а не *стабильную*. Это гарантирует, что у вас есть самые свежие изменения в Transformers, и полезно для экспериментов с новейшими функциями или исправления ошибок, которые ещё не были официально выпущены в стабильной версии. Недостаток состоит в том, что последняя версия не всегда стабильна. Если вы столкнетесь с какими-либо проблемами, пожалуйста, создайте [GitHub Issue](https://github.com/huggingface/transformers/issues), чтобы мы могли исправить их как можно скорее. Установите из исходного кода с помощью следующей команды. ```bash uv pip install git+https://github.com/huggingface/transformers ``` Проверьте успешность установки с помощью команды ниже. Она должна вернуть метку и оценку для предоставленного текста. ```bash python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))" [{'label': 'POSITIVE', 'score': 0.9998704791069031}] ``` ### Установка в режиме редактирования Установка в режиме [editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) полезна, если вы разрабатываете Transformers локально. Она связывает вашу локальную копию Transformers с [репозиторием](https://github.com/huggingface/transformers) Transformers, а не копирует файлы. Файлы добавляются в путь импорта Python. ```bash git clone https://github.com/huggingface/transformers.git cd transformers uv pip install -e . ``` > [!WARNING] > Вам необходимо сохранить локальную папку Transformers, чтобы продолжать её использовать. Обновите локальную версию Transformers с последними изменениями в основном репозитории с помощью следующей команды. ```bash cd ~/transformers/ git pull ``` ## conda [conda](https://docs.conda.io/projects/conda/en/stable/#) — это менеджер пакетов, не зависящий от языка программирования. Установите Transformers из канала [conda-forge](https://anaconda.org/conda-forge/transformers) в только что созданную виртуальную среду. ```bash conda install conda-forge::transformers ``` ## Настройка После установки вы можете настроить расположение кэша Transformers или настроить библиотеку для работы в автономном режиме. ### Каталог кэша При загрузке предобученной модели с помощью [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) модель скачивается с Hub и кэшируется локально. Если вы передаёте хеш коммита, Transformers использует локальный кэш для файлов этого коммита и не проверяет Hub повторно для каждого из них (включая файлы, отсутствие которых уже известно). Это поведение по умолчанию, если ревизия не указана. Если вы передаёте ветку или тег, Transformers обращается к Hub один раз в начале загрузки, чтобы выбрать коммит, а затем использует кэш для файлов этого коммита аналогичным образом. Каталог по умолчанию, задаваемый переменной окружения оболочки `HF_HUB_CACHE`, — это `~/.cache/huggingface/hub`. В Windows каталог по умолчанию — `C:\Users\username\.cache\huggingface\hub`. Кэшируйте модель в другой директории, изменив путь в следующих переменных окружения оболочки (перечислены по приоритету). 1. [HF_HUB_CACHE](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) (по умолчанию) 2. [HF_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) 3. [XDG_CACHE_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#xdgcachehome) + `/huggingface` (только если `HF_HOME` не задан) ### Офлайн-режим Для использования Transformers в автономной или защищённой файрволом среде необходимо заранее скачать и закэшировать файлы. Скачайте репозиторий модели с Hub с помощью метода [snapshot_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download). > [!TIP] > См. руководство [Загрузка файлов из Hub](https://hf.co/docs/huggingface_hub/guides/download), чтобы узнать о других способах загрузки файлов из Hub. Вы можете загружать файлы из конкретных ревизий, загружать их через CLI, а также фильтровать файлы, которые нужно загрузить из репозитория. ```py from huggingface_hub import snapshot_download snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model") ``` Установите переменную окружения `HF_HUB_OFFLINE=1`, чтобы предотвратить HTTP-вызовы к Hub при загрузке модели. Ещё один вариант загрузить только кэшированные файлы — установить `local_files_only=True` в [from_pretrained()](/docs/transformers/main/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained). ```py from transformers import LlamaForCausalLM model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True) ``` В режиме офлайн (или при `local_files_only=True`), если в кэше ранее было сохранено соответствие ветки или тега с коммитом при онлайн-загрузке, система всё равно может преобразовать ветку или тег в коммит. Если такое соответствие никогда не сохранялось, Transformers сохраняет запрошенную вами ветку или тег и продолжает обычную офлайн-загрузку. Вы получите те же попадания в кэш или ошибки об отсутствии файлов, что и при стандартной офлайн-загрузке.