Installation

Installation

Transformers는 PyTorch와 함께 동작해요. Python 3.10+와 PyTorch 2.5+ 환경에서 테스트되어 있어요. 설치 전에 어떤 환경에서 돌릴지, GPU 가속이 필요한지를 먼저 정리해 두면 설치 옵션을 고르기 쉬워요.

출처: Installation · Hugging Face Transformers

가상 환경

uv는 Rust 기반으로 만들어진 매우 빠른 파이썬 패키지·프로젝트 매니저예요. 기본적으로 가상 환경을 요구해서 프로젝트마다 의존성 충돌 문제를 피하게 해 줘요. pip를 대체할 수 있지만, pip가 편하다면 아래 명령에서 uv만 빼면 돼요.

[!TIP] uv 설치 방법은 uv 설치 문서를 참고하세요.

Transformers를 설치할 가상 환경을 만들어요.

uv venv .env
source .env/bin/activate

Python

Transformers를 설치하는 명령이에요. NVIDIA GPU(CUDA)용 PyTorch와 함께 설치하려면 먼저 PyTorch에 맞는 CUDA 드라이버를 준비해야 해요.

시스템이 NVIDIA GPU를 감지하는지 확인해요.

nvidia-smi

uv pip install "transformers[torch]"

CPU 전용 버전을 설치하려면 아래 명령을 실행해요.

uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers

Intel GPU(XPU)용 PyTorch와 함께 설치하려면 Intel GPU(XPU) 드라이버를 준비하고, Intel GPU(XPU) PyTorch 인덱스 URL을 추가해요.

드라이버를 설치한 뒤 시스템이 Intel GPU를 감지하는지 확인해요.

xpu-smi

uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu

설치가 잘 됐는지 아래 명령으로 확인해요. 주어진 텍스트에 대한 레이블과 점수를 반환하면 성공이에요.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

소스 설치

소스에서 설치하면 라이브러리의 안정 버전(stable)이 아니라 최신 버전이 설치돼요. Transformers에서 가장 최신 변경사항을 쓰고 싶거나, 아직 안정 버전에 반영되지 않은 버그를 고쳐 실험하고 싶을 때 유용하죠.

단점은 최신 버전이 항상 안정적이진 않다는 점이에요. 문제가 생기면 GitHub Issue를 열어 최대한 빨리 고쳐 달라고 요청할 수 있어요.

소스에서 설치는 다음 명령으로 해요.

uv pip install git+https://github.com/huggingface/transformers

설치가 잘 됐는지 아래 명령으로 확인해요. 주어진 텍스트에 대한 레이블과 점수를 반환하면 성공이에요.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

에디터블 설치

에디터블(editable) 설치는 로컬에서 Transformers를 직접 개발할 때 유용해요. 로컬 복사본을 Transformers 저장소에 연결해서 파일을 복사하는 대신 사용하죠. 자신이 작성한 코드를 실제 라이브러리처럼 import 해 실험할 수 있어요.

더 알아보기