설치

Transformers는 PyTorch와 함께 작동합니다. Python 3.11+ 및 PyTorch 2.6+에서 테스트되었습니다.

가상 환경

uv는 Rust 기반의 매우 빠른 Python 패키지 및 프로젝트 관리 도구로, 기본적으로 가상 환경을 사용하여 서로 다른 프로젝트를 관리하고 의존성 간의 호환성 문제를 방지합니다.

It can be used as a drop-in replacement for pip, but if you prefer to use pip, remove uv from the commands below.

uv를 설치하려면 uv 설치 문서를 참조하세요.

Transformers를 설치할 가상 환경을 생성합니다.

uv venv .env
source .env/bin/activate

Python

다음 명령어로 Transformers를 설치합니다.

uv는 Rust 기반의 빠른 Python 패키지 및 프로젝트 매니저입니다.

CUDA

NVIDIA Spark (ARM64)

CPU

Intel GPU (XPU)

다음 명령을 사용하여 설치가 성공적으로 완료되었는지 테스트하십시오. 제공된 텍스트에 대한 라벨과 점수를 반환해야 합니다.

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

소스에서 설치

소스에서 설치하면 라이브러리의 안정판이 아닌 최신 버전이 설치됩니다. 이를 통해 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 install은 Transformers를 로컬에서 개발할 때 유용합니다. 파일을 복사하는 대신 로컬의 Transformers 사본을 Transformers repository에 연결합니다. 파일은 Python의 import 경로에 추가됩니다.

git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .

사용을 계속하려면 로컬 Transformers 폴더를 유지해야 합니다.

다음 명령을 사용하여 main 저장소의 최신 변경 사항으로 Transformers의 로컬 버전을 업데이트하세요.

cd ~/transformers/
git pull

conda

conda는 언어에 구애받지 않는 패키지 매니저입니다. 새로 생성한 가상 환경에서 conda-forge 채널을 통해 Transformers를 설치하세요.

conda install conda-forge::transformers

설정

설치 후 Transformers 캐시 위치를 구성하거나 라이브러리를 오프라인 사용하도록 설정할 수 있습니다.

캐시 디렉터리

from_pretrained()로 사전 학습된 모델을 로드하면, 해당 모델은 Hub에서 다운로드되어 로컬에 캐시됩니다.

commit hash를 전달하면 Transformers는 해당 commit의 파일에 대해 로컬 캐시를 사용하고 Hub에서 각 파일을 다시 확인하지 않습니다(누락된 것으로 알려진 파일 포함). revision이 지정되지 않은 경우의 기본 동작입니다.

브랜치 또는 태그를 전달하면 Transformers는 로드 시작 시점에 Hub에 한 번만 연결하여 커밋을 선택한 후, 해당 커밋의 파일에 대해 동일한 방식으로 캐시를 사용합니다.

셸 환경 변수 HF_HUB_CACHE에 의해 지정된 기본 디렉토리는 ~/.cache/huggingface/hub입니다. Windows의 경우 기본 디렉토리는 C:\Users\username\.cache\huggingface\hub입니다.

다음 셸 환경 변수(우선순위 순으로 나열됨)의 경로를 변경하여 다른 디렉터리에 모델을 캐시합니다.

HF_HUB_CACHE (기본값)
HF_HOME
HF_HOME가 설정되지 않은 경우에만 XDG_CACHE_HOME + /huggingface

오프라인 모드

오프라인 또는 방화벽이 있는 환경에서 Transformers를 사용하려면 미리 다운로드하고 캐시된 파일이 필요합니다. snapshot_download 메서드를 사용하여 Hub에서 모델 저장소를 다운로드하세요.

Hub에서 파일을 다운로드하는 더 많은 옵션에 대해서는 Hub에서 파일 다운로드 가이드를 참조하세요. 특정 리비전에서 파일을 다운로드하거나, CLI에서 다운로드하거나, 저장소에서 다운로드할 파일을 필터링할 수도 있습니다.

from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

모델을 로드할 때 Hub에 대한 HTTP 호출을 방지하려면 환경 변수 HF_HUB_OFFLINE=1를 설정하세요.

캐시된 파일만 로드하려면 from_pretrained()에서 local_files_only=True를 설정하는 것도 하나의 방법입니다.

from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)

local_files_only=True로 설정된 오프라인 모드에서도 이전 온라인 로딩 시 해당 매핑이 캐시에 저장되어 있었다면 브랜치나 태그를 커밋으로 변환할 수 있습니다. 매핑이 저장된 적이 없다면 Transformers는 요청한 브랜치 또는 태그를 그대로 유지하고 일반적인 오프라인 로딩을 계속 진행합니다. 일반적인 오프라인 로딩과 동일한 캐시 히트 또는 파일 누락 오류가 발생합니다.

Update on GitHub