> 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/deployment/ko/monitoring-and-analytics/active-learning.md).

# 능동 학습

검토와 재학습을 통해 모델을 지속적으로 개선하기 위해 운영 추론 데이터를 수집합니다.

## 개요

Active Learning은 배포된 모델의 프로덕션 데이터를 수집하고, 검토 및 재학습을 위해 제공합니다. 모델이 프로덕션에서 추론을 실행하면 Active Learning은 사용자가 설정한 규칙(예: 신뢰도가 낮은 예측 또는 특정 클래스)에 따라 이미지를 자동으로 샘플링하고 사람의 검토를 위해 대기열에 추가합니다.

{% hint style="info" %}
Active Learning을 사용하려면 클라우드 배포가 필요합니다. Annotation Review 기능이 포함된 요금제에서 사용할 수 있습니다.
{% endhint %}

## 웹 앱

### Active Learning 사용 설정

1. 프로젝트를 열고 왼쪽 사이드바에서 "Active Learning"을 선택합니다.
2. Active Learning을 켭니다.

Active Learning이 데이터를 수집하려면 프로젝트에 학습된 모델과 활성 상태의 클라우드 배포가 있어야 합니다.

### 수집 규칙 구성

Active Learning에는 수집 한도와 조건, 두 가지 설정 범주가 있습니다.

#### 수집 한도

Active Learning이 수집하는 데이터의 양을 제어합니다.

* 샘플링 비율: 샘플링할 추론의 비율(예: 0.5%)
* 분당, 시간당, 일일 이미지 한도
* 압축 수준 및 이미지 최대 크기
* 배치 재생성 빈도(매일, 매주, 매월 또는 사용 안 함)
* 수집된 이미지와 함께 모델 예측을 저장할지 여부

이 설정을 수정하려면 수집 한도 섹션에서 "편집"을 클릭하고 구성 모달에서 값을 업데이트합니다.

#### 조건

조건은 수집할 이미지를 필터링합니다. 모델 유형에 따라 규칙을 정의할 수 있습니다.

* 신뢰도 임계값(예: 신뢰도가 60% 미만인 이미지 수집)
* 관심 있는 특정 클래스
* 탐지 수 요구 사항

조건을 설정하려면 조건 섹션에서 "편집"을 클릭합니다.

### Agent에서 Active Learning 관리

Active Learning은 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent)에서도 관리할 수 있습니다. 프로젝트 탭을 열고 "설정"을 선택한 다음, 이 페이지와 동일한 토글, 수집 한도 및 조건 설정을 사용합니다. 이를 위해서는 Manage Workflows, Publish Workflows 및 Dataset Active Learning 권한이 필요합니다.

### 수집된 이미지 검토

Active Learning이 이미지를 수집하면 Active Learning 페이지의 이미지 섹션에 표시됩니다. 이 페이지에는 검토 대기 중인 이미지 수와 현재 검토 중인 이미지 수가 표시됩니다.

검토를 시작하려면:

1. "이미지 검토"를 클릭해 검토 대기열을 엽니다.
2. 상태(시작 안 함, 진행 중)별로 배치를 살펴보고 생성 날짜, 이미지 수 또는 진행률을 기준으로 정렬합니다.
3. 배치를 선택해 검토를 시작합니다.

### 검토자 할당

팀원에게 검토 작업을 분배할 수 있습니다.

1. 검토 대기열을 열고 배치를 선택합니다.
2. 검토자를 할당하려면 클릭합니다.
3. 팀원을 선택하고 할당할 이미지 수를 설정한 다음, 선택적으로 검토 지침을 추가합니다.
4. "이미지 섞기"를 켜면 각 검토자에게 배정되는 이미지가 무작위로 선택됩니다.

이미지가 할당되면 검토자에게 알림이 전송됩니다. 언제든지 다른 검토자에게 이미지를 재할당할 수 있습니다.

