huggingface-dataset-publishinglisted
Install: claude install-skill black-yt/skills
# Hugging Face Dataset Publishing
## 核心原则
- 不要把 Hugging Face token 写进代码、notebook、README、日志或 git history；使用 `HF_TOKEN` 环境变量或 `huggingface-cli login`。
- 图片字段必须用 `datasets.Image` 特征类型，不要只上传本地图片路径字符串；多图字段用 `Sequence(Image())`。
- 上传前先本地构造 `Dataset`/`DatasetDict` 并检查 `features`、样本、图片解码和 JSON 字段。
- 上传后必须用 `load_dataset` 从 Hub 回读验证，确认图片能解码、metadata 可解析、split/config 正确。
- 上传完成后建议 `git clone https://huggingface.co/datasets/<org>/<repo>` 到本地，用 git 维护 `README.md`、dataset card、示例和后续小改动。
- 大数据或大量图片不要随手放在当前目录；明确构建目录、清理临时样本，不把 token、缓存或中间碎片提交。
如果用户贴出了明文 HF token，提醒其撤销/轮换该 token，并在后续代码中改用环境变量。
## 依赖与登录
安装依赖：
```bash
python -m pip install -U datasets huggingface_hub pillow
```
推荐登录方式：
```bash
export HF_TOKEN="hf_xxx"
huggingface-cli login --token "$HF_TOKEN"
```
Python 中只从环境变量读取：
```python
import os
from huggingface_hub import login
token = os.environ.get("HF_TOKEN")
if token:
login(token=token)
```
## 源码追溯
- `datasets` 和 `huggingface_hub` 版本更新较快；当 `Features`、`Image`、`Sequence`、`push_to_hub` 或 `load_dataset` 行为不符合预期时，优先查看当前安装版本源码。
- `module.__file__` 可定位安装路径。
- `inspect.getsource(...)` 可查看函数、类或方法实现。
- 源码只用于阅读和定位问题，不要改源码，不要直接修改 `site-packages`；需要修改依赖时先征得用户同意。
```bash
python - <<'PY'
import inspect
import datasets
import huggingface_hub
from datasets import Dataset, DatasetDict, Features, Image, Sequence, load_dataset
print("datasets:", datasets.__version__, datasets.__file__)
print("huggingface_hub:", huggingface_hub.__version__, huggingface_hub.__file__)
print("Dataset.push_