데이터세트 업로드

Python SDK를 사용해 구조화된 이미지 및 주석 데이터세트를 Roboflow 프로젝트에 업로드하세요.

이 페이지에서는 Python SDK, REST zip 엔드포인트 또는 CLI를 사용하여 기존 라벨링 데이터셋(이미지와 해당 주석)을 대량 가져오는 방법을 다룹니다. API를 통해 개별 이미지를 업로드하고 관리하는 방법은 다음을 참조하세요 이미지 관리.

Python SDK

Workspace.upload_dataset() 구조화된 데이터셋(이미지 + 일치하는 주석)을 Roboflow 프로젝트에 업로드합니다. 프로젝트가 없으면 생성되며, 있으면 새 이미지가 기존 프로젝트에 추가됩니다.

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()

workspace.upload_dataset(
    "./dataset/",                  # 구조화된 데이터셋 디렉터리 경로
    "my-detector",                 # 프로젝트 ID(없으면 생성됨)
    num_workers=10,
    project_license="MIT",
    project_type="object-detection",
    batch_name=None,
    num_retries=0,
    is_prediction=False,           # 검토를 기다리는 모델 생성 주석의 경우 True
)

매개변수

• dataset_path (str) - 데이터셋 루트 경로.

• project_name (str) - 대상 프로젝트의 ID. 없으면 생성됩니다.

• num_workers (int, 기본 10) - 동시 업로드 수. 25를 초과하지 않는 것이 좋습니다.

• project_license (str, 기본 "MIT") - 새로 생성된 프로젝트의 라이선스입니다. "Private" 를 비공개 프로젝트에 사용하세요(유료 플랜만).

• project_type (str, 기본 "object-detection") - 새로 생성된 프로젝트의 유형입니다. 프로젝트가 이미 있으면 무시됩니다.

• batch_name (str, 선택 사항) - 이 업로드들을 이름이 지정된 배치로 그룹화합니다. 라벨링 라운드의 출처를 추적하는 데 유용합니다.

• num_retries (int, 기본 0) - 일시적인 업로드 실패를 재시도합니다.

• is_prediction (bool, 기본 False) - True 로 설정하여 주석을 정답 대신 검토를 기다리는 모델 예측으로 업로드합니다.

예측이 저장되는 위치

아직 업로드 배치에 있는 이미지에 예측을 저장하면, Roboflow가 해당 이미지를 배치의 검토 작업으로 이동시킵니다. 레이블이 정답이 되기 전에 작업을 열어 승인하거나 수정하세요.

이미지가 이미 주석 작업에 할당되어 있으면, 해당 작업에 그대로 유지됩니다.

예상 디렉터리 구조

COCO 데이터셋의 경우:

my_dataset/
├── train/
│   ├── image1.jpg
│   └── _annotations.coco.json
├── valid/
│   ├── image2.jpg
│   └── _annotations.coco.json
└── test/
    ├── image3.jpg
    └── _annotations.coco.json

VOC의 경우 일치하는 .xml 파일을 각 이미지 옆에 두세요. YOLO의 경우 일치하는 .txt 파일과 하나의 data.yaml 클래스 목록을 설명하는 파일입니다.

SHA-256 중복 제거 참고(v1.3.6+)

현재 roboflow roboflow 1.3.6부터 SDK는 Pillow를 통해 다시 인코딩하는 대신 원본 이미지 바이트를 업로드합니다. 이는 웹 업로더와의 일관성을 제공하고 Roboflow 서버가 SHA-256으로 업로드를 중복 제거할 수 있게 합니다. 같은 이미지를 다시 업로드해도(예: 다른 배치에) 추가 저장소 크레딧을 소모하지 않고 성공합니다.

REST API

데이터셋 zip 업로드

