跳到主要内容
版本:0.6.11

数据集构建

Starwhale 数据集构建方式非常灵活,可以从一些图片/音频/视频/csv/json/jsonl文件构建,也可以写一些Python脚本构建,还可以从Huggingface Hub 导入数据集。

从数据文件直接构建

图片

支持递归遍历目录中的图片文件,构建Starwhale 数据集,不需要写任何代码:

  • 支持的图片文件格式: png/jpg/jpeg/webp/svg/apng
  • 图片会转成 Starwhale.Image 类型,并可以在 Starwhale Server Web页面中查看。
  • 支持命令行 swcli dataset build --image 和 Python SDK starwhale.Dataset.from_folder 两种方式。
  • label机制:当 SDK 设置 auto_label=True 或 命令行设置 --auto-label 时,会将父目录的名字作为 label
  • metadata机制:可以通过在根目录设置 metadata.csvmetadata.jsonl 文件来扩展数据集的列。
  • caption机制:当在同目录下发现 {image-name}.txt 文件时,文件中的内容会被自动导入,填充到 caption 列中。

假设在 folder 目录中有下面四个文件:

folder/dog/1.png
folder/cat/2.png
folder/dog/3.png
folder/cat/4.png

命令方式构建方法:

❯ swcli dataset build --image folder --name image-folder
🚧 start to build dataset bundle...
👷 uri local/project/self/dataset/image-folder/version/latest
🌊 creating dataset local/project/self/dataset/image-folder/version/uw6mdisnf7alg4t4fs2myfug4ie4636w3x4jqcu2...
🦋 update 4 records into dataset
🌺 congratulation! you can run swcli dataset info image-folder/version/uw6mdisnf7al
❯ swcli dataset head image-folder -n 2
row ───────────────────────────────────────
🌳 id: cat/2.png
🌀 features:
🔅 file_name : cat/2.png
🔅 label : cat
🔅 file : ArtifactType.Image, display:2.png, mime_type:MIMEType.PNG, shape:[None, None, 3], encoding:
row ───────────────────────────────────────
🌳 id: cat/4.png
🌀 features:
🔅 file_name : cat/4.png
🔅 label : cat
🔅 file : ArtifactType.Image, display:4.png, mime_type:MIMEType.PNG, shape:[None, None, 3], encoding:

Python SDK方式构建:

from starwhale import Dataset
ds = Dataset.from_folder("folder", kind="image")
print(ds)
print(ds.fetch_one().features)
🌊 creating dataset local/project/self/dataset/folder/version/nyc2ay4gnyayv4zqalovdgakl3k2esvrne42cjna...
🦋 update 4 records into dataset
Dataset: folder, stash version: d22hdiwyakdfh5xitcpn2s32gblfbhrerzczkb63, loading version: nyc2ay4gnyayv4zqalovdgakl3k2esvrne42cjna
{'file_name': 'cat/2.png', 'label': 'cat', 'file': ArtifactType.Image, display:2.png, mime_type:MIMEType.PNG, shape:[None, None, 3], encoding: }

视频

支持递归遍历目录中的视频文件,构建Starwhale 数据集,不需要写任何代码:

  • 支持的视频文件格式:mp4/webm/avi
  • 视频会被转成 Starwhale.Video 类型,并可以在 Starwhale Server Web页面中查看。
  • 支持命令行 swcli dataset build --video 和 Python SDK starwhale.Dataset.from_folder 两种方式。
  • label, caption 和 metadata 机制与图片方式相同。

音频

支持递归遍历目录中的音频文件,构建Starwhale 数据集,不需要写任何代码:

  • 支持的音频文件格式:mp3/wav
  • 音频会被转成 Starwhale.Audio 类型,并可以在 Starwhale Server Web页面中查看。
  • 支持命令行 swcli dataset build --video 和 Python SDK starwhale.Dataset.from_folder 两种方式。
  • label, caption 和 metadata 机制与图片方式相同。

