# 문제 해결

오류가 발생하는 경우가 있지만, 도움을 드리기 위해 이 가이드를 준비했습니다. 이 가이드에서는 가장 흔하게 발생하는 문제 몇 가지와 해결 방법을 다룹니다. 다만, 이 가이드는 모든 🤗 Transformers 문제를 포괄적으로 다루는 것이 아닙니다. 문제 해결에 대한 추가 도움이 필요하면 다음을 시도해 보세요:

1. [포럼](https://discuss.huggingface.co/)에서 도움을 요청할 수 있습니다. [Beginners](https://discuss.huggingface.co/c/beginners/5)나 [🤗 Transformers](https://discuss.huggingface.co/c/transformers/9)와 같이 질문을 게시할 수 있는 특정 카테고리가 있습니다. 문제가 해결될 가능성을 높이기 위해 재현 가능한 코드를 포함하여 설명이 잘 된 포럼 게시글을 작성하는 것이 좋습니다!

2. 라이브러리와 관련된 버그인 경우 🤗 Transformers 저장소에 [Issue](https://github.com/huggingface/transformers/issues/new/choose)를 생성하세요. 버그를 설명하는 정보를 최대한 포함하여 무엇이 잘못되었는지 파악하고 어떻게 수정할 수 있는지 확인하는 데 도움이 되도록 하세요.

3. 구버전의 🤗 Transformers를 사용 중이라면 버전 간에 중요한 변경 사항이 도입되었으므로 [Migration](https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md) 가이드를 확인하세요.

문제 해결 및 도움 요청에 대한 자세한 내용은 Hugging Face 코스의 [8장](https://huggingface.co/course/chapter8/1?fw=pt)을 참고하세요.

## 방화벽이 적용된 환경

클라우드 및 인트라넷 환경의 일부 GPU 인스턴스는 외부 연결에 대해 방화벽이 설정되어 있어 연결 오류가 발생할 수 있습니다. 스크립트가 모델 가중치 또는 데이터셋을 다운로드하려고 하면, 다운로드가 중단된 후 다음과 같은 메시지와 함께 시간 초과가 발생합니다:

```text
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.
```

이 경우 연결 오류를 피하기 위해 [오프라인 모드](installation#offline-mode)에서 🤗 Transformers를 실행해 보시기 바랍니다.

## CUDA 메모리 부족

수백만 개의 파라미터를 가진 대규모 모델을 학습하려면 적절한 하드웨어가 필요합니다. GPU 메모리가 부족할 때 흔히 발생하는 오류는 다음과 같습니다:

```text
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](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments)의 [per_device_train_batch_size](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments.per_device_train_batch_size) 값을 줄입니다.
- [TrainingArguments](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments)에서 [gradient_accumulation_steps](/docs/transformers/v5.23.0/ko/main_classes/trainer#transformers.TrainingArguments.gradient_accumulation_steps)를 사용하여 전체 배치 크기를 효과적으로 늘려 보세요.

메모리 절약 기술에 대한 자세한 내용은 [최적화 개요](optimization_overview)를 참조하세요.

## ImportError

특히 새로 출시된 모델의 경우, `ImportError`와 같은 또 다른 일반적인 오류를 마주할 수 있습니다:

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

이러한 오류 유형의 경우, 최신 모델을 사용하려면 🤗 Transformers의 최신 버전이 설치되어 있는지 확인하세요:

```bash
pip install transformers --upgrade
```

## CUDA 오류: device-side assert이 트리거되었습니다

가끔 장치 코드 오류에 대한 일반적인 CUDA 오류에 직면할 수 있습니다.

```text
RuntimeError: CUDA error: device-side assert triggered
```

더 자세한 오류 메시지를 확인하려면 먼저 CPU에서 코드를 실행해 보세요. CPU로 전환하려면 다음 환경 변수를 코드 맨 앞에 추가하세요:

```py
>>> import os

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

다른 옵션은 GPU에서 더 나은 traceback을 받는 것입니다. 오류의 원인을 가리키도록 traceback을 표시하려면 다음 환경 변수를 코드의 맨 앞에 추가하세요:

```py
>>> import os

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

## 패딩 토큰이 마스킹되지 않으면 잘못된 출력이 발생합니다

일부 경우 `input_ids`에 패딩 토큰이 포함된 경우 출력 `hidden_state`가 올바르지 않을 수 있습니다. 이를 시연하기 위해 모델과 토크나이저를 로드합니다. 모델의 `pad_token_id`에 접근하여 값을 확인할 수 있습니다. 일부 모델의 경우 `pad_token_id`가 `None`일 수 있지만, 항상 수동으로 설정할 수 있습니다.

```py
>>> from transformers import AutoModelForSequenceClassification
>>> import torch

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

다음 예제는 padding 토큰을 마스킹하지 않은 출력을 보여줍니다:

```py
>>> 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>)
```

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

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

대부분의 경우, 이러한 조용한 오류를 방지하기 위해 패딩 토큰을 무시하도록 모델에 `attention_mask`를 제공해야 합니다. 이제 두 번째 시퀀스의 출력이 실제 출력과 일치합니다:

기본적으로 토크나이저는 특정 토크나이저의 기본값에 따라 `attention_mask`를 자동으로 생성합니다.

```py
>>> 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는 padding 토큰이 제공된 경우에도 해당 padding 토큰을 가리기 위해 `attention_mask`를 자동으로 생성하지 않습니다. 그 이유는 다음과 같습니다:

- 일부 모델에는 패딩 토큰이 없습니다.
- 일부 사용 사례에서는 모델이 패딩 토큰에 주의를 기울이도록 하는 것이 필요합니다.

## ValueError: Unrecognized configuration class XYZ for this kind of AutoModel

일반적으로 사전 학습된 모델 인스턴스를 로드할 때 [AutoModel](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoModel) 클래스 사용을 권장합니다. 이 클래스는 설정을 기반으로 주어진 체크포인트에서 올바른 아키텍처를 자동으로 추론하고 로드할 수 있습니다. 체크포인트에서 모델을 로드할 때 이 `ValueError`가 발생하면, Auto 클래스가 주어진 체크포인트의 설정에서 로드하려는 모델 유형으로의 매핑을 찾지 못했다는 의미입니다. 가장 흔한 원인은 체크포인트가 특정 작업을 지원하지 않는 경우입니다. 예를 들어, 질문 답변용 GPT2가 없으므로 다음 예제에서는 이 오류가 발생합니다:

```py
>>> 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, ...
```

