문제 해결

문제 해결 (Troubleshoot)

때로는 오류가 발생하기도 하지만, 저희가 도와드릴게요! 이 가이드는 우리가 본 가장 흔한 문제들과 그 해결 방법을 다뤄요. 하지만 이 가이드는 모든 🤗 Transformers 문제의 종합적인 모음은 아니라는 점을 알아두세요. 문제 해결에 더 많은 도움이 필요하면 다음을 시도해 보세요:

출처: 문서

본문

포럼에서 도움을 요청하세요. Beginners나 🤗 Transformers처럼 질문을 올릴 수 있는 특정 카테고리가 있어요. 문제가 해결될 가능성을 높이려면 재현 가능한 코드와 함께 설명이 잘 된 포럼 게시물을 꼭 작성하세요!
라이브러리 관련 버그라면 🤗 Transformers 저장소에 Issue를 만들어 주세요. 버그를 설명하는 정보를 최대한 많이 포함해서 무엇이 잘못됐고 어떻게 고칠 수 있는지 더 잘 파악할 수 있게 해주세요.
이전 버전의 🤗 Transformers를 사용한다면 v5 migration 가이드를 확인하세요. 버전 사이에 몇 가지 중요한 변경 사항이 도입됐기 때문이에요.

문제 해결과 도움 받기에 대한 자세한 내용은 Hugging Face 강좌의 Chapter 8을 살펴보세요.

방화벽 환경 (Firewalled environments)

클라우드와 인트라넷 환경의 일부 GPU 인스턴스는 외부 연결에 대해 방화벽이 설치되어 있어 연결 오류가 발생해요. 스크립트가 모델 가중치나 데이터셋을 다운로드하려고 하면 다운로드가 멈추고 시간 초과되며 다음과 같은 메시지가 나타나요:

ValueError: Connection error, and we cannot find the requested files in the cached path.
Please try again or make sure your Internet connection is on.

이 경우 연결 오류를 피하기 위해 🤗 Transformers를 오프라인 모드로 실행해 보세요.

CUDA 메모리 부족

수백만 개의 파라미터를 가진 대형 모델을 학습하는 것은 적절한 하드웨어가 없으면 까다로울 수 있어요. GPU 메모리가 고갈될 때 흔히 보는 오류는 다음과 같아요:

CUDA out of memory. Tried to allocate 256.00 MiB (GPU 0; 11.17 GiB total capacity; 9.70 GiB already allocated; 179.81 MiB free; 9.85 GiB reserved in total by PyTorch)

메모리 사용을 줄일 수 있는 몇 가지 해결 방법이 있어요:

TrainingArguments의 per_device_train_batch_size 값을 줄여요.
TrainingArguments의 gradient_accumulation_steps를 사용해 전체 배치 크기를 효과적으로 늘려 보세요.

메모리 절약 기법에 대한 자세한 내용은 Training > Performance > Memory optimization 섹션을 참고하세요.

ImportError

특히 새로 출시된 모델에서 흔히 보는 또 다른 오류는 ImportError예요:

ImportError: cannot import name 'ImageGPTImageProcessor' from 'transformers' (unknown location)

이런 오류 유형의 경우 최신 모델에 접근할 수 있도록 최신 버전의 🤗 Transformers가 설치되어 있는지 확인하세요:

pip install transformers --upgrade

CUDA error: device-side assert triggered

때로는 디바이스 코드의 오류에 관한 일반적인 CUDA 오류를 마주칠 수 있어요.

RuntimeError: CUDA error: device-side assert triggered

더 설명적인 오류 메시지를 얻으려면 코드를 먼저 CPU에서 실행해 보세요. 코드 시작 부분에 다음 환경 변수를 추가해서 CPU로 전환하세요:

>>> import os

>>> os.environ["CUDA_VISIBLE_DEVICES"] = ""

또 다른 방법은 GPU에서 더 나은 트레이스백을 얻는 거예요. 오류의 원인을 가리키는 트레이스백을 얻으려면 코드 시작 부분에 다음 환경 변수를 추가하세요:

