Label Studio 导入 Roboflow COCO 数据集（S3 存储）最佳实践

本文档总结了一套已验证有效的流程，用于将 Roboflow Universe 导出的 COCO 格式数据集导入 Label Studio，并利用 S3 存储提供图片访问。

✅ 适用场景

• 数据集来源：Roboflow Universe 导出的 COCO JSON 格式（含 _annotations.coco.json 和图片）

• 存储方式：Amazon S3（或其他兼容 S3 协议的对象存储）

• Label Studio 版本：社区版（已验证，支持 label-studio-converter 和 S3 源存储）

📋 前提条件

1. 已安装 label-studio-sdk（包含 label-studio-converter 工具）：

   1	pip install label-studio-sdk

   或直接安装转换器：

   1	pip install label-studio-converter

2. 具备 AWS S3 访问权限：

   • 有读写（或至少读取）权限的 Access Key ID 和 Secret Access Key
   • 知道桶所在区域（Region）

3. Label Studio 实例已正确配置 S3 存储（参考下文步骤四）

🚀 完整操作步骤

步骤一：从 Roboflow 下载数据集

1. 在 Roboflow Universe 数据集页面，点击 Download Dataset。

2. 在导出格式中选择 COCO JSON（COCO 选项），下载 .zip 压缩包。

3. 解压后，你会得到：

   • 图片文件夹（如 train/、valid/、test/）
   • 标注文件 _annotations.coco.json

步骤二：上传数据到 S3

推荐将整个解压后的文件夹内容上传到 S3 桶的某个目录下，保持相对结构不变。例如，假设你的桶名为 google，目标路径为：

1
2
3
4
5

s3://google/0801/potato-detect.v1i.coco/
├── train/          # 图片文件
├── valid/          # （若有）
├── test/           # （若有）
└── _annotations.coco.json

注意：_annotations.coco.json 与 train/ 等目录同级，即都在 0801/potato-detect.v1i.coco/ 下。

步骤三：转换 COCO JSON 为 Label Studio 任务格式

使用 label-studio-converter 将标准 COCO 格式转换为 Label Studio 可直接导入的 JSON 文件。

⚠️ 关键：--image-root-url 参数决定了任务中 data.image 的值。我们推荐使用绝对 S3 URL（已验证有效），这样 Label Studio 可以直接通过这些 URL 访问图片，无需依赖存储配置中的 Prefix 和预签名 URL。

1
2
3
4

label-studio-converter import coco \
  -i _annotations.coco.json \
  -o label_studio_tasks.json \
  --image-root-url s3://google/0801/potato-detect.v1i.coco/train/

参数说明：

• -i：输入的 COCO JSON 文件路径

• -o：输出的 Label Studio 任务 JSON 文件名

• --image-root-url：图片的根 URL，这里使用 S3 绝对路径。末尾必须包含 /，因为 COCO 中的 file_name 只有文件名，拼接后形成完整对象键。

执行成功后会生成：

• label_studio_tasks.json：任务列表

• label_studio_tasks.label_config.xml：对应的标签配置（可选）

步骤四：在 Label Studio 中配置 S3 源存储

尽管我们使用了绝对 S3 URL，仍需在 Label Studio 项目中添加 S3 源存储，以便系统能够访问这些文件（例如生成预签名 URL 或通过代理）。配置如下：

1. 进入项目 → Settings → Cloud Storage → Add Source Storage

2. 选择 Amazon S3，填写：

   • Bucket Name：google
   • Region Name：你的桶所在区域（如 us-east-1）
   • Access Key ID / Secret Access Key：有读取权限的密钥
   • Bucket Prefix：留空（因为 data.image 已包含完整路径）
   • Import Method：Tasks（我们手动导入 JSON）
   • Use pre-signed URLs：不建议勾选（因为我们使用绝对 URL，不再需要额外签名；若勾选可能干扰）

3. 点击 Add Storage 保存。

若使用相对路径（如 --image-root-url train/），则需：

• Bucket Prefix 设为 0801/potato-detect.v1i.coco（不含 /train）
• 勾选 Use pre-signed URLs
• 并配置 CORS 和时间同步（见附录）

步骤五：导入转换后的 JSON 文件

1. 在 Label Studio 项目页面，进入 Data Manager。

2. 点击 Import 按钮。

3. 选择本地生成的 label_studio_tasks.json 文件上传。

4. 等待导入完成，你会看到所有任务显示在列表中。

步骤六：验证

• 点击任意任务，图片应正常加载（直接从 S3 读取）。

• 如果有预标注框（来自 Roboflow 的原始标注），它们会以 预标注（Predictions） 形式显示在图片上，方便你直接审查或修正。

🧩 故障排除指南

📦 一键式脚本（供后续复用）

将以下命令保存为 convert.sh，替换 _annotations.coco.json 路径和 S3 根 URL 即可：

1
2
3
4
5

#!/bin/bash
label-studio-converter import coco \
  -i /path/to/your/_annotations.coco.json \
  -o label_studio_tasks.json \
  --image-root-url s3://YOUR_BUCKET/YOUR_PATH/train/

然后：

1. 在 Label Studio 中配置相同的 S3 存储（Bucket Prefix 留空）。

2. 导入生成的 label_studio_tasks.json。

📚 参考链接

• Label Studio Converter 官方文档

• Label Studio 云存储配置指南

• Roboflow 导出格式说明

🎉 总结

通过绝对 S3 URL 方式，我们绕过了复杂的预签名 URL 和时间同步问题，使导入过程稳定且可重复。记住关键点：

• 转换时 --image-root-url 必须写完整的 S3 对象前缀（以 / 结尾）

• Label Studio 的 S3 存储中 Bucket Prefix 留空，且不启用预签名 URL

• 确保 S3 桶的 CORS 策略允许你的 Label Studio 域名访问（详见附录）

按照此文档操作，即可快速将 Roboflow 数据集无缝导入 Label Studio 进行标注或复审。

附录：S3 CORS 策略示例（允许 Label Studio 域名）

1
2
3
4
5
6
7
8

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET", "HEAD"],
        "AllowedOrigins": ["https://label.imlogic.cn"],
        "ExposeHeaders": []
    }
]

如有其他问题，欢迎查阅官方文档或提交 Issue。Happy Labeling! 🚀