문제 해결

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

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

인증 문제

🤗 Hub에서 Dataset.push_to_hub()와 Hugging Face 액세스 토큰을 사용하여 데이터셋을 공유할 때 인증 문제를 겪고 있다면:

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

대신 SSH 키를 사용하여 본인 인증을 수행할 수 있습니다. 자세한 내용은 🤗 Hub 문서를 참고하세요.

대용량 데이터셋 업로드 중 연결 끊김

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

요청이 너무 많습니다

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

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
• ImageFolder

Pickling 문제

Dataset.from_generator 사용 시 Pickling 문제

When creating a dataset, IterableDataset.from_generator() and Dataset.from_generator() expect a “picklable” generator function. This is required to hash the function using pickle to be able to cache the dataset on disk.

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

TypeError: cannot pickle 'generator' object

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

Dataset.map의 Pickling 문제

Pickling 오류는 멀티프로세스 Dataset.map()에서도 발생할 수 있습니다. 객체는 자식 프로세스로 전달되도록 pickling됩니다. 변환에 사용되는 객체가 pickling할 수 없다면 map의 결과를 캐시할 수 없으며, 이로 인해 오류가 발생합니다.

이 문제를 해결하는 몇 가지 방법은 다음과 같습니다:

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

도움 요청

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

포럼

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

Discord

Discord에 질문을 게시하고 팀과 커뮤니티의 도움을 받으세요.

🤗 Hub의 커뮤니티 토론

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

# Dataset rewiew request for <Dataset name>

## Description

<brief description of the dataset>

## Files to review

- file1
- file2
- ...

cc @lhoestq @albertvillanova

GitHub Issues

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