Kaggle CLI Datasets上传文件教程（保姆级）

[Kaggle CLI](#Kaggle CLI)

（1）kaggle分批次上传文件环境

一、本地目录组织

二、具体操作命令

[1. 安装并配置 Kaggle CLI](#1. 安装并配置 Kaggle CLI)

[2. 第 1 批：创建 Dataset](#2. 第 1 批：创建 Dataset)

设置对应的代理：（以下终端设置代理针对当前终端有效，打开新的终端需要重新配置代理）

[① anaconda prompt终端](#① anaconda prompt终端)

[② powershell终端](#② powershell终端)

[③ Git Bash / CMD](#③ Git Bash / CMD)

[3. 第 2~N 批：版本更新追加文件（注意这里的version是全量替换，不是增强追加，也就是之前的文件会被替换）](#3. 第 2~N 批：版本更新追加文件（注意这里的version是全量替换，不是增强追加，也就是之前的文件会被替换）)

[四、在 Kaggle Notebook 中使用](#四、在 Kaggle Notebook 中使用)

五、注意事项

[六命令使用补充](#六命令使用补充)

数据集命令

[① kaggle datasets list 列出可用的数据集。](#① kaggle datasets list 列出可用的数据集。)

[② kaggle datasets files列出特定数据集的文件。](#② kaggle datasets files列出特定数据集的文件。)

[③ kaggle datasets download下载数据集文件。](#③ kaggle datasets download下载数据集文件。)

[④ kaggle datasets init初始化用于创建新数据集的元数据文件（dataset-metadata.json）。参见 $元数据文件格式$ (./datasets_metadata.md)。](#④ kaggle datasets init初始化用于创建新数据集的元数据文件（dataset-metadata.json）。参见元数据文件格式。)

[⑤ kaggle datasets create在 Kaggle 上创建新数据集。](#⑤ kaggle datasets create在 Kaggle 上创建新数据集。)

[⑥ kaggle datasets version](#⑥ kaggle datasets version)

[⑦ kaggle datasets metadata](#⑦ kaggle datasets metadata)

[⑧ kaggle datasets status](#⑧ kaggle datasets status)

[⑨ kaggle datasets delete](#⑨ kaggle datasets delete)

[⑩ kaggle datasets topics list](#⑩ kaggle datasets topics list)

[⑪ kaggle datasets topics show](#⑪ kaggle datasets topics show)

Kaggle CLI

（1）kaggle分批次上传文件环境

在 Kaggle 上把 Hugging Face 的大模型分批次、按原目录结构 上传到同一个根目录 playground 下，最佳方式是使用 Kaggle Dataset + 版本更新（Versioning）。

一、本地目录组织

先在本地创建一个 demo 文件夹，内部结构和 Hugging Face 下载的完全一致：

复制代码

demo/                          ← 根目录（最终挂载到 /kaggle/input/playground/）
├── dir1/
├── dir2/
├── file1.txt
├── file2.txt
└── README.md

二、具体操作命令

1. 安装并配置 Kaggle CLI

https://github.com/Kaggle/kaggle-cli

复制代码

pip install kaggle

在 Kaggle 账户设置下载 kaggle.json，放到：

Windows: C:\Users\<你的用户名>\.kaggle\kaggle.json
Linux/Mac: ~/.kaggle/kaggle.json

步骤：
- 注意：新版界面中，"Create New Token" 按钮可能在 "Legacy API Credentials" 子标题下，而不是页面最显眼的 API 区域。需要继续往下滑才能看到。
- 登录 kaggle.com
- 点击右上角头像 → Settings
- 在 Settings 页面向下滚动到底部，找到 "API" 区域
- 找到 "Legacy API Credentials" 小节
- 点击 "Create Legacy API Key"（或 "Create New Token"）
- 浏览器会自动下载 kaggle.json

2. 第 1 批：创建 Dataset

进入到Anaconda Prompt环境执行下面的相关命令，先把第一批小文件放进 demo/ 目录，然后：

复制代码

cd playground # 初始化元数据文件（只执行一次）

kaggle datasets init

编辑生成的 dataset-metadata.json

复制代码

{
  "title": "version01",
  "id": "你的kaggle用户名/version2",
  "licenses": [{"name": "apache-2.0"}]
}

https://github.com/Kaggle/kaggle-cli/blob/main/docs/datasets_metadata.md

|--------------|------------------------------------------|--------------------------|-----------------------|
| 字段 | 你的值 | 规则 | 是否合规 |
| title | "playground-v2.5-1024px-aesthetic"（33字符） | 6-50字符 | √ 合规 |
| id 用户名部分 | "KeepTryingTo" | 用户名slug | √ 合规（大写是alphanumeric） |
| id 数据集slug部分 | "playground-v2.5-1024px-aesthetic" | 3-50字符，仅alphanumeric+"-" | × 点号非法 |
| licenses | ${"name": "CC0-1.0"}$ | 必须恰好一个条目，name需合法 | √ 合规 |

注意：只要这个 json 文件里面的内容改变了，在之前初始化的前提下进行上传文件是连接失败，因此需要重新create，创建一个新的连接。

上传第 1 批（将当前目录下的文件上传，如果有子文件夹，则不会进行 递归 的上传子文件夹中的内容）：

复制代码

kaggle datasets create -p .

如果子文件夹也需要上传的话，使用zip模式，将文件的打包上传，然后自动解压

复制代码

kaggle datasets create -p . -r zip

--dir-mode（-r） zip：会将你的文件夹打包并压缩成一个 .zip 文件上传。
                Kaggle 服务器接收后会自动解压。
--dir-mode（-r） tar：会将文件夹打包成一个 .tar 归档文件上传，但不会进行压缩。
                这通常用于保留文件权限或当你不想让 API 自动压缩时。
--dir-mode（-r） skip：会直接忽略子目录，只上传当前目录下的文件。

注意：create每执行一次都会重新上传文件，可以使用的version追加上传文件，但是如果version执行时提示：Metadata file not found: dataset-metadata.json或者说当前的目录下面没有 json 文件（对应的子目录下面也要有JSON文件），说明之前的 create 彻底失败了，服务器上根本没有这个数据集。这时你只能重新运行 create（确保元数据已修正）。

如果存在以下问题：

-09-13 13:05:18,015 WARNING Retrying (Retry(total=7, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError(' <urllib3.connection.HTTPSConnection object at 0x00000144E0D82190>: Failed to establish a new connection: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。')': /upload/storage/v1/b/kaggle-data-sets/o? uploadType=resumable&upload_id=AJjja9ZdmJLO9gzxHQYhu7qo66H6gtn9_Yz1YytYQfGRn RwrV51e1gVH7SVhxSFKPRayfGafyDLNrDYUaFEsMUdTaTGdcOl2xgHYGvkwSlIFyg

这个错误 $WinError 10060$ 连接尝试失败表明你的网络无法连接到 Kaggle 的上传服务器（storage.googleapis.com）。这在国内网络环境下是非常典型的问题，因为 Kaggle 的数据存储依赖 Google Cloud Storage (GCS)，而 GCS 在国内大部分地区是被屏蔽或严重干扰的。

设置对应的代理：（以下终端设置代理针对当前终端有效，打开新的终端需要重新配置代理）

① anaconda prompt终端

复制代码

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890

② powershell终端

复制代码

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
kaggle datasets create -p .

③ Git Bash / CMD

复制代码

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
kaggle datasets create -p .

3. 第 2~N 批：版本更新追加文件（注意这里的version是全量替换，不是增强追加，也就是之前的文件会被替换）

把下一批文件（如 text_encoder/）复制进本地的 playground-v2.5-1024px-aesthetic/ 目录，然后执行：

复制代码

kaggle datasets version -p . -m "add text_encoder and text_encoder_2"

重复此步骤，直到所有文件夹和文件都上传完毕：

# 第 3 批：加入 unet, vae

复制代码

kaggle datasets version -p . -m "add unet and vae"

# 第 4 批：加入大权重文件

复制代码

kaggle datasets version -p . -m "add safetensors weights"

原理：每次 version 都会把本地 playground-v2.5-1024px-aesthetic/ 下的所有文件与云端对比，新增的文件会被追加，已有文件会被覆盖（如果本地有修改）。所以你可以逐批把新文件放进本地目录，再上传新版本。

四、在 Kaggle Notebook 中使用

上传完成后，在 Notebook 右侧点击 Add Data → Datasets，搜索并添加你的 Dataset。Kaggle 会自动挂载到：

复制代码

from diffusers import StableDiffusionPipeline
import torch # 路径结构完全保留
model_path = "/kaggle/input/playground-v25-models/playground"
pipe = StableDiffusionPipeline.from_pretrained( model_path, 
            torch_dtype=torch.float16, )

注意：挂载后的路径是 /kaggle/input/<dataset-id>/，如果你希望路径简洁，可以在 dataset-metadata.json 的 id 中直接用 playground 作为名称的一部分。

五、注意事项

|-----------------|-----------------------------------------------------------------------------|
| 问题 | 说明 |
| 单文件 20GB 限制 | Kaggle Dataset 单个文件上限约 20GB，如果 .safetensors 超过此限制，需要拆分成多卷或用 Kaggle Models |
| 总容量限制 | 免费账户 Dataset 总容量约 100GB，确保所有文件加起来不超限 |
| 上传中断 | 大文件上传如果中断，重新执行 kaggle datasets version 即可，已传完的小文件不会重复上传 |
| 路径保留 | 使用 CLI 上传会完整保留子目录结构，和 Hugging Face 下载下来的一模一样 |
| 网页端补充 | 如果 CLI 上传某一批次失败，也可以登录 Kaggle 网页，进入该 Dataset → New Version，拖拽补充上传 |

六命令使用补充

数据集命令

https://github.com/Kaggle/kaggle-cli/blob/main/docs/datasets.md 用于与 Kaggle 数据集交互的命令。

① kaggle datasets list 列出可用的数据集。

用法： kaggle datasets list [options]

选项：

--sort-by <SORT_BY>：对结果排序。有效选项：hottest、votes、updated、active（默认：hottest）。
--size <SIZE_CATEGORY>：已弃用。请改用 --min-size 和 --max-size。
--file-type <FILE_TYPE>：按文件类型筛选。有效选项：all、csv、sqlite、json、bigQuery。
--license <LICENSE_NAME>：按许可证筛选。有效选项：all、cc、gpl、odb、other。
--tags <TAG_IDS>：按标签筛选（逗号分隔的标签 ID）。
-s, --search <SEARCH_TERM>：搜索词。
-m, --mine：仅显示你自己的数据集。
--user <USER>：按特定用户或组织筛选。
-p, --page <PAGE>：结果的页码（默认：1）。
-v, --csv：以 CSV 格式打印结果。
--max-size <BYTES>：数据集的最大大小（字节）。
--min-size <BYTES>：数据集的最小大小（字节）。

示例：

列出你自己的数据集：kaggle datasets list -m
列出 CSV 类型的数据集：第 2 页、按最近更新排序、标题中包含 "student"、大小介于 13000 到 15000 字节之间：
复制代码
```
kaggle datasets list --file-type csv --page 2 --sort-by updated -s student --min-size 13000 --max-size 15000
```
列出带有 ODB 许可证、带有 "internet" 标签且匹配搜索词 "telco" 的数据集：
复制代码
```
kaggle datasets list --license odb --tags internet --search telco
```

**用途：**此命令可帮助你根据所有者、文件类型、标签和大小等各种条件在 Kaggle 上查找数据集。

② kaggle datasets files列出特定数据集的文件。

用法： kaggle datasets files <DATASET> [options]

参数：

<DATASET>：格式为 owner/dataset-name 的数据集 URL 后缀（例如 kerneler/brazilian-bird-observation-metadata-from-wikiaves）。

选项：

-v, --csv：以 CSV 格式打印结果。
--page-token <PAGE_TOKEN>：用于结果分页的页面令牌。
--page-size <PAGE_SIZE>：每页显示的条目数（默认：20，最大：200）。

示例： 列出数据集 kerneler/brazilian-bird-observation-metadata-from-wikiaves 的前 7 个文件：

kaggle datasets files kerneler/brazilian-bird-observation-metadata-from-wikiaves --page-size=7

**用途：**在下载之前，可使用此命令查看数据集内的各个文件。

③ kaggle datasets download下载数据集文件。

用法： kaggle datasets download <DATASET> [options]

参数：

<DATASET>：数据集 URL 后缀（例如 willianoliveiragibin/pixar-films）。

选项：

-f, --file <FILE_NAME>：要下载的特定文件（未指定则下载全部）。位于文件夹内的文件（例如 train/labels.csv）会在下载路径下保留该文件夹。
-p, --path <PATH>：下载文件的目标文件夹（默认为当前目录）。
-w, --wp：将文件下载到当前工作路径。
--unzip：解压已下载的文件（之后删除 .zip 文件）。与 -f 一起使用时，大文件会以同名 zip 压缩包的形式提供，此选项会从中解压出该文件。
-o, --force：强制下载，覆盖已有文件。
-q, --quiet：抑制详细输出。

示例：

下载数据集 willianoliveiragibin/pixar-films 的所有文件：kaggle datasets download -d willianoliveiragibin/pixar-films

下载数据集 goefft/public-datasets-with-file-types-and-columns，将其解压到 tmp 文件夹，必要时覆盖，并抑制输出：

复制代码

   kaggle datasets download goefft/public-datasets-with-file-types-and-columns -p tmp --unzip -o -q

从 goefft/public-datasets-with-file-types-and-columns 下载特定文件 dataset_results.csv 到当前工作目录，静默执行并强制覆盖：
复制代码
```
kaggle datasets download goefft/public-datasets-with-file-types-and-columns -f dataset_results.csv -w -q -o
```

复制代码

   kaggle datasets download mlg-ulb/creditcardfraud -f creditcard.csv -p data --unzip

下载数据集内某个文件夹中的文件。该文件会被写入 data/WICAgencies2014ytd/Food_Costs.csv：

复制代码

   kaggle datasets download jpmiller/publicassistance -f WICAgencies2014ytd/Food_Costs.csv -p data

下载单个大文件并解压。creditcard.csv 以 creditcard.csv.zip 的形式提供，因此如果不使用 --unzip，落到磁盘上的将是压缩包：
用途： 命令让你能够获取数据集文件以供本地使用。

④ kaggle datasets init 初始化用于创建新数据集的元数据文件（`dataset-metadata.json`）。参见 $元数据文件格式$ (./datasets_metadata.md)。

用法： kaggle datasets init -p <FOLDER_PATH>

选项：

-p, --path <FOLDER_PATH>：将在其中创建 dataset-metadata.json 文件的文件夹路径（默认为当前目录）。

示例： 在 tests/dataset 文件夹中初始化一个数据集元数据文件：

复制代码

kaggle datasets init -p tests/dataset

用途： 此命令会创建一个模板 dataset-metadata.json 文件，在 Kaggle 上创建新数据集之前，你需要先编辑该文件。此文件包含数据集标题、ID（slug）和许可证等信息。

⑤ kaggle datasets create在 Kaggle 上创建新数据集。

用法： kaggle datasets create -p <FOLDER_PATH> [options]

选项：

-p, --path <FOLDER_PATH>：包含数据文件和 dataset-metadata.json 文件的文件夹路径（默认为当前目录）。
-u, --public：将数据集设为公开（默认为私有）。
-q, --quiet：抑制详细输出。
-t, --keep-tabular：不将表格文件转换为 CSV（默认会进行转换）。
-r, --dir-mode <MODE>：如何处理目录：skip（忽略）、zip（压缩上传）、tar（非压缩上传）（默认：skip）。
--ignore-patterns <PATTERNS>：要忽略的文件/目录的模式。可多次指定。

示例： 根据 tests/dataset 中的文件创建一个新的公开数据集，静默执行，不转换表格文件，并跳过子目录。（假设 tests/dataset 中的 dataset-metadata.json 已正确填写标题和 slug）：

复制代码

# Example: Edit dataset-metadata.json first
# sed -i 's/INSERT_TITLE_HERE/My Dataset Title/' tests/dataset/dataset-metadata.json
# sed -i 's/INSERT_SLUG_HERE/my-dataset-slug/' tests/dataset/dataset-metadata.json

kaggle datasets create -p tests/dataset --public -q -t -r skip

**用途：**此命令会上传你的本地数据文件及相关元数据，以在 Kaggle 上创建新数据集。

⑥ kaggle datasets version

为现有数据集创建新版本。

用法： kaggle datasets version -p <FOLDER_PATH> -m <VERSION_NOTES> [options]

选项：

-p, --path <FOLDER_PATH>：包含更新后数据文件和 dataset-metadata.json 的文件夹路径（默认为当前目录）。
-m, --message <VERSION_NOTES>：（必填）描述新版本的消息。
-q, --quiet：抑制详细输出。
-t, --keep-tabular：不将表格文件转换为 CSV。
-r, --dir-mode <MODE>：目录处理模式（skip、zip、tar）。
-d, --delete-old-versions：删除此数据集的旧版本。
--ignore-patterns <PATTERNS>：要忽略的文件/目录的模式。可多次指定。

示例： 使用 tests/dataset 中的文件为数据集创建新版本，版本说明为 "Updated data"，静默执行，保留表格格式，跳过目录，并删除旧版本：kaggle datasets version -m "Updated data" -p tests/dataset -q -t -r skip -d

**用途：**使用此命令可通过新文件或元数据变更来更新现有数据集。

⑦ kaggle datasets metadata

下载数据集的元数据，或根据本地元数据更新现有元数据。

用法： kaggle datasets metadata <DATASET> [options]

参数：

<DATASET>：数据集 URL 后缀（例如 goefft/public-datasets-with-file-types-and-columns）。

选项：

-p, --path <PATH>：下载/更新元数据文件（dataset-metadata.json）的目录。默认为当前工作目录。
--update：使用本地元数据 JSON 文件的内容更新现有数据集版本的元数据（例如从本地"推送"）。

示例： 将数据集 goefft/public-datasets-with-file-types-and-columns 的元数据下载到 tests/dataset 文件夹：kaggle datasets metadata goefft/public-datasets-with-file-types-and-columns -p tests/dataset

用途： 此命令让你能够获取现有数据集的 dataset-metadata.json 文件，可用于检查，或作为创建新版本的模板。

⑧ kaggle datasets status

获取数据集的创建状态。

用法： kaggle datasets status <DATASET>

参数：

<DATASET>：数据集 URL 后缀（例如 goefft/public-datasets-with-file-types-and-columns）。

示例： 获取数据集 goefft/public-datasets-with-file-types-and-columns 的状态：kaggle datasets status goefft/public-datasets-with-file-types-and-columns

**用途：**在创建或更新数据集之后，此命令可帮助你检查过程是否成功，以及是否存在任何问题。

⑨ kaggle datasets delete

从 Kaggle 删除数据集。

用法： kaggle datasets delete <DATASET> [options]

参数：

<DATASET>：数据集 URL 后缀（例如 username/dataset-slug）。

选项：

-y, --yes：自动确认删除，无需提示。

示例： 删除数据集 username/dataset-slug 并自动确认：kaggle datasets delete username/dataset-slug --yes

**用途：**此命令会从 Kaggle 永久移除你的某个数据集。请谨慎使用。

⑩ kaggle datasets topics list

列出数据集的讨论主题。

用法： kaggle datasets topics list <DATASET> [options]

参数：

<DATASET>：格式为 <owner>/<dataset-slug> 的数据集引用（例如 zillow/zecon）。

选项：

--sort-by <SORT_BY>：排序方式。有效选项：hot、top、new、recent、active、relevance。
-s, --search <SEARCH_TERM>：用于筛选主题的搜索查询。
--page-size <PAGE_SIZE>：每页的条目数。
--page-token <PAGE_TOKEN>：用于分页的页面令牌。
-v, --csv：以 CSV 格式打印结果。
-q, --quiet：抑制详细输出。

示例： 列出 zillow/zecon 数据集的最近主题：kaggle datasets topics list zillow/zecon --sort-by recent

**用途：**此命令让你能够浏览特定数据集的讨论主题。

⑪ kaggle datasets topics show

以树形结构显示数据集讨论主题及其所有评论。

用法： kaggle datasets topics show <TOPIC_REF> [options]

参数：

<TOPIC_REF>：主题引用，可以是：
- <dataset>/<topic-id>（例如 zillow/zecon/12345，注意该格式支持包含多个斜杠的数据集 slug）
- <dataset> <topic-id>（两个独立的参数，其中 <topic-id> 作为第二个参数传入）
- <topic-id>（纯数字 ID）

选项：

--page-size <PAGE_SIZE>：每页显示的评论数。
--page-token <PAGE_TOKEN>：用于评论分页的页面令牌。
-v, --csv：以 CSV 格式打印结果。
-q, --quiet：抑制详细输出。

示例： kaggle datasets topics show zillow/zecon/12345

**用途：**此命令会显示完整的讨论主题及其所有评论，并以缩进的树形结构呈现。

Kaggle CLI Datasets上传文件教程（保姆级）

Kaggle CLI

（1）kaggle分批次上传文件环境

一、本地目录组织

二、具体操作命令

1. 安装并配置 Kaggle CLI

2. 第 1 批：创建 Dataset

设置对应的代理：（以下终端设置代理针对当前终端有效，打开新的终端需要重新配置代理）

① anaconda prompt终端

② powershell终端

③ Git Bash / CMD

3. 第 2~N 批：版本更新追加文件（注意这里的version是全量替换，不是增强追加，也就是之前的文件会被替换）

四、在 Kaggle Notebook 中使用

五、注意事项

六 命令使用补充

数据集命令

① kaggle datasets list 列出可用的数据集。

② kaggle datasets files列出特定数据集的文件。

③ kaggle datasets download下载数据集文件。

④ kaggle datasets init 初始化用于创建新数据集的元数据文件（dataset-metadata.json）。参见元数据文件格式(./datasets_metadata.md)。

⑤ kaggle datasets create在 Kaggle 上创建新数据集。

⑥ kaggle datasets version

⑦ kaggle datasets metadata

⑧ kaggle datasets status

⑨ kaggle datasets delete

⑩ kaggle datasets topics list

⑪ kaggle datasets topics show

六命令使用补充

④ kaggle datasets init 初始化用于创建新数据集的元数据文件（`dataset-metadata.json`）。参见 $元数据文件格式$ (./datasets_metadata.md)。