> 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, 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` 주석을 실제 정답이 아니라 검토를 기다리는 모델 예측으로 업로드합니다. ### 예상 디렉터리 구조 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+) As of `roboflow` v1.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, 선택 사항) - 업로드된 이미지를 이 이름의 배치로 그룹화합니다. ``` 주석이 포함된 zip은 `batchName`으로 이름 붙은 하나의 주석 작업에 들어가며, 지정하지 않으면 "Uploaded via API"로 표시됩니다. 같은 이름을 다시 사용해도 업로드마다 각각의 작업이 생성됩니다. 워크스페이스에 [검토 모드](/datasets/ko/annotate/annotate/team-collaboration.md#review-mode) 이 켜져 있으면, 이미지는 Review에서 대기하다가 검토자가 승인하면 데이터셋에 합쳐집니다. **응답** ```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개씩 보고됩니다. 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` | 업로드된 모든 이미지의 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"} ``` ## 다음 단계 * 학습에 사용할 수 있도록 주석이 없는 이미지를 모두 레이블링하세요. 다음을 참조하세요 [Roboflow Annotate 소개](/datasets/ko/annotate/annotate/annotation-tools.md). * 이미지를 학습 가능한 스냅샷으로 변환하세요. 다음을 참조하세요 [데이터셋 버전 생성](/datasets/ko/versions/dataset-versions/create-a-dataset-version.md).