img2dataset 中文教程：先把 3 张图跑明白，再谈百万规模

img2dataset 接收 URL 清单，完成下载、图像变换、分片和元数据记录。当前可核对标签是 1.47.0。它解决数据工程问题，不会替你取得图片版权或训练授权。

1. 它在流水线里负责哪一段

Reader 把 txt、CSV、JSONL 或 Parquet 清单切成 Arrow 分片，distributor 把分片交给本机多进程、PySpark 或 Ray。每个 Downloader 进程用线程并发请求图片，由父线程解码、缩放并交给 Writer。最终得到图片或 tar、逐样本 JSON、Parquet 元数据和分片统计。

相比 WebDataset，img2dataset 偏向建库阶段，负责从 URL 生成 tar；WebDataset 偏向训练阶段，顺序读取已经存在的 tar。已有合格分片时直接用 WebDataset，无需重新下载。

2. 安装固定版本

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "img2dataset==1.47.0"
img2dataset --help

先在隔离环境安装，不要把云存储密钥写进命令历史。fsspec 可以读取 S3、GCS、SSH 与 Hugging Face 路径，相应配置可能包含访问凭据，也可能产生对象存储请求费和出网费。

3. 只用获授权的小清单试跑

mkdir -p input img2dataset-output
cat > input/urls.txt <<'EOF'
https://example.test/owned-image-1.jpg
https://example.test/owned-image-2.jpg
https://example.test/owned-image-3.jpg
EOF

img2dataset \
  --url_list=input/urls.txt \
  --output_folder=img2dataset-output \
  --output_format=webdataset \
  --processes_count=1 \
  --thread_count=8 \
  --image_size=256

示例域名只是占位符，必须替换为你有权处理的地址。官方默认 256 线程适合追求吞吐的场景，但第一次运行应先用 8 线程。观察带宽、DNS、远端 429、文件句柄、CPU、内存和磁盘，再逐步增加。

4. 默认安全项不要随手关

若来源提供可信哈希，可用 verify_hash 拒绝不匹配文件。它能发现内容变动或传输问题，但不能判断版权、恶意内容和数据质量。

5. 覆盖模式会真的删目录

源码在 incremental_mode=overwrite 时对输出路径执行递归删除。不要把输出设置成家目录、项目根目录、共享桶前缀或已有资料目录。最稳妥的做法是为每次任务创建新的专用目录，运行前打印绝对路径并检查其中内容。

6. 怎样验收第一次输出

find img2dataset-output -maxdepth 2 -type f | sort
du -sh img2dataset-output
python - <<'PY'
import glob, pyarrow.parquet as pq
for path in glob.glob("img2dataset-output/*.parquet")[:1]:
    table = pq.read_table(path)
    print(table.schema)
    print(table.to_pylist()[:3])
PY

核对 URL、状态、错误信息、原始尺寸、输出尺寸和 SHA-256。失败记录不能只看总数，要区分 404、限流、证书、解码和哈希不匹配。确认删除请求能追溯到对应分片后，再考虑扩大清单。

7. 输出格式怎么选

普通 files 便于查看，但百万级小文件会拖累文件系统；WebDataset 用 tar 分片，适合训练时顺序读取；Parquet 适合列式筛选；TFRecord 面向 TensorFlow，官方文档说明它在部分非本地文件系统上效率较低。选择应跟下游读取方式一致，而不是一味追求格式数量。

8. 1.47.0 与验证边界

官方 Git 标签与 setup.py 都显示 1.47.0。主分支 2025-08-16 的提交加入了可选的证书忽略开关，因此使用 main 时行为可能超过标签版本。生产任务应固定版本或 commit。

验证边界：未实测成功率、图片解码安全、吞吐、DNS、PySpark、Ray、云对象存储费用、远端限流或特定数据集的授权。文中命令是小规模验收路径，不是大规模抓取许可。

常见问题