> 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, REST zip 엔드포인트 또는 CLI를 사용하여 기존 레이블 지정 데이터셋(이미지 및 해당 어노테이션)을 일괄 가져오는 방법을 다룹니다. API를 통해 개별 이미지를 업로드하고 관리하려면 다음을 참조하세요. [이미지 관리](/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 ``` VOC의 경우 일치하는 `.xml` 파일을 각 이미지와 함께 배치합니다. YOLO의 경우 일치하는 `.txt` 파일과 `data.yaml` 클래스 목록을 설명하는 파일을 배치합니다. ### SHA-256 중복 제거 참고 사항(v1.3.6+) 다음 버전부터 `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`. ```bash 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, 선택 사항) - train, valid 또는 test 중 하나입니다. 기본값은 train입니다. - batchName (string, 선택 사항) - 업로드된 이미지를 이 이름의 배치 아래에 그룹화합니다. - annotationOverwrite (boolean, 선택 사항) - 이미 프로젝트에 있는 이미지의 어노테이션을 교체합니다. 기본값은 false입니다. ``` 기본적으로 프로젝트에 이미 있는 이미지는 기존 어노테이션을 유지하며, zip에 포함된 해당 이미지의 어노테이션은 건너뜁니다. 다음을 설정하세요. `annotationOverwrite` 다음 위치로 `true` 교체하려면 사용합니다. 분류 프로젝트는 항상 레이블을 교체하므로 기본값을 무시하고 다음을 거부합니다. `annotationOverwrite: false` 400 오류와 함께. 어노테이션을 포함한 zip은 다음 이름의 어노테이션 작업 하나에 저장됩니다. `batchName`, 또는 이를 생략하면 "Uploaded via API"입니다. 이름을 재사용해도 각 업로드에는 자체 작업이 할당됩니다. 워크스페이스에 [검토 모드](/datasets/ko/annotate/annotate/team-collaboration.md#review-mode) 가 켜져 있으면 이미지는 검토 상태에서 대기하며 검토자가 승인하면 데이터셋에 추가됩니다. **응답** ```json { "taskId": "abc123", "signedUrl": "https://storage.googleapis.com/...", "url": "https://api.roboflow.com/my-workspace/upload/zip/abc123" } ``` #### Zip 업로드 `PUT` zip 파일을 반환된 `signedUrl`에 업로드합니다. Content-Type은 다음이어야 합니다. `application/zip`. ```bash curl -X PUT "$SIGNED_URL" \ -H "Content-Type: application/zip" \ --upload-file ./my-dataset.zip ``` 업로드가 완료되면 처리가 자동으로 시작됩니다. #### 작업 상태 폴링 다음을 전송합니다. `GET` 다음 위치로 `/:workspace/upload/zip/:taskId`. ```bash curl "https://api.roboflow.com/my-workspace/upload/zip/abc123?api_key=$ROBOFLOW_API_KEY" ``` 응답은 표준 [비동기 작업](https://docs.roboflow.com/reference/platform/rest-api/async-tasks) 형식을 따릅니다. 작업이 완료되면 `result` 에는 이미지별 요약과 파싱 중 발생한 경고 또는 오류가 포함됩니다. ```json { "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를 사용하여 이미지 및/또는 어노테이션이 포함된 데이터셋을 업로드할 수 있습니다. 데이터셋 업로드 방법을 안내하는 동영상을 준비했습니다: {% embed url="" %} ### 디렉터리 업로드 다음을 사용하세요. `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 파일을 업로드하고 처리가 끝날 때까지 기다립니다. 이는 다음에 문서화된 동일한 흐름입니다. [REST API](#rest-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: Paper 1: Rock 2: Scissors ``` ### 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에는 이미지만 포함되므로 레이블은 두 번째 단계에서 저장됩니다.
도구설명
image_uploadzip을 통해 로컬 이미지 파일을 프로젝트에 업로드합니다. 이미지만 가능하며 어노테이션 파일은 지원하지 않습니다.
image_upload_status이미지 zip 업로드 작업의 상태를 확인합니다.
annotations_save이미 업로드된 이미지의 어노테이션을 저장합니다.
## 다음 단계 * 어노테이션이 없는 이미지를 레이블 지정하여 학습에 사용할 수 있게 하세요. 다음을 참조하세요. [Roboflow Annotate 소개](/datasets/ko/annotate/annotate/annotation-tools.md). * 이미지를 학습 가능한 스냅샷으로 전환하세요. 다음을 참조하세요. [데이터셋 버전 생성](/datasets/ko/versions/dataset-versions/create-a-dataset-version.md).