---
title: StructCoT
canonical_url: "https://www.modelscope.cn/datasets/wpj2003/StructCoT"
md_url: "https://www.modelscope.cn/datasets/wpj2003/StructCoT.md"
repository: wpj2003/StructCoT
last_updated: 2026-09-15
license: "Apache License 2.0"
storage_size: "418 GB"
downloads: 3702
stars: 0
---

# StructCoT

> StructCoT - wpj2003 在 ModelScope 开源的数据集。图片体量很大(约 440 万张、解包后数百 GB),因此不随 JSON 直接铺开,而是分片打包成 disttrain/imagespart.tar。训练图片解包后在根目录得到 images/；测试 JSON 与测试图片包单独使用 disttest/StructCoTtestimages.tar,解包后得到 imagestest/。

wpj2003/StructCoT 是 ModelScope 魔搭社区上的数据集，存储大小 418 GB，采用 Apache License 2.0 许可。

- **Repository**: wpj2003/StructCoT
- **License**: Apache License 2.0
- **Storage size**: 418 GB
- **Downloads**: 3702
- **Stars**: 0
- **Last updated**: 2026-09-15

Source: https://www.modelscope.cn/datasets/wpj2003/StructCoT

---

## 仓库结构

```
.
├── README.md
├── train/
│   └── train.jsonl              # 合并训练集(StructCoT + ZebraCot),含 is_zebra_cot 标记
├── test/
│   ├── structcot_test.json      # StructCoT 测试集(5,600 条,每个大类 800)
│   └── zebracot_test.json       # ZebraCot 测试集(4,000 条)
├── dist_train/
│   ├── images_part_001.tar … images_part_082.tar   # 训练图片,分片打包
│   └── _pack/                                      # 分片清单与打包索引
└── dist_test/
    ├── StructCoT_test_images.tar                   # 测试图片(42,926 张)
    └── _pack/                                      # 测试图片清单与打包报告
```

> 图片体量很大(约 440 万张、解包后数百 GB),因此**不随 JSON 直接铺开**,而是分片打包成
> `dist_train/images_part_*.tar`。训练图片解包后在根目录得到 `images/`；测试 JSON 与测试图片包单独使用
> `dist_test/StructCoT_test_images.tar`,解包后得到 `images_test/`。

两个图片归档的内部路径已经分别固定为 `images/` 和 `images_test/`。因此必须在数据集根目录
(即本 README 所在目录)解包,不要在 `dist_train/` 或 `dist_test/` 内解包。

---

## 下载与解包

图片被切成 **82 个独立的 tar 分片**(大多数每片约 5.4 GB,最后一片较小,**不压缩**——图片本身已是
jpg/png,再压缩几乎不省体积)。
每片都可**独立解开**,无需先合并;解包后统一在数据集根目录生成 `images/<大类>/<小类>/…`。

```bash
# 假设你已经把整个数据集仓库下载到本地,并 cd 到仓库根目录(README.md 所在目录)

# 逐片解包(每个 tar 内部成员都是 images/...,会就地还原到根目录下的 images/)
for f in dist_train/images_part_*.tar; do
    tar -xf "$f"
done

# 解包完成后,根目录下会出现:
#   images/<大类>/<小类>/<图片文件>
# 与 train/train.jsonl 中的相对路径(以 images/ 开头)对应
```

- **必须在数据集根目录执行解包**(不要 `cd dist_train`),这样 `images/` 才会落在根目录、和 JSON 路径对齐。
- 每片相互独立:可以只解压你需要的某几片,坏了/没下全某一片只需重下重解那一片,不影响其余。
- 单片快速校验成员路径:`tar -tf dist_train/images_part_001.tar | head`(应看到 `images/<大类>/<小类>/…`)。

> 用 `modelscope` SDK / CLI 下载本数据集的方式见 ModelScope 页面的「下载」说明;下载到本地后,解包步骤同上。

### 独立测试图片包

```bash
# 在数据集根目录执行
tar -xf dist_test/StructCoT_test_images.tar
# 解包后根目录出现 images_test/<大类>/<小类>/<图片文件>
# 与 test/*.json 中的图片路径(均以 images_test/ 开头)一一对应
```

---

## 图片路径约定