비동기 작업을 사용하여 데이터셋을 단일 zip 아카이브(최대 2GB, 10,000개 파일)로 업로드합니다. 표준 이미지 업로드 엔드포인트와 달리 zip이 처리되는 동안 HTTP 연결을 계속 열어둘 필요가 없습니다. API는 zip을 PUT할 서명된 URL을 반환하고, 상태를 폴링할 taskId 를 반환합니다.

이 엔드포인트는 Roboflow 데이터셋 업로드 도구(COCO, YOLO, Pascal VOC 등)에서 지원하는 모든 형식의 이미지와 주석이 포함된 zip을 स्वीकार합니다. 분류 데이터셋의 경우 폴더 이름이 클래스 레이블로 사용됩니다.

흐름

1. POST /:workspace/:project/upload/zip 는 서명된 URL과 taskId.

2. PUT zip을 서명된 URL에 직접 업로드합니다.

3. GET /:workspace/upload/zip/:taskId 작업이 완료될 때까지 폴링합니다.

업로드 시작

보내세요 POST 를 /:workspace/:project/upload/zip. 응답에는 GCS 서명된 URL과 taskId.

curl -X POST "https://api.roboflow.com/my-workspace/my-project/upload/zip?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split": "train", "batchName": "my-batch"}'

본문 매개변수

- split (string, optional) - train, valid, test 중 하나입니다. 기본값은 train입니다.
- batchName (string, optional) - 이 이름의 배치 아래에 업로드된 이미지를 그룹화합니다.

주석이 포함된 zip은 batchName을 이름으로 하는 하나의 주석 작업에, 또는 생략하면 "Uploaded via API"라는 이름의 주석 작업에 들어갑니다. 이름을 재사용하더라도 모든 업로드는 각자의 작업을 받습니다. 작업 공간에 검토 모드 가 켜져 있으면, 이미지는 검토 상태에서 대기하다가 검토자가 승인하면 데이터셋에 추가됩니다.

응답

{
    "taskId": "abc123",
    "signedUrl": "https://storage.googleapis.com/...",
    "url": "https://api.roboflow.com/my-workspace/upload/zip/abc123"
}

zip 업로드

PUT 반환된 signedUrl. Content-Type은 application/zip.

curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: application/zip" \
  --upload-file ./my-dataset.zip

업로드가 완료되면 처리가 자동으로 시작됩니다.

작업 상태 폴링

보내세요 GET 를 /:workspace/upload/zip/:taskId.

curl "https://api.roboflow.com/my-workspace/upload/zip/abc123?api_key=$ROBOFLOW_API_KEY"

응답은 표준 비동기 작업 형식을 따릅니다. 작업이 완료되면, result 에는 이미지별 요약과 파싱 중에 발생한 경고 또는 오류가 포함됩니다.

{
    "taskId": "abc123",
    "status": "completed",
    "progress": { "current": 250, "total": 250 },
    "result": {
        "uploaded": 248,
        "failed": 2,
        "warnings": [],
        "errors": []
    }
}

이미지별 오류는 최대 100개, 경고는 최대 100개까지 보고됩니다. zip 내부의 비디오와 PDF는 지원되지 않는 형식 경고로 표시되고 건너뜁니다.

제한

• 최대 zip 크기: 2GB

• zip당 최대 파일 수: 10,000개

오류

- 400 - zip이 잘못 형성되었거나 크기 또는 파일 수 제한을 초과했습니다.
- 401 - API 키가 없거나 유효하지 않습니다.
- 404 - 작업 공간, 프로젝트, 작업이 존재하지 않거나 다른 작업 공간에 속합니다.

CLI

Roboflow CLI를 사용하여 이미지 및/또는 주석이 포함된 데이터셋을 업로드할 수 있습니다.

데이터셋을 업로드하는 방법을 안내하는 동영상을 준비했습니다:

디렉터리 업로드

사용 roboflow image upload 디렉터리 경로와 함께 사용하여 이미지별 병렬 업로드로 데이터셋을 대량 업로드합니다:

roboflow image upload /path/to/dataset/folder -p PROJECT_ID

또는 약식 별칭을 사용하세요:

