> 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/annotate/annotate/ai-labeling/auto-label.md). # 자동 라벨 ## 소개 {% hint style="info" %} Auto Label은 여러 기능 중 하나입니다 [AI 라벨링](/datasets/ko/annotate/annotate/ai-labeling.md) 기능입니다. 이 기능을 사용하면 [크레딧](https://docs.roboflow.com/platform/billing-and-plans/credits) 다음에 명시된 요율로 [크레딧 페이지](https://roboflow.com/credits). {% endhint %} Roboflow Auto Label을 사용하면 기반 비전 모델(SAM 3 또는 Gemini), Roboflow에서 학습한 모델, 또는 저장된 [워크플로](https://docs.roboflow.com/workflows) 를 사용해 이미지를 자동 라벨링할 수 있습니다. Roboflow Auto Label은 다음 소스를 사용해 지정한 객체를 식별할 수 있습니다: * SAM 3 - 텍스트 프롬프트로 객체에 라벨을 지정하는 기반 모델(객체 탐지 및 분할) * Gemini (Boxes) - Gemini 3.7 Flash는 나열한 클래스에 대해 바운딩 박스를 그립니다(객체 탐지만 지원) * Roboflow에서 학습한 모델([https://github.com/roboflow/docs/tree/main/models/README.md](https://github.com/roboflow/docs/tree/main/models/README.md "mention")) * 참고: 현재는 Annotation Batch와 동일한 데이터셋의 모델만 지원됩니다. * 저장된 [워크플로](https://docs.roboflow.com/workflows) 프로젝트 유형과 호환되는 Auto Label은 컴퓨터 비전 모델 학습에 사용할 수 있도록 수백만 장의 이미지를 라벨링하는 데 사용되어 왔습니다. 직접 보유한 하드웨어에서 자동 라벨링하고 싶다면 Roboflow는 또한 [Autodistill](https://github.com/autodistill/autodistill)를 유지 관리하고 있으며, 이는 다양한 기반 모델을 사용해 이미지 데이터셋을 자동 라벨링하는 오픈 소스 프레임워크입니다. ### Roboflow Auto Label을 사용할 때 차량(예: 지게차), 사람, 일반적인 결함(예: 균열), 일반적인 제품(예: 바이닐 레코드, 빵)과 같은 일반 객체에 주석을 달아야 한다면 Roboflow Auto Label을 사용해야 합니다. 객체의 특정 변형을 식별해야 한다면 SAM 3와 같은 기반 모델을 사용해서는 안 됩니다. 예를 들어 Auto Label은 서로 다른 종류의 균열을 구분하거나 전자제품의 고유한 결함을 식별할 수 없습니다. ## Roboflow Auto Label로 데이터에 라벨 지정 Roboflow 플랫폼을 사용하면 전체 배치에 대해 작업을 실행하기 전에 Auto Label이 데이터셋의 데이터 클래스에 대해 얼마나 잘 라벨링할지 미리 볼 수 있습니다. 라벨링 후에는 품질 보증을 위해 결과를 검토하고(권장) 라벨링된 데이터셋으로 모델을 학습할 수 있습니다. ### 1단계: 데이터 업로드 먼저 Roboflow에 데이터를 업로드하세요. 자세한 내용은 [이미지, 비디오 및 주석 업로드](/datasets/ko/create-and-upload/adding-data.md) 설명을 참조하세요.

이미지를 Roboflow에 업로드하기.

### 2단계: Auto Label로 이동 모든 이미지를 업로드하면 이미지를 어떻게 라벨링할지 묻는 메시지가 표시됩니다. "Auto-Label And Review"를 선택하세요.

Roboflow Auto Label 인터페이스를 열려면 "Auto-Label And Review"를 선택하세요.