>>> import os

>>> os.environ["CUDA_LAUNCH_BLOCKING"] = "1"

패딩 토큰이 마스킹되지 않을 때 잘못된 출력

어떤 경우에는 input_ids에 패딩 토큰이 포함되면 출력 hidden_state가 잘못될 수 있어요. 시연을 위해 모델과 토크나이저를 로드해 보겠어요. 모델의 pad_token_id에 접근해서 값을 볼 수 있어요. 일부 모델에서는 pad_token_id가 None일 수 있지만, 항상 수동으로 설정할 수 있어요.

>>> from transformers import AutoModelForSequenceClassification
>>> import torch

>>> model = AutoModelForSequenceClassification.from_pretrained("google-bert/bert-base-uncased")
>>> model.config.pad_token_id
0

다음 예시는 패딩 토큰을 마스킹하지 않은 출력을 보여줘요:

>>> input_ids = torch.tensor([[7592, 2057, 2097, 2393, 9611, 2115], [7592, 0, 0, 0, 0, 0]])
>>> output = model(input_ids)
>>> print(output.logits)
tensor([[ 0.0082, -0.2307],
        [ 0.1317, -0.1683]], grad_fn=<AddmmBackward0>)

두 번째 시퀀스의 실제 출력은 다음과 같아요:

>>> input_ids = torch.tensor([[7592]])
>>> output = model(input_ids)
>>> print(output.logits)
tensor([[-0.1008, -0.4061]], grad_fn=<AddmmBackward0>)

대부분의 경우 이러한 조용한 오류를 피하려면 모델에 attention_mask를 제공해서 패딩 토큰을 무시해야 해요. 이제 두 번째 시퀀스의 출력이 실제 출력과 일치해요:

기본적으로 토크나이저는 특정 토크나이저의 기본값에 따라 attention_mask를 만들어 줘요.

>>> attention_mask = torch.tensor([[1, 1, 1, 1, 1, 1], [1, 0, 0, 0, 0, 0]])
>>> output = model(input_ids, attention_mask=attention_mask)
>>> print(output.logits)
tensor([[ 0.0082, -0.2307],
        [-0.1008, -0.4061]], grad_fn=<AddmmBackward0>)

🤗 Transformers는 제공된 패딩 토큰을 마스킹하기 위해 attention_mask를 자동으로 만들지 않아요. 그 이유는:

일부 모델에는 패딩 토큰이 없어요.
일부 사용 사례에서는 사용자가 모델이 패딩 토큰에 주의를 기울이기를 원해요.

ValueError: Unrecognized configuration class XYZ for this kind of AutoModel

일반적으로 모델의 사전 훈련 인스턴스를 로드할 때 AutoModel 클래스를 사용하는 것을 권장해요. 이 클래스는 구성에 기반해 주어진 체크포인트에서 올바른 아키텍처를 자동으로 추론하고 로드할 수 있어요. 체크포인트에서 모델을 로드할 때 이 ValueError가 보인다면, Auto 클래스가 주어진 체크포인트의 구성에서 로드하려는 모델 종류로의 매핑을 찾지 못했다는 뜻이에요. 가장 흔하게는 체크포인트가 특정 작업을 지원하지 않을 때 발생해요. 예를 들어 다음 예시에서는 질문 답변용 GPT2가 없기 때문에 이 오류가 발생해요:

>>> from transformers import AutoProcessor, AutoModelForQuestionAnswering

>>> processor = AutoProcessor.from_pretrained("openai-community/gpt2-medium")
>>> model = AutoModelForQuestionAnswering.from_pretrained("openai-community/gpt2-medium")
ValueError: Unrecognized configuration class <class 'transformers.models.gpt2.configuration_gpt2.GPT2Config'> for this kind of AutoModel: AutoModelForQuestionAnswering.
Model type should be one of AlbertConfig, BartConfig, BertConfig, BigBirdConfig, BigBirdPegasusConfig, BloomConfig, ...