> 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/versions/dataset-versions/create-a-dataset-version.md).

# 데이터셋 버전 만들기

모델 학습에 사용할 데이터셋 버전을 만듭니다.

## 소개

버전은 데이터셋의 시점 스냅샷입니다. 우리는 각 모델 반복에서 어떤 이미지, 전처리, 증강 단계가 정확히 사용되었는지를 추적함으로써 이러한 버전을 보존합니다. 이를 통해 결과를 재현할 수 있는 능력을 유지할 수 있습니다. 따라서 데이터 파이프라인의 버그/변경 때문이 아니라 모델 변경에 기인한 결과인지 확신을 가지고, 다양한 모델과 프레임워크에 걸쳐 과학적으로 테스트할 수 있습니다.

<a href="https://docs.roboflow.com/platform/workspaces/key-concepts" class="button primary">핵심 개념: 작업 공간과 프로젝트란 무엇인가요?</a>

{% hint style="info" %}
버전이 생성되면 그 시점에서 고정되므로, 이미지, 주석 또는 기타 데이터를 추가/삭제하는 등 프로젝트에 대한 변경 사항은 그 이전에 생성된 버전에 영향을 주지 않습니다.
{% endhint %}

## 웹 앱

### 데이터셋 버전을 만드는 방법

데이터셋 버전을 만들려면 Roboflow 프로젝트와 연결된 사이드바에서 "Versions"를 클릭한 다음 "Generate New Version"을 클릭하세요.

이 페이지에서 훈련/테스트/검증 분할을 설정하고 새 데이터셋 버전에 대한 전처리 단계와 증강을 지정할 수 있습니다.

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-15210ee011b26459ed30a427ac60bdfb85934980%2FScreenshot%202023-06-22%20at%2015.37.50.png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

