# 문제 해결

이 가이드는 일반적인 문제를 해결하는 데 필요한 도구와 지식을 제공하기 위한 것입니다. 이 가이드에 나열된 제안 사항이 해당 상황을 다루지 않는 경우, 구체적인 문제에 대한 도움을 받을 수 있는 방법을 배우려면 [도움 요청](#asking-for-help) 섹션을 참조하세요.

## `push_to_hub`로 데이터셋을 업로드할 때 발생하는 문제

### 인증 문제

🤗 Hub에서 [Dataset.push_to_hub()](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Dataset.push_to_hub)와 Hugging Face 액세스 토큰을 사용하여 데이터셋을 공유할 때 인증 문제를 겪고 있다면:

* 신원 인증에 사용하는 Hugging Face 토큰이 **write** 권한이 있는 토큰인지 확인하세요.
* OSX에서는 `hf auth login`을 사용하기 전에 키체인 접근에서 huggingface.co 비밀번호를 모두 정리하고 `git config --global credential.helper osxkeychain`을 다시 구성하는 것이 도움이 될 수 있습니다.

대신 SSH 키를 사용하여 본인 인증을 수행할 수 있습니다. 자세한 내용은 [🤗 Hub 문서](https://huggingface.co/docs/hub/security-git-ssh)를 참고하세요.
 
### 대용량 데이터셋 업로드 중 연결 끊김 

Hub에 대규모 데이터셋을 업로드할 때, 데이터셋 샤드 수가 많으면 짧은 시간 내에 Hub에 과도한 커밋이 생성될 수 있습니다. 이로 인해 연결 오류가 발생할 수 있습니다. 연결 오류는 Hub가 내부적으로 사용하는 AWS S3 버킷이 반환하는 HTTP 500 오류로도 발생할 수 있습니다. 어느 경우든 [Dataset.push_to_hub()](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Dataset.push_to_hub)를 다시 실행하여 데이터셋 업로드를 계속할 수 있습니다. Hub는 이미 업로드된 샤드의 SHA를 확인하여 재업로드를 방지합니다. 일시적 오류에 대해 업로드 프로세스를 더 견고하게 만드는 작업을 진행 중이므로, 항상 최신 라이브러리 버전으로 업데이트하는 것이 좋습니다.

### `Too Many Requests`

`push_to_hub()`를 통해 대규모 데이터셋을 업로드하면 오류가 발생할 수 있습니다:

```bash
HfHubHTTPError: 429 Client Error: Too Many Requests for url: ...
You have exceeded our hourly quotas for action: commit. We invite you to retry later.
```

이 문제를 겪는 경우, `datasets` 라이브러리를 최신 버전(최소 `2.15.0`)으로 업그레이드해야 합니다.

## 커스텀 데이터에서 데이터셋을 생성할 때 발생하는 문제

### 폴더에서 이미지 및 오디오 로드

폴더에서 데이터셋을 생성할 때 가장 흔한 문제 중 하나는 파일 구조가 예상된 형식을 따르지 않거나 메타데이터 파일에 문제가 있는 경우입니다.

해당 문서 페이지에서 필요한 폴더 구조에 대해 자세히 알아보세요:

* [AudioFolder](https://huggingface.co/docs/datasets/audio_dataset#audiofolder)
* [ImageFolder](https://huggingface.co/docs/datasets/image_dataset#imagefolder)

### Pickling 문제 

#### `Dataset.from_generator` 사용 시 Pickling 문제

When creating a dataset, [IterableDataset.from_generator()](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.IterableDataset.from_generator) and [Dataset.from_generator()](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Dataset.from_generator) expect a "picklable" generator function. This is required to hash the function using [`pickle`](https://docs.python.org/3/library/pickle.html) to be able to cache the dataset on disk.

제너레이터 함수는 일반적으로 "picklable"이지만, 제너레이터 객체는 그렇지 않다는 점에 유의하세요. 따라서 제너레이터 객체를 사용하는 경우 다음과 같은 `TypeError`가 발생합니다:

```bash
TypeError: cannot pickle 'generator' object
```

이 오류는 DB 연결과 같이 "picklable"하지 않은 전역 객체를 사용하는 제너레이터 함수를 사용할 때도 발생할 수 있습니다. 이 경우, 해당 객체를 제너레이터 함수 내부에서 직접 초기화하여 이 오류를 방지할 수 있습니다.

#### `Dataset.map`의 Pickling 문제

Pickling 오류는 멀티프로세스 [Dataset.map()](/docs/datasets/v5.2.0/ko/package_reference/main_classes#datasets.Dataset.map)에서도 발생할 수 있습니다. 객체는 자식 프로세스로 전달되도록 pickling됩니다. 변환에 사용되는 객체가 pickling할 수 없다면 `map`의 결과를 캐시할 수 없게 되어 오류가 발생합니다.

이 문제를 해결하는 몇 가지 방법은 다음과 같습니다:
* pickle 문제를 해결하는 보편적인 방법은 `__getstate__` / `__setstate__` / `__reduce__`를 구현하여 객체(또는 생성기 클래스)를 수동으로 pickle할 수 있도록 하는 것입니다.
* `map`에서 `new_fingerprint` 인수를 사용하여 고유한 해시를 직접 제공할 수도 있습니다.
* `datasets.disable_caching()`를 호출하여 캐싱을 비활성화할 수도 있지만, 이는 권장되지 않습니다. [캐시의 중요성에 대해 자세히 알아보기](cache)

## 도움 요청

위의 문제 해결 조언이 문제를 해결하는 데 도움이 되지 않았다면, 커뮤니티와 팀에 도움을 요청하세요.

### 포럼 

Hugging Face 포럼에서 도움을 요청하세요 - [🤗Datasets 카테고리](https://discuss.huggingface.co/c/datasets/10)에 질문을 게시하세요. 문제가 해결될 가능성을 높이기 위해, 설정에 대한 관련 컨텍스트와 재현 가능한 코드를 포함하여 설명적인 게시글을 작성하는 것이 중요합니다!

### Discord

[Discord](http://hf.co/join/discord)에 질문을 게시하고 팀과 커뮤니티의 도움을 받으세요.

### 🤗 Hub의 커뮤니티 토론

Hub에서 커스텀 데이터셋을 생성하는 중 문제가 발생하면, 데이터셋의 Community 탭에서 아래 메시지와 함께 discussion을 열어 Hugging Face 팀에게 도움을 요청할 수 있습니다:

```text
# Dataset rewiew request for <Dataset name>

## Description

<brief description of the dataset>

## Files to review

- file1
- file2
- ...

cc @lhoestq @albertvillanova
```

### GitHub Issues

마지막으로, 라이브러리 자체와 관련된 버그를 발견했다고 의심되는 경우, 🤗 Datasets [GitHub 저장소](https://github.com/huggingface/datasets/issues)에 Issue를 생성하세요. 버그에 대한 컨텍스트를 포함하여 문제를 파악하고 수정하는 데 도움을 주세요. 재현을 위한 코드 스니펫, 환경 및 데이터에 대한 세부 정보 등이 해당됩니다.