csv 文件

支持命令行或Python SDK方式将本地或远端的csv文件直接转化成 Starwhale 数据集:

  • 支持一个或多个本地csv文件
  • 支持对本地目录递归寻找csv文件
  • 支持一个或多个以http url方式指定的远端csv文件

命令行方式构建:

❯ swcli dataset build --name product-desc-modelscope --csv https://modelscope.cn/api/v1/datasets/lcl193798/product_description_generation/repo\?Revision\=master\&FilePath\=test.csv --encoding=utf-8-sig
🚧 start to build dataset bundle...
👷 uri local/project/self/dataset/product-desc-modelscope/version/latest
🌊 creating dataset local/project/self/dataset/product-desc-modelscope/version/wzaz4ccodpyj4jelgupljreyida2bleg5xp7viwe...
🦋 update 3848 records into dataset
🌺 congratulation! dataset build from csv files(('https://modelscope.cn/api/v1/datasets/lcl193798/product_description_generation/repo?Revision=master&FilePath=test.csv',)) has been built. You can run swcli dataset info product-desc-modelscope/version/wzaz4ccodpyj

Python SDK方式构建:

from starwhale import Dataset
ds = Dataset.from_csv(path="http://example.com/data.csv", name="my-csv-dataset")

json/jsonl 文件

支持命令行或Python SDK方式将本地或远端的json/jsonl文件直接转化成 Starwhale 数据集:

  • 支持一个或多个本地json/jsonl文件
  • 支持对本地目录递归寻找json/jsonl文件
  • 支持一个或多个以http url方式指定的远端json/jsonl文件

对于json文件:

  • 默认认为json解析后的对象是list,list中的每个对象是dict,会映射为Starwhale 数据集中的一行。
  • 可以通过 --field-selectorfield_selector 参数定位具体的某个list。

比如json文件如下:

{
"p1": {
"p2":{
"p3": [
{"a": 1, "b": 2},
{"a": 10, "b": 20},
]
}
}
}

那么可以设置 --field-selector=p1.p2.p3 ,准确添加两行数据到数据集中。

命令方式构建:

❯ swcli dataset build --json https://modelscope.cn/api/v1/datasets/damo/100PoisonMpts/repo\?Revision\=master\&FilePath\=train.jsonl
🚧 start to build dataset bundle...
👷 uri local/project/self/dataset/json-b0o2zsvg/version/latest
🌊 creating dataset local/project/self/dataset/json-b0o2zsvg/version/q3uoziwqligxdggncqywpund75jz55h3bne6a5la...
🦋 update 906 records into dataset
🌺 congratulation! dataset build from ('https://modelscope.cn/api/v1/datasets/damo/100PoisonMpts/repo?Revision=master&FilePath=train.jsonl',) has been built. You can run swcli dataset info json-b0o2zsvg/version/q3uoziwqligx

Python SDK方式构建:

from starwhale import Dataset
myds = Dataset.from_json(
name="translation",
text='{"content":{"child_content":[{"en":"hello","zh-cn":"你好"},{"en":"how are you","zh-cn":"最近怎么样"}]}}',
field_selector="content.child_content"
)
print(myds[0].features["zh-cn"])
🌊 creating dataset local/project/self/dataset/translation/version/kblfn5zh4cpoqxqbhgdfbvonulr2zefp6lojq44y...
🦋 update 2 records into dataset
你好

从Huggingface Datasets Hub中构建

Huggingface Hub 上有大量的数据集,可以通过一行代码或一条命令就能转化为 Starwhale 数据集。

提示

Huggingface Datasets 转化需要依赖 datasets 库。

命令行方式:

swcli dataset build -hf lambdalabs/pokemon-blip-captions --name pokemon

Python SDK方式:

from starwhale import Dataset

