roboflow-data-management

面向 Agent： 此技能由 roboflow/computer-vision-skills 编写。如果客户端已将其作为技能加载（例如通过 Roboflow 插件），请使用该副本。roboflow://skills/<name>/... MCP 资源为尚未加载这些技能的客户端提供相同的技能。

Roboflow 上的数据管理

项目类型

类型	标注格式	使用场景
目标检测	边界框（多边形/掩码会自动转换）	用边界框定位对象
实例分割	多边形、掩码	对象级像素边界
语义分割	多边形、掩码	像素级类别区域
关键点检测	关键点（骨架）	姿态/骨架估计
单标签分类	图像级标签（无需绘制标注）	每张图像对应一个类别
多标签分类	图像级标签	每张图像对应多个类别

项目类型在创建时设定，之后无法更改。

上传数据

方式

方式	适用场景	格式
Web UI 拖放	< 1,000 张图像	JPG、PNG、WEBP、AVIF、BMP、MOV、MP4、PDF + 40 多种标注格式
CLI（roboflow import）	> 1,000 张图像（仅图像）	相同的图像格式，不支持视频
MCP zip 上传（image_upload）	Agent 上传本地文件，每个 zip 最大 2 GB / 10,000 个文件	图像及可选的标注文件（见下文）
云存储存储桶镜像	S3 / GCS 中已有的大量或持续增长的数据	参见 roboflow://skills/roboflow-cloud-storage/SKILL
Dataset Upload Workflow Block	从生产环境的 Workflows 收集数据	程序化
Universe 派生	从公开数据集开始	任意 Universe 数据集

限制： 每张图像最大 20 MB，最大 16,400 x 10,900 像素。重复图像会自动跳过。

视频上传

视频会按可配置的速率拆分为帧（每 60 秒 1 帧至 60 fps）。支持的格式取决于浏览器（MP4 H.264 兼容性最佳）。

CLI 上传

pip install roboflow
roboflow import -w <workspace> -p <project-id> /path/to/dataset

MCP Zip 上传

image_upload 会返回一个签名 URL。客户端将本地文件打包为 zip，将 zip PUT 到该 URL，然后轮询 image_upload_status，直至状态为 completed 或 failed。

• 会导入标注。 zip 中可以将标注文件与图像放在一起。系统会像 Web 上传器一样解析这些文件：COCO JSON（_annotations.coco.json）、YOLO TXT（含 data.yaml 或 classes.txt）、Pascal VOC XML、CreateML JSON、CSV 等。系统会按文件名将标注与图像匹配。在分类项目中，图像的父文件夹名称就是其类别。
• 文件夹会设置数据集划分。 图像路径中的任意位置只要包含 train/、valid/ 或 test/ 文件夹（也包括 training/、validation/、val/、testing/），就会设置相应的数据集划分。其他图像使用 split 参数。
• 已标注图像会直接进入 Dataset。 无需接受标注任务，除非工作区启用了标注审核（此时图像会进入审核任务等待处理）。未标注图像会进入一个批次（batch_name，默认为 "Uploaded via API"）；使用 annotations_save 并设置 add_to_dataset=true 为其添加标签。
• 重复图像仍会应用其标注。 项目中已有的图像不会再次存储，但 zip 中的标注仍会保存。如果图像已有标注，则保留原标注，并在 annotationErrors 中将图像列为 "Image was already annotated"；传入 annotation_overwrite=true 可替换原标注。分类标签始终会被替换。
• 失败的分块可以安全重试。 zip 会分块处理。如果状态为 failed，且 uploadErrors 中有类似 chunk-0 的条目，则该分块中的图像可能已存储，但其标注尚未保存。再次上传相同的 zip：已存储的图像会作为重复图像返回，其缺失的标注会被保存。对于首次上传成功的图像，出现 "Image was already annotated" 属正常情况。

标签

标签是图像上的自由格式标记，用于整理和筛选。