데이터에 적용할 전처리 단계와 증강을 지정한 후 "Generate"를 클릭하세요. 그러면 새 데이터셋 버전이 생성됩니다. 그런 다음 이 데이터셋 버전을 사용해 Roboflow에서 모델을 학습할 수 있습니다. 또한 [데이터셋을 내보내어](https://docs.roboflow.com/datasets/ko/versions/dataset-versions/exporting-data.md) 모델을 수동으로 학습하는 데 사용할 수도 있습니다.

### 훈련/검증/테스트 분할 재조정

버전 생성 과정에서 훈련, 검증, 테스트 세트 분할의 균형도 다시 조정할 수 있습니다. 이렇게 하려면 "Step 2: Train/Test Split"로 이동한 다음 "Rebalance" 버튼을 클릭하세요.

<figure><img src="https://3735512388-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-4c91693393b132f1503c086f5ebf67f27dd9a4b9%2Fimage%20(342).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

권장 분할 비율은 70/20/10(train/valid/test)이며, 대부분의 데이터셋에 적합한 좋은 출발점입니다. 언제든지 "Reset"을 클릭하여 복원할 수 있습니다.

훈련, 검증, 테스트 비율을 설정한 다음 이미지가 재할당되는 방식을 선택하세요:

* "Move as few as possible"은 이미지를 현재 분할에 그대로 두고, 목표 비율에 도달하는 데 필요한 만큼만 이동합니다.
* "Random shuffle"은 모든 이미지를 분할 간에 무작위로 재할당합니다.
* "Random shuffle per upload batch or annotation job"은 각 업로드 배치 또는 완료된 주석 작업을 개별적으로 섞어, 모든 배치와 작업이 목표 비율에 맞도록 합니다.

특정 클래스에만 범위를 지정하여 재균형을 조정할 수도 있습니다. 클래스를 선택하면 해당 클래스만 포함하는 이미지로 이동이 제한되며, 방법은 "Move as few as possible"로 전환됩니다.

대규모 데이터셋의 경우 재균형은 단계별 진행 상황이 표시되는 백그라운드 작업으로 실행됩니다. 대화상자를 닫아도 계속 진행되며, Activity Center에서 추적할 수 있습니다.

## HTTP API

### 훈련/검증/테스트 분할 재균형

다음에 POST 요청을 보내 프로젝트의 분할을 재균형하세요. `/:workspace/:project/splits/rebalance` 엔드포인트. 이 작업은 프로젝트 자체의 분할을 변경하므로, 다음에 생성하는 버전은 새로운 균형을 사용합니다.

재균형은 항상 백그라운드 작업으로 실행됩니다. 요청은 `202 Accepted` 와 함께 작업 ID와 폴링 URL을 반환합니다. 반환된 `url`을 폴링하거나 `GET /:workspace/asynctasks/:id` 를 `taskId`와 함께 호출하여 작업이 완료될 때까지 기다리세요.

호출하는 API 키에는 `project:update` 범위와 Workspace에서 분할을 편집할 권한이 있어야 합니다.

**예시 요청**

```bash
$ curl --location "https://api.roboflow.com/my-workspace/my-project/splits/rebalance?api_key=$ROBOFLOW_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "splits": { "train": 70, "valid": 20, "test": 10 }
}'
```

**매개변수**

```
- splits (object) - 필수. 대상 train, valid, test 값이며 각각 0 이상의 정수여야 합니다. 값은 상대값이므로 70/20/10은 70%/20%/10%를 의미합니다. 적어도 하나는 0보다 커야 합니다.
- mode (string) - "rebalance"(기본값)는 가능한 한 적은 이미지만 이동합니다. "shuffle"은 모든 이미지를 무작위로 다시 할당합니다.
- grouping (string) - "shuffle" 모드에서만 사용됩니다. "global"(기본값)은 전체 프로젝트를 섞습니다. "batch"는 각 업로드 배치와 완료된 주석 작업을 개별적으로 섞습니다.
- classes (array of strings) - 재균형을 이 클래스들만 포함하는 이미지로 제한합니다. 다른 클래스가 있는 이미지는 현재 분할에 유지됩니다.
```

**예시 응답**

```json
{
    "taskId": "abc123",
    "url": "https://api.roboflow.com/my-workspace/asynctasks/abc123"
}
```

## Python SDK

버전은 선택한 전처리 및 증강 단계를 적용한 프로젝트의 레이블된 데이터 스냅샷을 고정합니다. 프로젝트 자체가 아니라 버전을 대상으로 학습하세요.

`Project.generate_version()` 은 새 버전 번호를 반환하며, 이를 `project.version(...)` 에 전달하여 `Version` 핸들을 얻을 수 있습니다.

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("my-detector")

new_version = project.generate_version(settings={
    "preprocessing": {
        "auto-orient": True,
        "resize": {"width": 640, "height": 640, "format": "Stretch to"},
    },
    "augmentation": {},
})
version = project.version(new_version)
```

`augmentation.image.versions` 는 최대 버전 크기 배율이며, 사용 중인 요금제에서 상한이 정해집니다. 더 크게 설정하면 생성이 실패합니다. 참조 [증강 제한](https://docs.roboflow.com/datasets/ko/versions/dataset-versions/image-augmentation.md#limiting-augmentations).

다음은 설정의 전체 예시입니다. 아래에서 각 속성에 대한 자세한 설명을 볼 수 있습니다.

```json
{
    "versionName": "Raccoons",
    "augmentation": {
        "bbblur": { "pixels": 1.5 },
        "bbbrightness": { "brighten": true, "darken": false, "percent": 91 },
        "bbcrop": { "min": 12, "max": 71 },
        "bbexposure": { "percent": 30 },
        "bbflip": { "horizontal": true, "vertical": false },
        "bbnoise": { "percent": 50 },
        "bbninety": { "clockwise": true, "counter-clockwise": false, "upside-down": false },
        "bbrotate": { "degrees": 45 },
        "bbshear": { "horizontal": 45, "vertical": 45 },
        "blur": { "pixels": 1.5 },
        "brightness": { "brighten": true, "darken": false, "percent": 91 },
        "crop": { "min": 12, "max": 71 },
        "cutout": { "count": 26, "percent": 71 },
        "exposure": { "percent": 30 },
        "flip": { "horizontal": true, "vertical": false },
        "hue": { "degrees": 180 },
        "image": { "versions": 32 },
        "mosaic": true,
        "ninety": { "clockwise": true, "counter-clockwise": false, "upside-down": false },
        "noise": { "percent": 50 },
        "rgrayscale": { "percent": 50 },
        "rotate": { "degrees": 45 },
        "saturation": { "percent": 50 },
        "shear": { "horizontal": 45, "vertical": 45 }
    },
    "preprocessing": {
        "auto-orient": true,
        "contrast": { "type": "Contrast Stretching" },
        "filter-null": { "percent": 50 },
        "filter-tags": { "tag_name": true, "other_tag": false },
        "grayscale": true,
        "isolate": true,
        "remap": { "original_class_name": "new_class_name" },
        "resize": { "width": 200, "height": 200, "format": "Stretch to" },
        "static-crop": { "x_min": 10, "x_max": 90, "y_min": 10, "y_max": 90 },
        "tile": { "rows": 2, "columns": 2 }
    }
}
```

`타일` 은 다음의 고정 타일 모드도 지원합니다: `{"mode": "fixed_size", "tileWidth": 640, "tileHeight": 640, "overlap": 5, "padding": "black"}` 또는 `{"mode": "fixed_aspect", "aspectRatio": 1, "span": "width", "overlap": 5, "padding": "black"}`. 참조 [타일](https://docs.roboflow.com/datasets/ko/versions/dataset-versions/image-preprocessing.md#tile).

## MCP 서버

AI 에이전트를 다음에 연결하면 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 그리고 다음 도구들로 데이터셋 버전을 생성할 수 있습니다:

<table data-search="false"><thead><tr><th width="290">도구</th><th>설명</th></tr></thead><tbody><tr><td><code>versions_generate</code></td><td>선택적 전처리 및 증강을 적용해 버전을 생성합니다.</td></tr><tr><td><code>versions_get</code></td><td>분할 정보와 학습 정보를 포함한 버전 정보를 가져옵니다.</td></tr><tr><td><code>datasets_rebalance_splits</code></td><td>훈련, 검증, 테스트 분할의 비동기 재균형을 대기열에 넣습니다.</td></tr><tr><td><code>async_tasks_get</code></td><td>재균형 작업이 끝날 때까지 폴링합니다.</td></tr></tbody></table>