roboflow upload /path/to/dataset/folder -p PROJECT_ID

CLI는 경로가 파일, 디렉터리 또는 .zip 파일인지 자동 감지합니다. 디렉터리는 --zip-upload.

옵션

플래그	설명
-p, --project	프로젝트 ID(필수)
-c, --concurrency	병렬 업로드 수(기본값: 10)
-b, --batch	업로드를 그룹화할 배치 이름
-r, --retries	실패한 업로드를 N번 재시도(기본값: 0)
-s, --split	업로드된 모든 이미지의 split을 재정의

옵션 예시:

roboflow upload ./my-dataset -p my-project -c 20 -b "april-batch" -r 3

zip 파일 업로드

더 큰 데이터셋이나 데이터셋이 이미 .zip 파일로 패키징된 경우 zip 업로드를 사용하세요. zip 업로드는 Roboflow의 비동기 zip 업로드 흐름을 사용합니다. 기본적으로 CLI는 zip 파일을 업로드하고 처리가 끝날 때까지 기다립니다.

이는 위에 문서화된 동일한 흐름입니다; REST API CLI가 서명된 URL 업로드와 작업 폴링을 대신 처리합니다.

기존 zip 파일을 업로드하려면:

roboflow image upload /path/to/dataset.zip -p PROJECT_ID

로컬 디렉터리를 클라이언트 측에서 zip으로 압축하고 비동기 zip 흐름으로 업로드하려면, 기본 명령과 함께 --zip-upload 를 사용하세요:

roboflow image upload /path/to/dataset/folder -p PROJECT_ID --zip-upload

zip 업로드 옵션

플래그	설명
-p, --project	프로젝트 ID(필수)
--zip-upload	디렉터리를 클라이언트 측에서 zip으로 압축하고 비동기 zip 업로드 흐름으로 업로드
--no-wait	처리가 끝날 때까지 기다리지 않고 zip 업로드 직후 즉시 반환
-b, --batch	업로드를 그룹화할 배치 이름
-s, --split	split 세트: train, valid 또는 test
-t, --tag	쉼표로 구분된 태그 이름

zip 업로드 옵션 예시:

roboflow image upload ./my-dataset.zip -p my-project -s train -t "outdoor,daytime" -b "april-batch"

처리를 시작하고 즉시 task ID를 반환하려면:

roboflow image upload ./my-dataset.zip -p my-project --no-wait --json

JSON 응답에는 비동기 작업 ID가 포함됩니다:

{
  "status": "pending",
  "task_id": "task-123",
  "path": "./my-dataset.zip",
  "project": "my-project",
  "result": {
    "task_id": "task-123",
    "status": "pending"
  }
}

zip 업로드는 다음을 지원하지 않습니다 --is-prediction. 예측 업로드에는 일반 이미지별 업로드 흐름을 사용하세요.

지원되는 프로젝트 유형

다음 프로젝트 유형의 데이터를 업로드할 수 있습니다:

• 객체 감지

• 단일 레이블 분류

• 다중 레이블 분류

• 인스턴스 분할

• 시맨틱 분할

• 키포인트 감지

지원되는 data.yaml 형식

CLI는 목록형과 키-값 쌍 형식의 클래스 이름 매핑을 모두 지원합니다 data.yaml 데이터셋 업로드 중 파일에서:

nc: 3
names: ['종이', '바위', '가위']

또는

nc: 3
names:
  0: 종이
  1: 바위
  2: 가위

JSON 출력

자동화를 위해 --json:

roboflow upload ./my-dataset -p my-project --json

{"status": "uploaded", "path": "./my-dataset", "project": "my-project"}

다음 단계

• 학습에 사용할 수 있도록 주석이 없는 이미지를 라벨링하세요. 다음을 참조하세요 Roboflow Annotate 소개.

• 이미지를 학습 가능한 스냅샷으로 전환하세요. 다음을 참조하세요 데이터셋 버전 만들기.