训练 JSON 里的图片路径以 `images/` 开头；独立测试 JSON 里的图片路径以 `images_test/` 开头。
两者都是相对路径，解析时拼到数据集根目录即可:

```python
import os, json
DATASET_ROOT = "/path/to/这个目录"          # 即本 README 所在、且解包出 images/ 与 images_test/ 的目录
rec = json.loads(open(f"{DATASET_ROOT}/train/train.jsonl").readline())
img_abspath = os.path.join(DATASET_ROOT, rec["input_images"][0]["path"])
assert os.path.exists(img_abspath)
```

---

## 字段说明

### 训练集 `train/train.jsonl`(每行一个 JSON 对象)

- `id`:样本唯一 id。
- `messages`:`[{role:"user", content}, {role:"assistant", content}]`。`content` 中用占位符
  `<input_image_N>` / `<output_image_N>` 按序对应输入/输出图片;助手推理文本里还会出现
  `<|vision_start|><|vision_end|>` 视觉占位。**占位符不含文件路径。**
- `input_images` / `output_images`:`[{id, path}]`,`path` 为相对图片路径(以 `images/` 开头)。
- **`is_zebra_cot`**(bool):该样本是否来自 ZebraCot 子集。
- **`origin`**(str):`"StructCoT"` 或 `"ZebraCot"`(与 `is_zebra_cot` 冗余,便于阅读)。
- `num_tokens`(list[int]):每张图片的视觉 token 预算(首图用基础预算,其余由 TSIM Router 按
  时序相似度分配);训练 / 推理在 `--use_json_num_tokens` 下读取。
- `token_length`(int):整条样本的近似 token 长度,供 sequence-packing 训练分桶用。
- `subset` / `subset_info`(`{category, source_subset}`)、`task_type` 原样保留。
- 注:`dataset` 字段对两个子集均为 `"StructCoT"`,**不可用于区分来源**,请用 `is_zebra_cot`/`origin`。

### 测试集(两文件 schema 不同)

`test/structcot_test.json`(JSON 数组):
- `input_image` / `output_image`:相对图片路径列表(以 `images_test/` 开头,可能为空)。
- `input_prompt`、`output_text`(含 `<|vision_start|><|vision_end|>` 占位)。
- `major_category`(7 个大类之一)、`label`(细类,形如 `"<大类> —— <子类>"`)。
- `num_tokens`(每图视觉 token 数)、`token_status`、`split`、`dataset="StructCoT"`。

`test/zebracot_test.json`(JSON 数组):
- `input_image` / `output_image`:相对图片路径列表(已按统一 7 大类体系归档在 `images_test/<大类>/<小类>/…`)。
- `input_prompt`、`output_text`(含 `THOUGHT n:` 行与 `<|vision_start|><|vision_end|>` 占位)。
- `config`(18 个细类,**保留原始 4 大类命名**,如 `"Visual Logic & Strategic Games - Tetris"`);
  `validity`、`num_tokens`、`token_status`、`dataset="ZebraCot"`。
- 注:`config` 是原始标签,仅作记录;图片实际归档大类/小类已映射到与训练集一致的 7 大类体系。

---

## 7 大类体系

训练集与独立测试集的图片分别归档在以下 7 个大类下：训练使用
`images/<大类>/<小类>/…`，测试使用 `images_test/<大类>/<小类>/…`:

`Image Restoration and Jigsaw Reasoning`、`Logical and Abstract Reasoning`、
`Mathematical and Algorithmic Reasoning`、`Natural Science and Domain-Specific Reasoning`、
`Spatial Perception and Embodied Planning`、`Strategic Game and Planning`、`Visual Search`。

具体小类以各 JSON 的标签字段和图片路径为准。

> ZebraCot 测试集的 `config` 字段保留其原始命名(4 大类 / 18 细类),仅作记录;其图片的实际归档大类
> 已映射到上面的 7 大类体系,与训练集一致。

---

## 解压检查

```bash
cd /path/to/StructCoT
tar -xf dist_test/StructCoT_test_images.tar
for f in dist_train/images_part_*.tar; do
    tar -xf "$f"
done

# 最终应存在:
#   images/<大类>/<小类>/...
#   images_test/<大类>/<小类>/...
```