疑難排解

本指南旨在為您提供解決常見問題所需的工具與知識。如果本指南列出的建議未能解決您的情況，請參考尋求協助 (Asking for Help) 章節，了解如何針對特定問題尋求支援。

使用 push_to_hub 上傳資料集時遇到的問題

驗證問題

如果您在使用 Dataset.push_to_hub() 和 Hugging Face 存取權杖（access token）將資料集分享到 🤗 Hub 時遇到驗證問題：

請確保您用於驗證身分的 Hugging Face 權杖具有寫入 (write) 權限。
在 macOS 上，在使用 huggingface-cli login 之前，清理鑰匙圈存取（keychain access）中所有 huggingface.co 的密碼，並重新設定 git config --global credential.helper osxkeychain 可能會有幫助。

或者，您可以使用 SSH 金鑰來驗證身分——請詳閱 🤗 Hub 文件以了解更多資訊。

上傳大型資料集時連線中斷

在上傳大型資料集至 Hub 時，如果資料集的分片（shards）數量龐大，可能會在短時間內建立過多的提交（commits），導致連線錯誤。此類錯誤也可能由 Hub 內部使用的 AWS S3 bucket 回傳的 HTTP 500 錯誤引起。無論是哪種情況，您都可以重新執行 Dataset.push_to_hub() 來繼續上傳資料集。Hub 會檢查已上傳分片的 SHA 值，以避免重複上傳。我們正致力於提升上傳流程對暫時性錯誤的耐受性，因此建議您始終將程式庫更新至最新版本。

請求過多 (Too Many Requests)

透過 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）。

從自訂資料建立資料集時遇到的問題

從資料夾載入圖片與音訊

從資料夾建立資料集時，最常見的問題之一是檔案結構不符合預期格式，或是中繼資料檔（metadata file）有問題。

請在對應的文件頁面中進一步了解所需的資料夾結構：

序列化 (Pickling) 問題

使用 Dataset.from_generator 時的序列化問題

建立資料集時，IterableDataset.from_generator() 和 Dataset.from_generator() 要求提供一個可序列化的（picklable）產生器函數。這是為了能夠使用 pickle 對函數進行雜湊處理（hash），進而將資料集快取到磁碟上。

雖然產生器函數通常是「可序列化的」，但請注意產生器物件則不然。因此，如果您使用的是產生器物件，將會遇到類似這樣的 TypeError：

TypeError: cannot pickle 'generator' object

當使用的產生器函數依賴於「不可序列化」的全域物件（例如資料庫連線）時，也可能發生此錯誤。若是這種情況，您可以直接在產生器函數內部初始化該物件，以避免此錯誤。

Dataset.map 的序列化問題

序列化錯誤也可能發生在多處理程序（multiprocess）的 Dataset.map() 中——因為物件需要被序列化才能傳遞給子行程。如果轉換中使用的物件無法被序列化，則無法快取 map 的結果，進而導致錯誤。

以下是解決此問題的一些方法：

解決序列化問題的一個通用方案是透過實作 __getstate__ / __setstate__ / __reduce__，確保物件（或產生器類別）能夠手動被序列化。
您也可以在 map 中使用 new_fingerprint 引數來提供您自己的唯一雜湊值。
您也可以透過呼叫 datasets.disable_caching() 來停用快取，但這通常不建議這樣做——了解更多關於快取重要性的資訊。

尋求協助

如果上述疑難排解建議無法解決您的問題，請向社群和團隊尋求幫助。

論壇

請在 Hugging Face 論壇上尋求協助——將您的問題發佈在 🤗Datasets 分類中。務必撰寫詳細的貼文，並提供有關您的環境設定及可重現問題的程式碼，以最大限度提高問題獲得解決的機率！

Discord

在 Discord 上發文提問，讓團隊和社群為您提供協助。

🤗 Hub 上的社群討論

如果您在 Hub 上建立自訂資料集時遇到問題，您可以透過在資料集的「社群 (Community)」分頁中開啟討論，並附上以下訊息來請求 Hugging Face 團隊的協助。

# Dataset rewiew request for <Dataset name>

## Description

<brief description of the dataset>

## Files to review

- file1
- file2
- ...

cc @lhoestq @albertvillanova

GitHub Issues

最後，如果您懷疑發現了與程式庫本身的相關 Bug，請在 🤗 Datasets 的 GitHub 儲存庫上建立 Issue。請包含關於該 Bug 的背景資訊：可重現問題的程式碼片段、關於您的環境與資料的詳細資訊等，以幫助我們釐清問題並找出修復方法。

在 GitHub 上更新

資料集 (Datasets)