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

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

관련 페이지:

* Roboflow에서 모델을 학습하려면 다음을 참조하세요 [모델 학습](/roboflow/roboflow-ko/train/train.md)
* 모델 weights를 다운로드하려면 다음을 참조하세요 [Model Weight 다운로드](/roboflow/roboflow-ko/deploy/download-roboflow-model-weights.md)

## Roboflow 외부에서 학습한 weights 업로드

사용자 지정 모델 학습을 완료한 후, 모델 weights를 다시 Roboflow project에 업로드하여 다음의 이점을 활용하세요 [Roboflow Inference](https://inference.roboflow.com/).

### 모델 지원

다음을 참조하세요: [Supported Models 표](/roboflow/roboflow-ko/deploy/supported-models.md) weights 업로드 호환성에 대한 자세한 내용은.

{% hint style="warning" %}

* YOLOv8 모델은 다음에서 학습해야 합니다: `ultralytics==8.0.196`
* YOLOv9 모델은 다음을 사용하여 학습 및 업로드해야 합니다: `ultralytics` 에서 <https://github.com/WongKinYiu/yolov9>
* YOLOv10 모델은 다음을 사용하여 학습 및 업로드해야 합니다: `ultralytics` 에서

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

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

### Versioned vs. Versionless 모델 업로드

Roboflow는 project에 모델을 배포하는 두 가지 서로 다른 방식을 제공하며, 각 방식은 서로 다른 사용 사례와 조직의 요구를 충족합니다. versioned 배포와 versionless 배포 중 선택은 dataset version과 함께 모델의 변화를 추적해야 하는지, 아니면 workspace의 여러 project 간에 모델을 공유하고 싶은지에 따라 달라집니다.

* **Versionless 배포**
  * workspace 수준에 연결됨
  * 여러 project에 동시에 배포할 수 있음
  * 동일한 workspace 내의 서로 다른 project 간에 모델을 공유하는 데 이상적임
* **Versioned 배포**
  * 특정 project version에 연결됨
  * dataset version당 모델 1개
  * dataset version과 함께 모델의 변화를 추적하는 데 이상적임
  * Label Assist에서 모델을 사용하는 데 이상적임
  * 다른 모델을 학습할 때 checkpoint로 모델을 사용하는 데 이상적임

### 사용자 지정 weights 업로드

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

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

{% tabs %}
{% tab title="Python SDK (Versionless)" %}
versionless 사용자 지정 weights를 업로드하려면 다음을 사용하세요: `workspace.deploy_model()` 메서드:

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

**매개변수**

* model\_type (str): 배포되는 모델의 유형(예: "yolov8", "yolov11")
* model\_path (str): 모델 weights가 포함된 디렉터리의 파일 경로
* project\_ids (list\[str]): 모델을 배포할 project ID 목록
* model\_name (str): 모델을 식별하기 위한 이름 - (최소 1개의 문자를 포함해야 하며, 숫자와 하이픈을 허용함)
* filename (str, optional): weights 파일 이름(기본값은 "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"
)
```

{% endtab %}

{% tab title="Python SDK (Versioned)" %}
{% hint style="info" %}
하나의 versioned 모델은 반드시 하나의 해당 dataset version에만 연결되어야 합니다. dataset에 생성된 version이 없다면, 다음에서 생성할 수 있습니다: [앱 내에서](/roboflow/roboflow-ko/datasets/dataset-versions/create-a-dataset-version.md) 또는 다음을 통해 [API](/developer/python-sdk/create-a-dataset-version.md).

다음 문서를 참조하세요: [API를 통해 version을 불러오는 방법](/developer/rest-api/versions/view-a-version.md) 또는 아래 예시를 참조하세요.
{% endhint %}

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

**사용량**

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

**매개변수**

* model\_type (str): 배포할 모델의 유형(예: "yolov8", "yolov11")
* model\_path (str): 모델 weights가 포함된 디렉터리의 파일 경로
* filename (str, optional): weights 파일 이름(기본값은 "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")
```

**중요 참고 사항**

1. 하나의 version에는 한 번에 하나의 학습된 모델만 있을 수 있습니다
2. 이미 모델이 있는 version에 업로드를 시도하면 429 오류가 발생합니다
   {% endtab %}

{% tab title="CLI (Versionless 및 versioned)" %}
**인증**

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

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

인증 정보는 자동으로 다음 위치에 저장됩니다: `~/.config/roboflow/config.json`

**모델 weights 업로드**

Roboflow CLI는 학습된 모델 weights를 Roboflow project에 업로드하는 명령을 제공합니다. 이는 사용자 지정으로 학습한 모델을 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`: workspace ID 또는 URL(선택 사항 - 지정하지 않으면 기본 workspace를 사용함)
* `-p, --project`: 모델을 업로드할 project ID( versionless 업로드의 경우 여러 project에 대해 여러 번 지정할 수 있음)
* `-t, --model_type`: 모델 유형(예: yolov8, paligemma2)
* `-m, --model_path`: 학습된 모델 파일이 포함된 디렉터리의 경로
* `-v, --version_number`: 모델을 업로드할 version 번호(선택 사항)
* `-f, --filename`: 모델 파일 이름(기본값: "weights/best.pt")
* `-n, --model_name`: 모델 이름(versionless 모델 배포 시 필수)

**예시**

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

{% endtab %}
{% endtabs %}

## 다음 단계

1. Roboflow의 "Models" 탭에서 모델을 확인하세요
2. 다음을 사용해 로컬에서 모델을 실행하세요: [Roboflow Inference Server](https://inference.roboflow.com/).
3. [모델을 배포하세요](/roboflow/roboflow-ko/deploy/deployment-overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/roboflow/roboflow-ko/deploy/upload-custom-weights.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.