> 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/models/ko/model-weights/upload-custom-weights.md).

# 사용자 지정 모델 가중치 업로드

Roboflow는 사용자 지정 학습 모델의 가중치를 Roboflow 프로젝트에 업로드하여 모델을 배포할 수 있도록 지원합니다.

## Roboflow 외부에서 학습된 가중치 업로드

사용자 지정 모델 학습을 완료한 후, 모델 가중치를 Roboflow 프로젝트에 다시 업로드하여 다음을 활용하세요 [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted).

Roboflow에서 모델을 학습하려면 다음을 참조하세요 [모델 학습](https://docs.roboflow.com/models/ko/train/train-a-model.md).

### 모델 지원

YOLOv5, YOLOv7, YOLOv9, YOLOv10 가중치의 새 업로드는 더 이상 지원되지 않습니다. 이미 업로드된 기존 모델은 추론에 계속 사용할 수 있습니다.

이 모델 계열의 가중치를 업로드할 수 있습니다. 다음의 값에 전달하세요 `model_type` 열을 Python SDK 또는 CLI에.

<table data-search="false"><thead><tr><th>모델</th><th>model_type</th></tr></thead><tbody><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/rf-detr.md">RF-DETR</a></td><td><code>rfdetr-nano</code> 부터 <code>rfdetr-2xlarge</code>, <code>rfdetr-seg-nano</code> 부터 <code>rfdetr-seg-2xlarge</code>, <code>rfdetr-keypoint-preview</code></td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/yolo26.md">YOLO26</a></td><td><code>yolo26n</code>, <code>yolo26s</code>, <code>yolo26m</code>, <code>yolo26l</code>, <code>yolo26x</code> (추가 <code>-seg</code>, <code>-pose</code>또는 <code>-sem</code> 다른 작업의 경우)</td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/yolov12.md">YOLOv12</a></td><td><code>yolov12n</code> 부터 <code>yolov12x</code></td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/yolo11.md">YOLO11</a></td><td><code>yolov11n</code> 부터 <code>yolov11x</code> (추가 <code>-seg</code> 또는 <code>-pose</code> 다른 작업의 경우)</td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/yolov8.md">YOLOv8</a></td><td><code>yolov8n</code> 부터 <code>yolov8x</code> (추가 <code>-seg</code> 또는 <code>-pose</code> 다른 작업의 경우)</td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/yolo-nas.md">YOLO-NAS</a></td><td><code>yolonas</code></td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/paligemma2.md">PaliGemma 2</a></td><td><code>paligemma2-3b-pt-224</code>, <code>-448</code>, <code>-896</code> (추가 <code>-peft</code> LoRA 가중치용)</td></tr><tr><td><a href="https://docs.roboflow.com/models/ko/supported-models/florence-2.md">Florence 2</a></td><td><code>florence-2-base</code>, <code>florence-2-large</code></td></tr></tbody></table>

{% hint style="warning" %}

* YOLOv8 모델은 다음 버전에서 학습되어야 합니다 `ultralytics==8.0.196`
* YOLOv11 모델은 다음 버전에서 학습되어야 합니다 `ultralytics<=8.3.40`
* YOLOv12 모델은 다음을 사용하여 학습 및 업로드해야 합니다 `ultralytics` 에서 <https://github.com/sunsmarterjie/yolov12>
  {% endhint %}

{% hint style="info" %}
모델 크기가 클수록 학습 결과는 더 좋습니다. 그러나 모델 크기가 커질수록 학습 시간과 추론(모델 예측) 속도는 느려집니다. 빠르게 움직이는 객체나 비디오 피드에서 실시간 추론이 필요한지, 아니면 수집된 후의 데이터를 처리하면서 더 높은 예측 정확도가 중요한지 고려하세요(더 작은 모델을 선택하는 것이 좋음).
{% endhint %}

### 버전 관리 모델 vs. 버전 없는 모델 업로드

Roboflow는 프로젝트에 모델을 배포하는 두 가지 서로 다른 방식을 제공합니다. 각각은 서로 다른 사용 사례와 조직상의 요구를 충족합니다. 버전 관리 배포와 버전 없는 배포 중 어떤 것을 선택할지는 데이터셋 버전과 함께 모델의 변화를 추적할지, 아니면 작업 공간의 여러 프로젝트에서 모델을 공유할지에 따라 달라집니다.

* **버전 없는 배포**
  * 작업 공간 수준에 연결됨
  * 여러 프로젝트에 동시에 배포할 수 있음
  * 같은 작업 공간 내의 서로 다른 프로젝트 간 모델 공유에 이상적임
* **버전 관리 배포**
  * 특정 프로젝트 버전에 연결됨
  * A [버전](https://docs.roboflow.com/models/ko/versions-trainings-and-models.md) 에는 여러 개의 업로드된 모델이 있을 수 있음
  * 데이터셋 버전과 함께 모델 변화를 추적하는 데 이상적임
  * Label Assist에서 모델을 사용하는 데 이상적임
  * 다른 모델을 학습하기 위한 체크포인트로 모델을 사용하는 데 이상적임

## Python SDK

먼저 최신 버전의 `roboflow` Python 패키지가 설치되어 있는지 확인하세요:

```bash
pip install --update roboflow
```

### 버전 없는 모델

버전 없는 사용자 지정 가중치를 업로드하려면 다음을 사용하세요 `workspace.deploy_model()` 메서드:

```python
workspace.deploy_model(
    model_type="yolov8",  # 모델 유형
    model_path="path/to/model",  # 모델 디렉터리 경로
    project_ids=["project1", "project2"],  # 프로젝트 ID 목록
    model_name="my-model",  # 모델 이름(적어도 1개의 문자를 포함해야 하며 숫자와 대시를 허용함)
    filename="weights/best.pt"  # 가중치 파일 경로(기본값)
)
```

**매개변수**

| 매개변수          | 유형         | 필수  | 설명                                            |
| ------------- | ---------- | --- | --------------------------------------------- |
| `model_type`  | str        | 예   | 배포할 모델 유형, 예: `yolov8`, `yolov11`.            |
| `model_path`  | str        | 예   | 모델 가중치가 들어 있는 디렉터리의 경로.                       |
| `project_ids` | list\[str] | 예   | 모델을 배포할 프로젝트 ID.                              |
| `model_name`  | str        | 예   | 모델을 식별하는 이름. 적어도 하나의 문자를 포함해야 하며 숫자와 대시를 허용함. |
| `filename`    | str        | 아니요 | 가중치 파일 이름. 기본값은 `weights/best.pt`.            |

**예시**

```python
from roboflow import Roboflow

rf = Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace("YOUR_WORKSPACE")

workspace.deploy_model(
  model_type="yolov8",
  model_path="./runs/train/weights",
  project_ids=["project-1", "project-2", "project-3"],
  model_name="my-custom-model"
)
```

### 버전 관리 모델

{% hint style="info" %}
버전 관리 사용자 지정 가중치 업로드는 업로드된 각 모델을 데이터셋 버전에 연결합니다. 데이터셋에 생성된 버전이 없으면 하나를 만들 수 있습니다 [앱 내에서](https://docs.roboflow.com/datasets/versions/dataset-versions/create-a-dataset-version) 또는 다음을 통해 [API](https://docs.roboflow.com/datasets/versions/dataset-versions/create-a-dataset-version#python-sdk).

다음 문서를 참조하세요 [API를 통해 버전을 로드하는 방법](https://docs.roboflow.com/datasets/versions/dataset-versions#view-a-version) 또는 아래 예시를 참고하세요.
{% endhint %}

사용자 지정 가중치를 업로드하려면 다음을 사용하세요 `version.deploy()` Python SDK의 메서드.

**사용법**

```python
version.deploy(
    model_type="yolov8",  # 모델 유형
    model_path="path/to/model",  # 모델 디렉터리 경로
    filename="weights/best.pt"  # 가중치 파일 경로(기본값)
)
```

**매개변수**

| 매개변수         | 유형  | 필수  | 설명                                 |
| ------------ | --- | --- | ---------------------------------- |
| `model_type` | str | 예   | 배포할 모델 유형, 예: `yolov8`, `yolov11`. |
| `model_path` | str | 예   | 모델 가중치가 들어 있는 디렉터리의 경로.            |
| `filename`   | str | 아니요 | 가중치 파일 이름. 기본값은 `weights/best.pt`. |

**예시**

```python
from roboflow import Roboflow

rf = Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("PROJECT_ID")

#weights_filename을 지정할 수 있으며, 기본값은 "weights/best.pt"입니다
version = project.version(VERSION_ID)

#예시1 - 디렉터리 경로는 yolov8 모델의 경우 "training1/model1.pt"입니다
version.deploy("yolov8", "training1", "model1.pt")

#예시2 - 디렉터리 경로는 yolov8 모델의 경우 "training1/weights/best.pt"입니다
version.deploy("yolov8", "training1")
```

**중요 참고 사항**

{% hint style="info" %}
버전에는 여러 개의 업로드된 모델이 있을 수 있습니다. 다음을 참조하세요 [버전, 학습, 모델](https://docs.roboflow.com/models/ko/versions-trainings-and-models.md) 버전의 모델이 어떻게 지정되는지에 대해.
{% endhint %}

## CLI

CLI를 설치하려면 다음을 참조하세요 [CLI 설치 및 설정](https://docs.roboflow.com/reference/platform/cli/install-and-set-up-the-cli).

**인증**

CLI 명령을 사용하기 전에 Roboflow로 인증해야 합니다:

1. 인증 명령을 실행하세요: `roboflow login`
2. 터미널에 표시된 URL을 방문하세요: <https://app.roboflow.com/auth-cli>
3. 웹사이트에서 인증 토큰을 가져오세요
4. 터미널에 토큰을 붙여넣으세요

자격 증명은 자동으로 다음 위치에 저장됩니다 `~/.config/roboflow/config.json`

**모델 가중치 업로드**

Roboflow CLI는 학습된 모델 가중치를 Roboflow 프로젝트에 업로드하는 명령을 제공합니다. Roboflow에 사용자 지정 학습 모델을 배포하려는 경우 유용합니다.

**기본 사용법**

{% code overflow="wrap" %}

```bash
roboflow upload_model -w <workspace> -p <project> -t <model_type> -m <model_path> [-v <version>] [-f <filename>] [-n <model_name>]
```

{% endcode %}

**매개변수**

| 플래그                    | 필수  | 설명                                                  |
| ---------------------- | --- | --------------------------------------------------- |
| `-w, --workspace`      | 아니요 | 작업 공간 ID 또는 URL. 기본값은 기본 작업 공간입니다.                  |
| `-p, --project`        | 예   | 업로드할 프로젝트 ID. 버전 없는 모델을 여러 프로젝트에 업로드하려면 플래그를 반복하세요. |
| `-t, --model_type`     | 예   | 모델 유형, 예: `yolov8`, `paligemma2`, `rfdetr-medium`.  |
| `-m, --model_path`     | 예   | 학습된 모델 파일이 들어 있는 디렉터리의 경로.                          |
| `-v, --version_number` | 아니요 | 모델을 연결할 데이터셋 버전.                                    |
| `-f, --filename`       | 아니요 | 모델 파일 이름. 기본값은 `weights/best.pt`.                   |
| `-n, --model_name`     | 조건부 | 모델 이름. 버전 없는 모델 배포에 필요합니다.                          |

**예시**

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash"># 1. 특정 버전에 모델 업로드: 
<strong>roboflow upload_model -w my-workspace -p my-project -v 1 -t yolov8 -m ./weights
</strong>
# 2. 버전 없는 모델을 여러 프로젝트에 업로드:
roboflow upload_model -w my-workspace -p project1 -p project2 -t yolov11 -n my-model-v1 -m ./weights
# 3. 버전 없는 RF-DETR medium 모델을 단일 프로젝트에 업로드: 
roboflow upload_model -w my-workspace -p my-project -t rfdetr-medium -n my-model-name -m ./ -f weights.pt
</code></pre>

## 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>models_upload_custom_weights</code></td><td>로컬에서 학습한 가중치를 Roboflow에 업로드하는 방법을 확인하세요.</td></tr></tbody></table>

## 다음 단계

1. Roboflow의 "Models" 탭에서 모델을 확인하세요
2. 다음을 사용해 로컬에서 모델을 실행하세요 [Roboflow Inference Server](https://docs.roboflow.com/deployment/self-hosted/self-hosted).
3. 다음을 검토하세요 [배포 옵션](https://docs.roboflow.com/deployment).
