> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/ko/create-and-upload/upload-a-dataset.md).

# 데이터셋 업로드

Python SDK를 사용해 구조화된 이미지 및 주석 데이터셋을 Roboflow 프로젝트에 업로드합니다.

이 페이지에서는 Python SDK, HTTP API 또는 CLI를 사용해 기존 레이블 지정 데이터셋(이미지와 해당 주석)을 일괄 가져오는 방법을 설명합니다. API를 통해 개별 이미지를 업로드하고 관리하는 방법은 다음을 참조하세요. [이미지 관리](https://docs.roboflow.com/datasets/ko/manage/manage-images.md).

## Python SDK

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

```python
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
```

각 이미지가 들어 있는 폴더 이름에 따라 데이터 분할이 정해집니다. 다음과 정확히 일치하는 폴더 이름만 인식됩니다: `train`, `training`, `valid`, `validation`, `val`, `test` 및 `testing`. 대소문자는 구분하지 않으며 파일 이름은 무시됩니다. 따라서 이름이 `test_image.jpg` 인 이미지는 테스트 분할에 포함되지 않고, 이름이 `train2017` 인 폴더도 분할을 지정하지 않습니다. 일치하는 폴더가 없으면 이미지에는 업로드의 기본 분할이 적용됩니다. ZIP 업로드의 경우 기본 분할은 요청의 `split` 값이며, 기본값은 `train`.

VOC의 경우 각 이미지와 같은 위치에 해당하는 `.xml` 파일을 넣으세요. YOLO의 경우 해당하는 `.txt` 파일과 클래스 목록을 설명하는 `data.yaml` 파일을 넣으세요.

### SHA-256 중복 제거 참고 사항(v1.3.6 이상)

버전 `roboflow` 1.3.6부터 SDK는 Pillow를 통해 이미지를 다시 인코딩하는 대신 원본 이미지 바이트를 업로드합니다. 이에 따라 웹 업로더와 동작이 일치하며, Roboflow 서버에서 SHA-256을 기준으로 업로드를 중복 제거할 수 있습니다. 따라서 같은 이미지를 다시 업로드해도(예: 다른 배치에 업로드) 추가 저장 크레딧을 사용하지 않고 성공합니다.

## HTTP API

### 데이터 세트 ZIP 업로드

전체 데이터 세트를 ZIP 파일 하나로 업로드합니다. Roboflow가 백그라운드에서 처리하므로 처리 중에 연결을 유지할 필요가 없습니다. ZIP에는 지원되는 형식(예: COCO, YOLO, Pascal VOC)의 이미지와 어노테이션을 넣을 수 있습니다. 분류 작업의 경우 폴더 이름이 클래스 레이블이 됩니다.

업로드는 다음 세 단계로 진행됩니다:

1. 업로드를 시작합니다. 응답에는 서명된 URL과 `taskId`.
2. 서명된 URL에 다음을 사용해 ZIP을 PUT합니다. `Content-Type: application/zip`. 업로드가 완료되면 처리가 시작됩니다.
3. 작업 상태가 다음 중 하나가 될 때까지 폴링합니다: `completed` 또는 `failed`.

{% openapi src="/files/92b2637425a242011c91d76461d36ea8fdcaa54a" path="/{workspace}/{project}/upload/zip" method="post" %}
[dataset-zip-upload.yaml](https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-25a53c9e468fe23c13da4395e49bc7a5287c5a12%2Fdataset-zip-upload.yaml?alt=media)
{% endopenapi %}

서명된 URL은 Roboflow API가 아니라 Google Cloud Storage에 있습니다. 따라서 API 키를 포함하지 말고 해당 URL로 파일을 전송하세요:

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

기본적으로 프로젝트에 이미 있는 이미지의 어노테이션은 유지되고, ZIP에 포함된 해당 이미지의 어노테이션은 건너뜁니다. 기존 어노테이션을 바꾸려면 `annotationOverwrite` 를 `true` 로 설정하세요.

업로드 심사에서 보류되지 않은 이미지의 어노테이션은 Dataset에 바로 추가되거나, [검토 모드](https://docs.roboflow.com/datasets/ko/annotate/annotate/team-collaboration.md#review-mode) 가 켜져 있으면 검토 작업에 추가됩니다. 어노테이션이 없는 이미지는 라벨링을 위한 배치에 들어갑니다. 보류된 이미지의 어노테이션은 심사에서 승인되면 저장되고, 승인되지 않으면 삭제됩니다.

{% openapi src="/files/92b2637425a242011c91d76461d36ea8fdcaa54a" path="/{workspace}/upload/zip/{taskId}" method="get" %}
[dataset-zip-upload.yaml](https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-25a53c9e468fe23c13da4395e49bc7a5287c5a12%2Fdataset-zip-upload.yaml?alt=media)
{% endopenapi %}

완료된 ZIP 작업에도 업로드 심사에서 보류된 이미지가 있을 수 있습니다. `result.screening` 개수는 `result.uploaded`에 포함됩니다. 이러한 이미지는 아직 프로젝트나 Dataset에서 사용할 수 없습니다. 심사를 통과하거나 수정된 이미지는 나중에 사용할 수 있게 되지만, 거부되거나 심사에 실패한 이미지는 사용할 수 없습니다. ZIP 결과에는 이미지별 최종 판정이 포함되지 않습니다. 업로드 응답에 보류된 이미지 ID가 있으면 [해당 이미지의 심사 판정을 확인하거나](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data.md#check-image-upload-screening), MCP를 통해 `images_screening_status` 를 사용하세요. 심사 판정만으로 Dataset에 추가할 준비가 끝났다고 확인할 수는 없습니다.

ZIP 안의 PDF는 지원되지 않는 형식이라는 경고와 함께 건너뜁니다. 동영상도 Action Recognition 프로젝트가 아닌 경우 같은 방식으로 건너뜁니다.

Action Recognition 프로젝트에서는 ZIP에 포함된 최대 3GB의 MP4 또는 MOV 동영상이 [동영상 업로드](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data.md#upload-a-video)와 같은 방식으로 동영상으로 추가됩니다. ZIP 안의 이미지는 경고와 함께 건너뜁니다. 동영상에는 업로드의 태그, 배치, 분할이 적용되며, `train`, `valid`또는 `test` 폴더를 사용하면 이미지와 동일한 방식으로 분할이 설정됩니다. 각 ID를 사용해 `result.videoIds` 의 [해당 동영상의 상태를 확인](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data.md#upload-a-video)하세요. ZIP 안의 동영상 라벨은 가져오지 않습니다.

## CLI

Roboflow CLI를 사용해 이미지 및/또는 어노테이션이 포함된 데이터셋을 업로드할 수 있습니다.

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

{% embed url="<https://www.loom.com/share/19637984033a466b831af56f9404fa89>" %}

### 디렉터리 업로드

디렉터리 경로를 지정해 `roboflow image upload` 를 사용하면 이미지별 업로드를 병렬로 수행해 데이터셋을 일괄 업로드할 수 있습니다.

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

또는 더 짧은 별칭을 사용하세요.

```bash
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`       | 업로드하는 모든 이미지의 분할을 재정의합니다 |

옵션 사용 예:

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

### ZIP 파일 업로드

대규모 데이터셋을 업로드하거나 데이터셋이 이미 `.zip` 파일로 압축되어 있는 경우 zip 업로드를 사용하세요. zip 업로드는 Roboflow의 비동기 zip 업로드 흐름을 사용합니다. 기본적으로 CLI는 zip 파일을 업로드한 후 처리가 완료될 때까지 기다립니다.

이는 위에서 설명한 [HTTP API](#http-api) 와 동일한 흐름입니다. CLI가 서명된 URL을 통한 업로드와 작업 폴링을 대신 처리합니다.

기존 zip 파일을 업로드하려면 다음을 실행하세요:

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

로컬 디렉터리를 클라이언트 측에서 zip 파일로 압축한 뒤 비동기 zip 업로드 흐름으로 업로드하려면 기본 명령에 `--zip-upload` 를 사용하세요:

```bash
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`   | 분할 세트: train, valid 또는 test                           |
| `-t`, `--tag`     | 쉼표로 구분된 태그 이름                                         |

zip 업로드 옵션 사용 예:

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

처리를 시작하고 작업 ID를 즉시 반환하려면 다음을 실행하세요:

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

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

```json
{
  "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` 파일에서 목록 형식과 키-값 쌍 형식의 클래스 이름 매핑을 모두 지원합니다:

```yaml
nc: 3
names: ['Paper', 'Rock', 'Scissors']
```

또는

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

### JSON 출력

자동화를 위해 다음을 사용하세요 `--json`:

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

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

## MCP 서버

AI 에이전트를 다음에 연결하세요:  [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 이미지와 선택적 주석 파일을 ZIP으로 업로드할 수 있습니다. 업로드 작업을 폴링하고, 검토를 위해 보류된 이미지가 있으면 별도로 보고하세요. 학습 전에 데이터셋 준비 상태를 확인하세요.

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>image_upload</code></td><td>이미지와 선택적 주석 파일을 ZIP으로 업로드할 수 있도록 준비하세요.</td></tr><tr><td><code>image_upload_status</code></td><td>이미지 ZIP 업로드 작업의 상태를 확인하세요.</td></tr><tr><td><code>annotations_save</code></td><td>이미 업로드된 이미지의 주석을 저장합니다.</td></tr><tr><td><code>images_screening_status</code></td><td>보류된 이미지 ID 하나의 검토 결과를 확인합니다.</td></tr></tbody></table>

## 다음 단계

* 주석이 없는 이미지에 라벨을 지정하여 학습에 사용할 수 있도록 하세요. 자세한 내용은 다음을 참조하세요:  [Roboflow Annotate 소개](https://docs.roboflow.com/datasets/ko/annotate/annotate/annotation-tools.md).
* 이미지를 학습 가능한 스냅샷으로 변환하세요. 자세한 내용은 다음을 참조하세요:  [데이터셋 버전 만들기](https://docs.roboflow.com/datasets/ko/versions/dataset-versions/create-a-dataset-version.md).