### 3단계: Auto Label 구성 Auto Label 라벨링 인터페이스가 나타나며, 여기서 자동 라벨링 작업을 구성할 수 있습니다. #### 클래스(& 설명) 클래스는 이미지의 객체에 할당할 라벨을 나타냅니다. 설명은 기반 모델(SAM 3)이 해당 클래스의 인스턴스를 식별하는 데 사용하는 클래스의 시각적 설명을 나타냅니다. 기본적으로 설명은 클래스 이름이 됩니다. Gemini (Boxes)는 클래스 이름만 읽으므로 설명은 영향을 주지 않습니다. Auto Label은 명확한 시각적 설명이 있는 일반 객체를 라벨링할 때 가장 잘 작동합니다. 예를 들어 Auto Label은 생산 라인에서 알루미늄 캔의 위치를 식별할 수 있습니다. 하지만 Auto Label은 알루미늄 캔의 브랜드를 구분하는 것처럼 특정 요구 사항에 따라 이미지를 라벨링할 수는 없습니다. #### 테스트 결과 생성 Auto Label을 구성한 후 "테스트 결과 생성"을 클릭하여 데이터셋의 작은 하위 집합에서 클래스를 테스트하세요. 기본적으로 4개의 이미지가 선택됩니다.

Auto Label 인터페이스.

### 4단계: Roboflow Auto Label 라벨 평가 예시 이미지에서 "aluminum can" 클래스를 사용할 때의 테스트 결과는 다음과 같습니다. 여기에서 다음을 할 수 있습니다:

Auto Label이 알루미늄 캔에 주석을 달고 있습니다.

