> 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` (문자열) - 데이터셋 루트 경로. * `project_name` (문자열) - 대상 프로젝트의 ID. 존재하지 않으면 생성됩니다. * `num_workers` (정수, 기본값 `10`) - 동시 업로드 수. 25를 넘기지 않는 것을 권장합니다. * `project_license` (문자열, 기본값 `"MIT"`) - 새로 생성되는 프로젝트의 라이선스입니다. 다음으로 설정하세요: `"Private"` 비공개 프로젝트의 경우. * `project_type` (문자열, 기본값 `"object-detection"`) - 새로 생성되는 프로젝트의 유형입니다. 프로젝트가 이미 있으면 무시됩니다. * `batch_name` (문자열, 선택 사항) - 이 업로드들을 이름이 있는 배치로 그룹화합니다. 라벨링 라운드의 출처를 추적하는 데 유용합니다. * `num_retries` (정수, 기본값 `0`) - 일시적인 업로드 실패를 재시도합니다. * `is_prediction` (부울, 기본값 `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` 인 이미지는 test 분할로 들어가지 않고, 이름이 `train2017` 인 폴더는 분할을 설정하지 않습니다. 폴더가 일치하지 않으면 이미지는 업로드의 기본 분할로 되돌아갑니다. zip 업로드의 경우 이는 `split` 요청 `train`. VOC의 경우 일치하는 `.xml` 파일을 각 이미지 옆에 넣으세요. YOLO의 경우 일치하는 `.txt` 파일과 `data.yaml` 을 넣어 클래스 목록을 설명하세요. ### SHA-256 중복 제거 참고(v1.3.6+) 다음 버전부터 `roboflow` 1.3.6에서 SDK는 Pillow를 통해 다시 인코딩하는 대신 원본 이미지 바이트를 업로드합니다. 이는 웹 업로더와의 동등성을 제공하며, Roboflow 서버가 SHA-256으로 업로드를 중복 제거할 수 있게 해줍니다. 동일한 이미지를 다시 업로드해도(예: 다른 배치에) 추가 저장소 크레딧을 사용하지 않고 성공합니다. ## REST API ### 데이터셋 ZIP 업로드 비동기 작업을 사용하여 데이터셋을 단일 zip 아카이브(최대 2 GB, 파일 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 (문자열, 선택 사항) - train, valid, test 중 하나입니다. 기본값은 train입니다. - batchName (문자열, 선택 사항) - 업로드한 이미지들을 이 이름의 배치로 그룹화합니다. - tags (문자열 배열, 선택 사항) - 업로드된 각 이미지 또는 비디오에 추가할 태그입니다. - annotationOverwrite (불리언, 선택 사항) - 이미 프로젝트에 있는 이미지의 주석을 교체합니다. 기본값은 false입니다. ``` 기본적으로 이미 프로젝트에 있는 이미지는 보유한 주석을 유지하고, zip의 주석은 건너뜁니다. `annotationOverwrite` 을 `true` 로 설정하면 이를 교체합니다. 분류 프로젝트는 항상 레이블을 교체하므로 기본값을 무시하고 `annotationOverwrite: false` 를 400으로 거부합니다. 주석이 포함된 zip은 다음 이름의 하나의 주석 작업으로 들어갑니다. `batchName`, 또는 생략하면 "Uploaded via API"입니다. 이름을 재사용하더라도 각 업로드는 고유한 작업을 갖습니다. 작업공간에 [Review Mode](/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` 반환된 `signedUrl`에 zip 파일을 업로드하세요. 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는 지원되지 않는 형식 경고와 함께 건너뜁니다. 비디오는 Action Recognition 프로젝트가 아닌 경우 같은 방식으로 건너뜁니다. Action Recognition 프로젝트에서는 zip 안의 최대 3 GB짜리 MP4 또는 MOV 비디오가 각각 비디오로 추가되며, 이는 다음과 같습니다: [비디오 업로드](/datasets/ko/create-and-upload/adding-data.md#upload-a-video). zip 안의 이미지는 경고와 함께 건너뜁니다. 비디오는 업로드의 태그, 배치, 분할을 적용받으며, `train`, `valid`또는 `test` 폴더는 이미지와 마찬가지로 분할을 설정합니다. `result.videosStaged` 는 추가된 비디오 수를 계산하고, `result.videoIds` 는 해당 ID를 최대 100개까지 나열합니다. 각 ID를 사용해 [해당 비디오의 상태를 확인하세요](/datasets/ko/create-and-upload/adding-data.md#upload-a-video). zip 내부의 비디오 레이블은 가져오지 않습니다. #### 제한 * 최대 zip 크기: 2 GB * 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 Server AI 에이전트를 [MCP Server](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).