### 학습 루프에서 Active Learning이 작동하는 방식

일반적인 워크플로:

1. 모델을 학습시키고 배포합니다.
2. 사용 사례에 맞게 조정한 조건으로 Active Learning을 사용 설정합니다.
3. 조건에 부합하는 프로덕션 데이터가 수집되어 대기열에 추가됩니다.
4. 검토자가 수집된 이미지에 라벨을 지정합니다.
5. 검토가 완료된 이미지를 데이터셋에 추가하고 재학습하여 모델을 개선합니다.

이렇게 하면 모델이 가장 어려워하는 사례에서 성능을 개선하는 피드백 루프가 만들어집니다.

## HTTP API

HTTP API를 사용해 Active Learning을 켜거나 끄고, 수집 규칙을 업데이트하고, 검토 대기열의 이미지를 나열할 수 있습니다. Active Learning은 프로젝트의 기본 워크플로 내에서 실행되므로, 변경할 때마다 해당 워크플로의 새 버전이 저장 및 배포됩니다.

### Active Learning 구성 가져오기

{% openapi src="/files/1a7d950b29db6bfc296d4f3735a06b7f1a5e3eea" path="/{workspace}/{project}/deploy/active-learning" method="get" %}
[active-learning.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1d8110bcfbedf0930aefd5d2cfc4571776e13736%2Factive-learning.yaml?alt=media)
{% endopenapi %}

### Active Learning 사용 설정

프로젝트에 모델이 설정되어 있지 않으면 서비스가 먼저 모델을 선택합니다.

{% openapi src="/files/1a7d950b29db6bfc296d4f3735a06b7f1a5e3eea" path="/{workspace}/{project}/deploy/active-learning/enable" method="post" %}
[active-learning.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1d8110bcfbedf0930aefd5d2cfc4571776e13736%2Factive-learning.yaml?alt=media)
{% endopenapi %}

### Active Learning 사용 중지

{% openapi src="/files/1a7d950b29db6bfc296d4f3735a06b7f1a5e3eea" path="/{workspace}/{project}/deploy/active-learning/disable" method="post" %}
[active-learning.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1d8110bcfbedf0930aefd5d2cfc4571776e13736%2Factive-learning.yaml?alt=media)
{% endopenapi %}

### Active Learning 구성 업데이트

새 프로젝트에서 구성하기 전에 Active Learning을 활성화하세요. 매번 전체 `collectionLimits` 객체를 전송하세요. 생략한 선택적 필드는 제거됩니다.

{% openapi src="/files/1a7d950b29db6bfc296d4f3735a06b7f1a5e3eea" path="/{workspace}/{project}/deploy/active-learning/configuration" method="post" %}
[active-learning.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1d8110bcfbedf0930aefd5d2cfc4571776e13736%2Factive-learning.yaml?alt=media)
{% endopenapi %}

### Active Learning 이미지 목록

{% openapi src="/files/1a7d950b29db6bfc296d4f3735a06b7f1a5e3eea" path="/{workspace}/{project}/deploy/active-learning/images" method="get" %}
[active-learning.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1d8110bcfbedf0930aefd5d2cfc4571776e13736%2Factive-learning.yaml?alt=media)
{% endopenapi %}

## Python SDK

`Workspace.active_learning()` 은 디렉터리의 모든 이미지에 대해 추론을 실행하고, 조건에 따라 이미지(및 예측 결과)를 대상 프로젝트에 업로드합니다. SDK에 기본 제공되는 Active Learning 루프로, 기존 모델이 라벨링할 가치가 있는 항목을 선별하도록 하여 원본 영상에서 라벨링 대기열을 구성할 수 있습니다.

