hf-cloud-python-env-setup

Этот навык Hugging Face посвящён подготовке отдельной Python-среды перед выполнением SageMaker deployment, training job или другой AWS-автоматизации. Его центральное правило простое: не использовать системный Python и не устанавливать зависимости в него. Проект получает собственную среду, где интерпретатор, boto3 и awscli можно проверить независимо от других проектов. Такой порядок уменьшает риск, что локальный пакет, старая библиотека или случайно выбранный интерпретатор изменит результат облачного скрипта. В качестве поддерживаемой границы Python навык называет версии 3.10, 3.11 и 3.12. Версии 3.13 и новее предлагается не выбирать для этого workflow, потому что у ML-библиотек может не быть подходящих wheel-пакетов и разрешение зависимостей способно закончиться запутанной ошибкой. При этом фиксируется именно версия Python, а не произвольные версии пакетов: по умолчанию используются актуальные boto3 и awscli, если проекту не нужна явно заданная версия. Это не означает, что всякое окружение должно быть обновлено вслепую: конкретное ограничение версии допустимо, когда его требует пользователь или совместимость проекта. Изолированную среду можно создать предоставленным скриптом setup_env.py. Он проверяет наличие uv, использует его как быстрый путь, а при отсутствии переходит к стандартному модулю venv. По умолчанию создаётся .venv с Python 3.12; путь к каталогу и версию, например 3.11, можно передать аргументами. Скрипт рассчитан на повторный запуск и отказывается продолжать с неподдерживаемой версией. Ручной эквивалент также описан: uv venv либо python3.12 -m venv, после чего boto3 и awscli устанавливаются через интерпретатор созданной среды. После подготовки не требуется полагаться на активацию shell. Скрипты запускаются явным путём .venv/bin/python на macOS и Linux либо .venv/Scripts/python.exe в Windows. Для проверки установленных библиотек предусмотрен check_versions.py: он обращается к importlib.metadata.version(), а не к непоследовательному атрибуту module.__version__. Можно проверить boto3, botocore, awscli и передать дополнительные имена пакетов. Это позволяет отличить проблему отсутствующей библиотеки от ситуации, когда пакет был установлен в другой интерпретатор. Предоставленные deploy.py, deploy_async.py и teardown.py используют boto3 напрямую и получают URI образов из опубликованного AWS каталога Deep Learning Containers. SageMaker Python SDK тоже допустим, если он уже выбран проектом или нужен пользователю, но его следует устанавливать в ту же изолированную среду; он не заменяет зависимости bundled-скриптов. Для generative reranker нужно отдельно проверить выбор контейнера: автоматическая маршрутизация задачи text-ranking к TEI не подходит для causal-LM reranker, которому нужен vLLM. Ошибка credentials при SSO assumed-role в SDK при успешном aws sts get-caller-identity может указывать на сбой разрешения credentials в SDK, а не на неверные права AWS. Для расширенных задач можно добавить huggingface_hub или transformers в отдельный requirements-файл и установить их явным Python. Если pip сообщает о странном конфликте, первым делом проверяется версия Python и чистота .venv; если скрипт не находит модуль после успешной установки, сверяются пути pip и запускающего интерпретатора. Навык помогает стандартизировать окружение и порядок проверки, но не подтверждает права IAM, корректность региона, выбранного образа, модели, параметров SageMaker или безопасность конкретного deployment. После настройки остаются отдельные проверки AWS-конфигурации и бизнес-логики проекта.