# You only specify starwhale dataset expected name and huggingface repo name
# example: https://huggingface.co/datasets/lambdalabs/pokemon-blip-captions
ds = Dataset.from_huggingface("pokemon", "lambdalabs/pokemon-blip-captions")
print(ds)
print(len(ds))
print(repr(ds.fetch_one()))

使用 Starwhale SDK 编写 Python Script 方式构建

Starwhale Dataset SDK 提供类似Python dict 的方式添加或更新数据,实现本地或远端数据集的创建和更新。

Starwhale 对每行数据定义了两种属性:keyfeatures

- `key` 类型为 int 或 str,同一个数据集中只有有一种类型的`key`。`key` 表示能够唯一索引到该行数据。
- `features` 类型为 dict。Starwhale Dataset 采用无Schema设计,所以每一行的 `features` 结构都可以不同。
- `features` 中的数据支持int, float, str等Python 常量类型,也支持Image, Video, Audio, Text, Binary 等Starwhale 类型,还支持 list, tuple, dict等Python 复合类型。

数据集初始化

要创建、更新或加载数据集,需要先获得一个 Starwhale.Dataset 对象,一般可以采用如下方式获取:

from starwhale import dataset

# 创建一个本地的数据集,名称为 new-test,若已经存在这个数据集,则抛出异常
local_ds = dataset("new-test", create="empty")
print(local_ds)
print(len(local_ds))

# 若mnist64数据集不存在就创建一个,若存在就加载这个数据集
remote_ds = dataset("https://cloud.starwhale.cn/project/starwhale:helloworld/dataset/mnist64", create="auto")
print(remote_ds)
print(len(remote_ds))

# 加载一个已经存在的数据集,名称为mnist64,如该数据集不存在则报错
existed_ds = dataset("mnist64", create="forbid")
print(existed_ds)
print(len(existed_ds))
Dataset: new-test, stash version: y4touw3btifhkd4f2gg4x3qvydgnfmvoztqqm5cf, loading version: y4touw3btifhkd4f2gg4x3qvydgnfmvoztqqm5cf
0

Dataset: mnist64, stash version: 4z5wpbpozsxlelma3j6soeatekufymnyxdeihoqo, loading version: vs3gnaauakidjcc5effevaoh63vivu7dzodo5cmc
500

Dataset: mnist64, stash version: 3ahtfbizw63myxcz34ebd72lhgc25dualcmtznts, loading version: lwhvvixpimlsghfs2xqmtgrwti4yn2z5nevz7hth
500

数据集元素添加和更新

Dataset 添加完数据后,如调用 commit 方式会产生一个新的版本,之后就可以用这个版本进行数据集的记载。

append 方式

Dataset 提供 append 函数,调用时自动增加features到数据集新的一行。

from starwhale import dataset
ds = dataset("new-test", create="empty")

# key 采用自增ID方式,本例子中 key 为 0
ds.append({"a": 0, "b": 0})

# key 也可以主动声明,但需要保持与其他行的key类型一致
# 以 list 或 tuple 方式添加的数据,第0个就是该行的`key`, 第1个是`features`
ds.append((1, {"a":1, "b":1}))

ds.commit()

__setitem__ 方式

Dataset 提供 __setitem__ 函数,提供类似 dict的索引更新值的方式添加数据。

ds[2] = {"a":2, "b":2}
ds.commit()

使用 swcli dataset build + Python Handler 方式构建

支持 swcli 命令行读取某个Python文件中的某个函数作为输入,构建数据集。该函数的返回值需要可迭代。

dataset.py 脚本内容如下:

def iter_item():
for i in range(100):
# 只返回 features。key为int类型的自增数字。
yield {"a": i, "b": i}

def iter_item_with_key():
for i in range(100):
# 返回 key + features结构。
yield i, {"a": i, "b": i}

构建数据集时,需要通过swcli命令行触发:

swcli dataset build --handler dataset:iter_item --name test1
swcli dataset build --handler dataset:iter_item_with_key --name test2