#### 클래스 및 설명 조정 Auto Label이 예상대로 이미지를 라벨링하지 않으면 클래스에 대해 다른 설명을 테스트해 보세요. {% hint style="info" %} 모든 테스트 결과는 무료이며 크레딧을 사용하지 않습니다. {% endhint %} #### 신뢰도 조정 각 클래스 오른쪽의 숫자는 (이 클래스의 표시된 박스 수) / (이 클래스의 전체 박스 수)로 표시됩니다. 신뢰도 임계값을 조정하여 박스를 더 많이 또는 더 적게 걸러낼 수 있습니다. 신뢰도가 높을수록 표시되는 박스 수는 줄어듭니다. {% hint style="info" %} 여기서 설정한 신뢰도 임계값은 전체 배치를 라벨링할 때도 동일하게 사용되므로, 올바르게 설정되었는지 확인하세요! {% endhint %} Gemini (Boxes)는 모든 박스를 전체 신뢰도로 반환하므로 설정할 임계값이 없습니다. 이를 선택하면 슬라이더와 미리보기 라벨의 신뢰도 값이 숨겨집니다. #### 다른 이미지에서 테스트 배치의 다른 이미지에서 Auto Label의 성능을 검토하려면 왼쪽 아래의 "Test images" 섹션에서 이미지를 클릭하세요. 추가 버튼을 누르지 않아도 해당 이미지의 미리보기가 즉시 로드됩니다. ## 워크플로로 라벨링 기반 모델이나 학습된 모델 대신 저장된 [워크플로](https://docs.roboflow.com/workflows)를 사용해 SAHI, 모델 앙상블, 다단계 사용자 지정 로직으로 배치를 라벨링할 수 있습니다. Auto Label 모델 드롭다운에서 "Workflows" 탭을 열고 워크플로를 선택하세요. 프로젝트 유형(detection, segmentation, classification)과 호환되는 워크플로만 표시됩니다. 워크플로를 선택한 후, 해당 출력 클래스 각각을 프로젝트의 클래스에 매핑하고 클래스별 신뢰도 임계값을 설정하세요. 샘플 이미지에서 미리보기가 실행되므로 작업을 시작하기 전에 매핑을 확인할 수 있습니다. {% hint style="info" %} 매핑한 클래스만 적용됩니다. 매핑이 없는 출력 클래스는 제외되므로, 프로젝트에 다시 기록하려는 모든 클래스를 매핑하세요. {% endhint %} 매핑이 올바르면 "Auto Label With This Workflow"를 클릭하여 작업을 시작하세요. 작업은 백그라운드에서 실행되며 매핑된 라벨을 배치에 적용합니다. ### 배치에서 Auto Label 실행 Auto Label이 예상대로 이미지를 라벨링하면 "Auto Label with This Model"을 클릭하세요. 요약 모달을 검토한 후 진행을 클릭하세요. 천 장의 이미지를 라벨링하는 데 몇 분 정도 걸립니다. 작업이 시작되면 Annotate 페이지로 이동하며, 새 Auto Label 작업이 다른 주석 작업과 함께 나열됩니다. Auto Label은 백그라운드에서 실행되므로 완료되면 그곳에서 결과를 검토할 수 있습니다. ## 기존 주석 배치의 이미지에 이미 주석이 달려 있으면 요약 모달에서 Auto Label이 이를 어떻게 처리할지 묻습니다. 작업은 다음 옵션 중 하나를 선택하기 전까지 시작되지 않습니다: * "Keep Existing Annotations"는 각 이미지에 이미 있는 주석 옆에 Auto Label 예측을 추가합니다. * "Replace Existing Annotations"는 기존 주석을 삭제하고 Auto Label 예측만 저장합니다. ## HTTP API REST API를 사용하여 프로그래밍 방식으로 자동 라벨링 작업을 시작하고 추적할 수 있습니다. Auto Label은 기반 모델(SAM 3) 또는 직접 학습한 Roboflow 모델을 사용해 배치의 이미지를 자동으로 주석 처리합니다. 이 엔드포인트에는 [범위가 지정된 API 키](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) 와 `annotationJob.create` 및 `annotationJob.read` 스코프가 각각 필요합니다. ### Auto Label 작업 만들기 자동 라벨 작업을 시작하려면 POST 요청을 보내세요: ```bash curl --location --request POST 'https://api.roboflow.com/${WORKSPACE}/${PROJECT}/autolabel?api_key=${ROBOFLOW_API_KEY}' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "batchId": "", "modelType": "sam3", "ontology": {"a dog": "dog", "a cat": "cat"} }' ``` 다음도 생략할 수 있습니다 `ontology` 를 생략하여 API가 모델 또는 데이터셋 클래스에서 이를 도출하도록 할 수 있습니다: ```bash curl --location --request POST 'https://api.roboflow.com/${WORKSPACE}/${PROJECT}/autolabel?api_key=${ROBOFLOW_API_KEY}' \\ --header 'Content-Type: application/json' \\ --data-raw '{ "batchId": "", "modelType": "sam3" }' ``` #### 요청 본문 | 매개변수 | 유형 | 필수 | 설명 | | ----------------------------- | -------- | --- | ----------------------------------------------------------------------------------------------- | | `batchId` | string | 예 | 라벨링할 이미지 배치의 ID입니다. | | `modelType` | string | 예 | 사용할 모델. 다음 중 하나: `sam3`, `custom_roboflow`. | | `ontology` | 객체 또는 배열 | 아니요 | 프롬프트를 클래스 이름에 매핑합니다. 아래 형식을 참조하세요. 생략하면 자동으로 파생됩니다(참조 [온톨로지 자동 파생](#ontology-auto-derivation)). | | `numImagesToLabel` | number | 아니요 | 라벨링할 이미지 수입니다. 기본값은 전체 배치입니다. | | `defaultConfidence` | number | 아니요 | 모든 클래스에 적용되는 신뢰도 임계값(0\~1). | | `confidenceThresholds` | 객체 | 아니요 | 클래스별 신뢰도 임계값, 예: `{"dog": 0.5, "cat": 0.7}`. | | `reviewerEmail` | string | 아니요 | 검토자로 지정할 워크스페이스 구성원의 이메일입니다. 기본값은 워크스페이스 소유자입니다. | | `runNMS` | 불리언 | 아니요 | 비최대 억제를 실행할지 여부입니다. 기본값은 `true`. | | `modelOptions` | 객체 | 아니요 | 추가 모델별 옵션(예: `{"modelId": "your-model/1"}` 다음에 대해 `custom_roboflow`). | | `preserveExistingAnnotations` | 불리언 | 아니요 | 이미지에 이미 있는 주석을 유지하고 Auto Label 결과를 추가합니다. 기본값은 `false`이며, 이 경우 기존 주석을 대체합니다. | #### 온톨로지 형식 이 `ontology` 필드는 여러 형식을 허용합니다. 모두 내부적으로 정규화됩니다. **객체(표준)** - 키는 프롬프트, 값은 클래스 이름입니다: ```json {"a dog": "dog", "a cat": "cat"} ``` **문자열 배열** - 각 문자열은 프롬프트와 클래스 이름 모두로 사용됩니다: ```json ["dog", "cat"] ``` **객체 배열:** ```json [{"class": "dog", "prompt": "a dog"}, {"class": "cat", "prompt": "a cat"}] ``` #### 온톨로지 자동 파생 경우 `ontology` 가 생략되었거나(또는 비어 있으면), API는 다음을 기반으로 자동으로 파생하려고 시도합니다: `modelType`: | 모델 유형 | 파생 소스 | | ----------------- | --------------------------------------------------- | | `custom_roboflow` | 다음에 지정된 모델의 학습된 클래스를 사용합니다: `modelOptions.modelId`. | | `sam3` | 데이터셋에 정의된 클래스 이름을 사용합니다. | 데이터셋에 잠긴 주석 클래스가 있으면, 파생된 온톨로지는 허용된 클래스와 교집합을 이루므로 잘못된 주석이 생성되지 않습니다. 요청은 다음과 같은 `400` 오류로 실패합니다. 예를 들어 데이터셋에 클래스가 없거나 모델 클래스가 데이터셋의 잠금 클래스와 겹치지 않을 때 온톨로지를 파생할 수 없는 경우입니다. 가능한 `errorType` 값: * `MISSING_MODEL_ID` - `modelOptions.modelId` 는 다음에 필요합니다 `custom_roboflow` 온톨로지가 제공되지 않을 때. * `MODEL_CLASSES_UNAVAILABLE` - 지정된 모델에 클래스가 없습니다. * `NO_MATCHING_CLASSES` - 모델의 클래스가 데이터셋의 잠금 클래스와 겹치지 않습니다. * `DATASET_HAS_NO_CLASSES` - 데이터셋에 정의된 클래스가 없습니다( `sam3`). #### 응답 ```json { "jobId": "auto-label-job-uuid", "annotationJobId": "annotation-job-uuid", "message": "자동 라벨링 작업이 생성되었습니다" } ``` ### Auto Label 작업 상태 가져오기 자동 라벨 작업의 진행 상황을 확인하려면 GET 요청을 보내세요: ```bash curl 'https://api.roboflow.com/${WORKSPACE}/autolabel/jobs/${JOB_ID}?api_key=${ROBOFLOW_API_KEY}' ``` 다음 `jobId` 를 사용하세요. #### 응답 ```json { "id": "auto-label-job-uuid", "status": "pending", "modelType": "sam3", "projectType": "object-detection", "projectId": "project-id", "annotationJobId": "annotation-job-uuid", "numImages": 100, "numImagesSentBack": 0, "subjobs": [ {"id": "subjob-1", "status": "pending"}, {"id": "subjob-2", "status": "done"} ], "ontology": {"a dog": "dog"}, "confidenceThresholds": {"dog": 0.5}, "startTime": "2026-01-01T00:00:00.000Z" } ``` ## MCP 서버 AI 에이전트를 [MCP 서버](https://docs.roboflow.com/agents/mcp-server) 에 연결하면 다음 도구를 사용해 이미지 배치를 자동 라벨링할 수 있습니다:
도구설명
autolabel_start호스팅된 자동 라벨 작업을 이미지 배치에 대해 시작합니다.
autolabel_job_get자동 라벨 작업의 하위 작업별 상태와 진행 상황을 가져옵니다.