操作	方法
上传时添加	在上传对话框中使用标签选择器，或通过 API 添加
添加到现有图像	选择图像 -> “已选择图像” -> “应用标签”
批量重命名/删除	项目设置 -> 标签 -> “修改标签”
按标签筛选	使用 tag:<name> 搜索，或使用 Assign 页面筛选器
在版本中使用	使用“按标签筛选”预处理步骤（要求/排除/允许）

数据集搜索（RoboQL）

通过 Images 页面的搜索栏搜索图像，或使用 MCP images_workspace_search 工具（添加 project:<slug> 以将搜索限制在一个项目内）。可使用布尔逻辑组合筛选条件。

MCP images_search 工具不会解析 RoboQL。它的查询是语义文本，可对结果排序，但不会筛选结果，因此其中的 split:valid 不会产生任何效果。它只能通过自身参数进行筛选（标签、类别、Dataset、批次、标注任务）。要使用数据集划分和其他 RoboQL 筛选条件，请使用 images_workspace_search。

筛选条件

筛选条件	示例	说明
(自由文本)	person on sidewalk	语义搜索（基于 CLIP）
like-image:<ID>	like-image:abc123	查找视觉上相似的图像
filename:	filename:*factory*	文件名匹配（使用 * 进行部分匹配）
tag:	tag:factory	按标签筛选
split:	split:train	按数据集划分筛选
job:	job:<JOB_ID>	按标注任务筛选
class:	class:helmet	包含指定类别的标注
metadata:	metadata:key=value	按用户元数据筛选
project:	project:my-project	按项目筛选（工作区搜索）
dataset:	dataset:my-project	项目 Dataset 中的图像；project:my-project NOT dataset:my-project 可查找尚未加入其中的图像
sort:	sort:updated	对结果排序
min-width: / max-width:	min-width:1000	图像尺寸筛选条件
min-height: / max-height:	max-height:800	图像尺寸筛选条件
min-annotations: / max-annotations:	max-annotations:1	标注数量筛选条件

布尔逻辑

• AND、OR、NOT、括号：class:helmet AND NOT (tag:v1 OR tag:v2)
• 使用 - 反转筛选条件：-class:vest
• 数值筛选条件的比较运算符：>、<、>=、<=、=（例如，class:helmet>=3）

数据集划分（Train / Valid / Test）

图像会被分配到 train、valid 或 test 数据集划分。在生成版本时（版本创建的第 2 步）会重新平衡数据集划分。增强仅应用于 train 数据集划分。

数据集版本

版本是数据集在某个时间点的冻结快照。创建版本后对项目所做的更改不会影响现有版本。

版本创建流程

1. 源选择 — 来自数据集划分的图像
2. Train/Test 划分 — 重新平衡百分比
3. 预处理 — 应用于所有数据集划分（train + valid + test）
4. 增强 — 仅应用于 train 数据集划分
5. 生成 — 创建不可变版本

预处理选项

步骤	效果
自动定向	移除 EXIF，规范化方向
调整大小	拉伸至 / 适配于 / 适配（黑色边缘）/ 适配（白色边缘）
灰度化	将 RGB 转换为单通道
自动调整对比度	对比度拉伸 / 直方图均衡化 / 自适应（CLAHE）
隔离对象	将每个 bbox 裁剪为单独的图像（将 OD 转换为分类）
固定裁剪	将所有图像裁剪至固定区域
切片	将图像切分为 NxN 网格（默认为 2x2，有助于检测小型对象）
动态裁剪	围绕特定类别裁剪图像
修改类别	仅对此版本重新映射/省略类别
筛除空标注	控制未标注图像的百分比
按标签筛选	按标签要求/排除/允许图像
随机采样	按数据集划分采样一定百分比的图像

增强选项

仅应用于训练图像。可配置最大版本大小（例如，3x = 原图 + 2 个增强副本）。

