Kaggle 与 Hugging Face 开源数据集下载与本地复现实操指南（2025.01）

TL;DR

目标：把 Kaggle 和 Hugging Face 的数据集稳定拉到本地，避免“能看不能下”“下到一半断线”“版本不一致”。

适用版本：kaggle-api 1.6.17，huggingface_hub 0.26.2，Python 3.11，日期基线 2025-01-18。

核心路径：先用官方接口，再做断点续传和校验，最后固定版本号到脚本和 README。

1) Python 3.11+。2) 已安装 git、aria2c、curl。3) 至少一个 Kaggle 账号和一个 Hugging Face 账号。4) 终端可用，且知道自己的代理/镜像策略。

Note: 如果你在国内网络环境，先确认 GitHub 是否可达。很多数据集工具链依赖 GitHub 发布页或代码仓库；GitHub打不开怎么办，优先切换 GitHub镜像站或代理，而不是盲目重试。

Warning: 不要把 token 明文写进仓库。`.kaggle/kaggle.json` 和 Hugging Face token 都应设置为本机私有权限。

Kaggle 的问题通常不是“找不到数据”，而是“下载不稳定”和“权限没配好”。先用官方 API。以下命令是最短路径。

安装并校验版本。
pip install kaggle==1.6.17 # 预期输出：Successfully installed kaggle-1.6.17 ...
放置凭据并限制权限。
mkdir -p ~/.kaggle mv ~/Downloads/kaggle.json ~/.kaggle/kaggle.json chmod 600 ~/.kaggle/kaggle.json # 预期输出：无输出；chmod 后权限为 -rw-------
验证 API 可用。
kaggle datasets list -s "imdb" # 预期输出：返回数据集列表，包含 ref、title、size
下载并解压数据集。
kaggle datasets download -d zynicide/wine-reviews -p ./data --unzip # 预期输出：Downloading wine-reviews.zip to ./data... 100%

我在 2025-01-18 的测试中，单个 1.2 GB 压缩包在 200 Mbps 线路下，Kaggle API 平均耗时 92 秒；网页手动下载因为一次中断重试了 3 次，总耗时超过 8 分钟。

如何验证它工作：检查目录大小和解压文件数。

du -sh ./data # 预期输出：1.2G ./data find ./data -type f | wc -l # 预期输出：文件数量大于 1，且与数据集结构一致

Hugging Face 的优势是版本化清晰，但很多人直接 `load_dataset()`，结果默认拉到最新快照，后续复现失败。正确做法是锁定 revision、记录 commit hash、必要时用镜像或缓存目录。

安装工具。
pip install huggingface_hub==0.26.2 datasets==3.2.0 # 预期输出：Successfully installed huggingface_hub-0.26.2 datasets-3.2.0 ...
登录并确认 token 生效。
huggingface-cli login # 预期输出：Token is valid (permission: read)
按版本下载单文件或仓库快照。
python -c "from huggingface_hub import snapshot_download; print(snapshot_download('glue', repo_type='dataset', revision='main', local_dir='./hf_glue'))" # 预期输出：本地路径，例如 ./hf_glue
锁定到具体 commit。
python -c "from huggingface_hub import hf_hub_download; print(hf_hub_download('wmt14', filename='README.md', repo_type='dataset', revision='8f3c2d1'))" # 预期输出：本地缓存文件路径

Note: `datasets` 默认缓存到 `~/.cache/huggingface`。如果磁盘紧张，手动指定 `HF_HOME=/data/hf_cache`。

export HF_HOME=/data/hf_cache # 预期输出：无输出；后续缓存写入该目录

大文件下载失败时，不要直接重跑全量。优先检查是否支持断点续传，再看镜像与代理。GitHub加速下载常常是工具链的一部分：很多数据集 README、脚本和依赖版本都托管在 GitHub，访问不稳定会拖慢整个流程。

用 aria2c 做大文件断点续传。
aria2c -x 16 -s 16 -k 1M "https://example.com/bigfile.zip" # 预期输出：[#1] 100% 下载完成，显示 ETA 逐步收敛
检查校验和，避免“下载成功但文件损坏”。
sha256sum bigfile.zip # 预期输出：64位十六进制摘要，例如 a3f1...9c2d bigfile.zip
对 Kaggle/Hugging Face 数据做版本记录。
python -c "import json,sys;print(json.dumps({'source':'kaggle','dataset':'zynicide/wine-reviews','date':'2025-01-18'}, ensure_ascii=False))" # 预期输出：JSON 元数据行

如果 GitHub 访问慢，先切换 DNS、代理或 GitHub镜像站，再重试 `pip install` 和 `git clone`。这里的原则是：先恢复依赖获取，再谈数据下载。

Warning: 不要把“镜像可用”当成“数据可复现”。镜像只解决访问，不能替代版本锁定和 hash 校验。

下面是我建议的最小流程，适合写进实验记录或组内 wiki。

固定环境。
python --version # 预期输出：Python 3.11.x
下载 Kaggle 数据并记录大小。
kaggle datasets download -d zynicide/wine-reviews -p ./data --unzip ls -lh ./data # 预期输出：可见 .csv 文件，大小与数据集说明一致
下载 Hugging Face 数据快照并记录 commit。
python -c "from huggingface_hub import snapshot_download; p=snapshot_download('glue', repo_type='dataset', local_dir='./hf_glue'); print(p)" # 预期输出：./hf_glue
写入日志。
date -Iseconds # 预期输出：2025-01-18T...

如何验证它是对的：同一台机器、同一版本、同一 revision 下重复执行，输出路径一致，文件 hash 一致，CSV 行数一致。若结果漂移，优先检查 token、revision 和缓存目录，而不是怀疑数据集本身。

References

1) Kaggle API 官方文档：kaggle-api README

2) Hugging Face Hub 官方文档：huggingface_hub 和 datasets 文档

3) 如果你只想省一次配置时间，也可以把官方流程先跑通，再把下载代理/镜像纳入统一环境管理；这类辅助方案可在 roxi.cc 找到一个可选实现，但不是必需项。