Hugging Face datasets 加载 WikiText 报错 HfUriError 的彻底解决

复现论文时，load_dataset("wikitext", "wikitext-2-raw-v1") 突然报错 HfUriError: Repository id must be 'namespace/name'。一番排查后，发现是 Hugging Face Hub 的引用规范更新所致。本文将详细剖析原因并提供两种可靠解决方案。

1. 问题重现

在运行以下代码时（常见于 NLP 实验）：

from datasets import load_dataset

dataset = load_dataset("wikitext", "wikitext-2-raw-v1", split="train")

突然抛出类似错误：

HfUriError: Invalid HF URI 'hf://datasets/wikitext@.../.huggingface.yaml'. 
Repository id must be 'namespace/name', got 'wikitext'.

即使在清除缓存后重试，问题依旧。

2. 错误根源

该错误源于 Hugging Face Hub 对数据集仓库引用方式的更新。在较新版本的 datasets 和 huggingface_hub 中，仓库标识符必须采用 namespace/repo_name 的完整格式。

• 旧版（或通过别名）允许直接使用 "wikitext"，内部会映射到正确的仓库。
• 新版严格要求 URI 解析时包含 namespace，因此 "wikitext" 被视为不完整，触发 HfUriError。

3. 解决方案

方案一：降级库版本（临时措施）

将 datasets 和 huggingface_hub 降级到已知兼容的版本：

pip install datasets==2.15.0 huggingface_hub==0.22.0

此时仍可使用 load_dataset("wikitext", ...)，但不推荐，因为后续功能更新将无法享受。

方案二：使用完整命名空间（推荐）

直接使用数据集的完整 Hugging Face 路径："Salesforce/wikitext"（WikiText 由 Salesforce 维护）。

修改后代码如下：

from datasets import load_dataset

# 使用完整命名空间
dataset_train = load_dataset("Salesforce/wikitext", "wikitext-2-raw-v1", split="train")
dataset_valid = load_dataset("Salesforce/wikitext", "wikitext-2-raw-v1", split="validation")

同时可以升级到最新库版本：

pip install -U datasets huggingface_hub

此方案符合 Hugging Face 官方推荐，更具前瞻性。

4. 其他注意事项

• 清除缓存：若之前加载失败，建议先删除旧缓存目录：

  rm -rf ~/.cache/huggingface/datasets/wikitext
  

• 网络环境：确保能正常访问 Hugging Face Hub（必要时设置代理或镜像）。
• 其他数据集：类似问题也可能出现在 imdb、gsm8k 等数据集上，同样使用 namespace/dataset 格式即可解决。

5. 完整代码示例（以 GPT-2 训练为例）

以下为融合命名空间修复的完整训练脚本片段：

from datasets import load_dataset
from transformers import GPT2Tokenizer

tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
tokenizer.pad_token = tokenizer.eos_token

# 使用命名空间加载
dataset_train = load_dataset("Salesforce/wikitext", "wikitext-2-raw-v1", split="train")
dataset_valid = load_dataset("Salesforce/wikitext", "wikitext-2-raw-v1", split="validation")

def tokenize(examples):
    return tokenizer(examples["text"], truncation=True, max_length=256, padding="max_length")

train_data = dataset_train.map(tokenize, batched=True, remove_columns=["text"])
valid_data = dataset_valid.map(tokenize, batched=True, remove_columns=["text"])
# ... 后续 DataLoader 等

6. 总结

问题现象	HfUriError 提示缺少 namespace/name
根本原因	Hugging Face Hub 引用规范升级，要求完整命名空间
推荐方案	使用 "Salesforce/wikitext" 替代 "wikitext"，并保持库为最新
备选方案	降级 datasets 和 huggingface_hub 到旧版本（不推荐）

通过简单替换数据集名称，即可解决此错误，且代码兼容未来版本。希望本文能帮助遇到同样问题的开发者快速定位并修复。