增强方式	图像级	BBox 级	级别
翻转	是	是	基础
90 度旋转	是	是	基础
裁剪	是	是	基础
旋转	是	是	基础
错切	是	是	基础
灰度	是	否	基础
色调	是	否	基础
饱和度	是	否	基础
亮度	是	是	基础
曝光	是	是	基础
模糊	是	是	基础
噪声	是	是	基础
相机增益	是	是	基础
运动模糊	是	是	基础
遮挡	是	否	增强版（付费）
Mosaic	是	否	增强版（付费）

数据集分析

可在项目侧边栏 -> “Analytics”中查看。包括：

• 图像数量、标注数量、平均图像大小、中位数宽高比
• 缺失和空标注数量
• 训练集／验证集／测试集的类别分布
• 图像尺寸分析（大小和宽高比分布）
• 标注热力图（单击并拖动以按区域筛选图像）
• 对象数量直方图（单击柱状图查看匹配的图像）

类别

在 Project Settings -> Classes 中管理。

操作	说明
重命名	在 Override 列中输入新名称
合并	将多个类别 Override 为相同名称
删除	勾选 Delete 复选框
锁定	“Lock Annotation Classes”可阻止创建新类别

警告： 在项目级别更改类别会影响所有图像（不可撤销）。如需进行非破坏性更改，请使用版本级别的“Modify Classes”预处理。

标注组

标注组 = 包含项目中所有类别的类别集合。共享相同标注组的项目会共享其类别列表和标注。

• 创建项目时启用：“Share image annotations with other projects”
• 共享标注：在一个项目中编辑会影响所有关联项目
• 查看链环图标以识别共享的图像／项目
• 在多个项目间共享的图像在用量中只计一次

重用组名会共享标注，即使项目位于 Trash 中也一样。 该组只是创建时指定的 annotation 名称。使用另一个项目已用名称创建的新项目（包括已移至 Trash 的项目）会静默加入该组：上传到该项目且已存在于工作区中的图像会连同其标注一起导入；如果上传时附带标注，则会失败并显示“Image was already annotated”。除非用户希望共享标注，否则请在调用 projects_create 之前检查 projects_list 和 trash_list 中的 annotation 值，并选择其他项目未使用的名称。

项目文件夹

文件夹用于整理项目。SSO 工作区可以将文件夹访问权限限制为特定团队成员。

操作	方法
创建	在工作区视图中选择“+ New Folder”
移动项目	项目菜单 -> “Move Project”
删除文件夹	文件夹菜单 -> “Delete”（项目会移至工作区根目录，而不会被删除）

导出格式

版本可导出为 .zip 下载文件或 curl 命令。支持 40 多种格式，包括 COCO、YOLO、Pascal VOC、TFRecord 等。完整列表请访问 roboflow.com/formats。

通过 Python SDK 导出：

project.version(1).download("yolov8")

项目类型和许可证

不要猜测项目的类型或许可证。在调用 projects_create 之前，请向用户确认两者。

可用的 MCP 工具

工具	用途
projects_create	创建新项目（指定类型和未使用的标注组，除非计划共享）
projects_list / projects_get	列出项目或获取项目详情
images_search	在单个项目中进行语义搜索，支持标签、类别、数据集、批次和任务筛选（不支持 RoboQL）
images_workspace_search	使用 RoboQL 在整个工作区中搜索，例如 project:my-project split:valid
image_upload / image_upload_status	准备包含图像和可选标注的 zip 上传，并查询其状态
versions_generate	通过预处理／增强生成数据集版本
versions_get	查看版本
versions_export	以指定格式导出版本

相关页面

• roboflow://skills/roboflow-data-management/labeling — 标注工具、AI 标注、Label Assist、Smart Polygon、Auto Label、标注任务
• roboflow://skills/roboflow-cloud-storage/SKILL — 将 S3/GCS 存储桶镜像到工作区（凭证、数据源、glob 规则、定时同步）