같은 패턴은 프로덕션 환경에서 사용할 경우 [Workflow](https://docs.roboflow.com/workflows/manage/manage-workflows#python-sdk) 로 구현하는 것이 가장 좋지만, `active_learning()` 은 "프레임이 들어 있는 폴더"에서 "프로젝트에 입력할 라벨링된 데이터"까지 가장 빠르게 이어 주는 방법입니다.

### 기본 사용법

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
ws = rf.workspace()

ws.active_learning(
    raw_data_location="./frames",
    raw_data_extension=".jpg",
    inference_endpoint=["my-detector", 3],   # [project, version]
    upload_destination="my-detector",         # destination project
    conditionals={
        "required_class_variance_count": 1,           # at least 1 different class
        "minimum_size_requirement": 100,              # min pixels per detection
        "maximum_size_requirement": 4000000,
        "confidence_interval": [0, 60],               # only low-confidence predictions
    },
)
```

#### 매개변수

* `raw_data_location` (str) - 입력 이미지가 있는 디렉터리입니다.
* `raw_data_extension` (str) - 검색할 이미지 확장자입니다(예: `.jpg`, `.png`).
* `inference_endpoint` (list, `[project, version]`) - 선별 단계에서 실행할 모델입니다.
* `upload_destination` (str) - 조건을 충족하는 이미지와 예측 결과를 업로드할 프로젝트 ID입니다. 대개 모델이 속한 프로젝트와 같습니다.
* `conditionals` (dict) - 이미지 업로드 여부를 결정하는 규칙입니다. 자주 사용하는 키:
  * `confidence_interval` - `[min, max]`; 탐지 신뢰도가 이 범위에 해당하는 이미지만 전달합니다.
  * `required_class_variance_count` - 필요한 최소 고유 클래스 수입니다.
  * `minimum_size_requirement` / `maximum_size_requirement` - 탐지 영역의 픽셀 크기를 기준으로 필터링합니다.
  * `required_class_count` - 전체 탐지 수입니다.
* `use_localhost` (bool, 기본값 `False`) - `True`, 호스팅된 추론 대신 자체 호스팅 [Roboflow Inference](https://docs.roboflow.com/deployment/ko/self-hosted/self-hosted.md) 서버에 요청합니다.
* `local_server` (str) - 로컬 추론 서버의 기본 URL입니다. 기본값은 `http://localhost:9001/`.

### 사용 이유

일반적인 작업 흐름:

1. 소량의 라벨링된 데이터로 v1 모델을 학습합니다.
2. 다음과 같이 `active_learning()` 을 라벨이 없는 프로덕션 데이터 폴더에 지정합니다.
3. 모델의 확신도가 낮거나 희귀 클래스를 감지한 이미지만 전달합니다.
4. Roboflow 웹 앱에서 해당 이미지에 라벨을 지정합니다.
5. 새 예시를 추가해 v2를 생성하고 다시 학습합니다.

조건 설정 `conditionals` 을 사용하면 "모든 항목 업로드"를 실제 분류 정책으로 바꿀 수 있습니다.

### 대규모 파이프라인

입력이 동영상 스트림이거나 모델이 Workflow 뒤에서 실행되거나 일괄 처리 및 재시도가 필요한 경우, 이에 해당하는 구성을 [Workflow](https://docs.roboflow.com/workflows/manage/manage-workflows#python-sdk). `로 구축하세요.` active\_learning()

## MCP 서버

AI 에이전트를 [MCP Server](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>project_deployment_enable_active_learning</code></td><td>프로젝트 배포에 액티브 러닝을 사용하도록 설정합니다.</td></tr><tr><td><code>project_deployment_configure_active_learning</code></td><td>배포에서 액티브 러닝 데이터를 수집하는 방식을 설정합니다.</td></tr><tr><td><code>project_deployment_disable_active_learning</code></td><td>액티브 러닝 데이터 수집을 일시 중지합니다.</td></tr><tr><td><code>project_deployment_list_review_queues</code></td><td>프로덕션 추론 결과가 쌓이는 검토 대기열을 나열합니다.</td></tr></tbody></table>
