🧠 학습데이터(정답셋)¶

라벨링(Workforce)과 모델 만들기(ML), 두 축이 봉합되는 지점이 이 카테고리입니다. 완료확정된 할당작업이 학습에 적격한지(qualifiesForTraining) 게이트를 통과시키고, 적격한 라벨을 정답셋(GT)에 모아 학습데이터 버전으로 얼리는 여정을 다룹니다. "라벨링 끝난 데이터를 학습으로 넘기고 싶다", "정답셋에 뭐가 들어있는지 보고 싶다"면 이 페이지입니다.

flowchart LR
    A["🏭 완료확정 할당작업<br/>(Workforce)"] --> B{{"check_training_eligibility<br/>게이트"}}
    B -->|적격| C["🧠 정답셋(GT)"]
    C --> D["학습데이터 버전<br/>(불변 스냅샷)"]
    B -->|부적격| X["GT 에 넣지 않음"]
    style B fill:#f9e79f,stroke:#b7950b,color:#000

불변식 — 미리 알아야 할 것

정답셋(GT)은 버전으로만 운영되며 직접 삭제할 수 없습니다. 버전 저장은 그 시점 구성을 불변으로 얼립니다(leakage 방지·재현 앵커). 기본 bump=Minor, split 8:1:1.
학습은 실험 목적과 연결된 학습데이터 버전만 쓸 수 있고, 학습 완료분만 모델로 등록됩니다 → 실험·모델·추론.
할당작업은 완료확정 후 수정 불가이며, 완료확정과 불량확정은 동시에 될 수 없습니다(상호배타).
데이터유닛을 삭제하면 파생된 작업·할당작업·정답데이터에 접근할 수 없습니다 — 원천 데이터 관리는 데이터 준비 참조.

qualifiesForTraining — 학습 적격 조건 4항

라벨 데이터를 학습으로 넘기려면 다음을 모두 만족해야 합니다.

완료확정(is_confirmed) 이고
불량 아님 이고
보류 아님 이고
(검수를 사용하는 워크샵이면) 검수완료

미충족 데이터는 정답셋(GT)에 넣지 마세요. check_training_eligibility 가 이 조건을 항별로 평가합니다.

도구 한눈에¶

도구	무엇을 할 때	쓰기 여부
`check_training_eligibility`	할당작업이 학습에 적격한지 항별 평가	읽기
`list_ground_truth_datasets`	정답셋(컨테이너) 목록 조회	읽기
`get_ground_truth_dataset`	정답셋 1건 상세 조회	읽기
`create_ground_truth_dataset`	정답셋 생성	✏️ 쓰기(confirm)
`update_ground_truth_dataset`	정답셋 이름/설명 수정	✏️ 쓰기(confirm)
`delete_ground_truth_dataset`	정답셋 삭제	⚠️ 파괴적(confirm)
`list_ground_truths`	정답셋 개별 항목 목록 (클래스 서버 필터)	읽기
`get_ground_truth`	정답셋 항목 1건 상세 조회	읽기
`list_ground_truth_versions`	학습데이터 버전 목록 조회	읽기
`create_ground_truths`	정답셋 채우기 — 프로젝트 작업 결과 또는 다른 정답셋의 버전에서 GT 생성	✏️ 쓰기(confirm)
`update_ground_truths`	정답셋 GT 데이터 새로고침 · train/validation/test 재분배	✏️ 쓰기(confirm)

도구 상세¶

`check_training_eligibility`¶

🧠 ML 이음매 — 두 축의 봉합 게이트입니다. 할당작업이 학습에 적격한지(qualifiesForTraining)를 완료확정 · 불량아님 · 보류아님 · (검수 활성 워크샵이면) 검수완료 네 항목으로 나눠 평가합니다. 완료확정된 라벨을 정답셋(GT)에 넣기 전에 게이트로 호출하세요.

주요 인자: assignment_id (평가할 할당작업 ID — 할당작업 목록에서 확인).
주의: 불량확정 여부는 v2 API 로 확인할 수 없어 조건부로 판정합니다.
함께 보기: 할당작업의 상태·완료확정은 워크샵·검수 · 통과 후 담을 그릇은 create_ground_truth_dataset.

`list_ground_truth_datasets`¶

정답셋(GT 데이터셋, 평가 기준 데이터)의 컨테이너 목록을 조회합니다. 어떤 정답셋이 있는지 찾거나 둘러볼 때 호출하세요. 개별 항목(라벨 하나하나)은 list_ground_truths 로 봅니다.

주요 인자: project (프로젝트 ID 로 좁히기) · 페이지네이션(cursor/per_page).
함께 보기: 상세는 get_ground_truth_dataset, 버전은 list_ground_truth_versions.

`get_ground_truth_dataset`¶

정답셋 1건의 상세를 확인합니다. list_ground_truth_datasets 에서 얻은 id 로 조회하세요.

주요 인자: id (정답셋 ID).

`create_ground_truth_dataset`¶

정답셋(GT 데이터셋)을 새로 만듭니다. 완료확정된 라벨(check_training_eligibility 게이트 통과분)을 담을 컨테이너가 필요할 때 호출하세요.

주요 인자: name (이름) · description (설명, 선택).
안전장치: 기본은 dry-run 미리보기(검증만, 미생성) → confirm=true 로 다시 호출해야 실제 생성.

`update_ground_truth_dataset`¶

정답셋의 name/description 을 수정합니다. 이름이나 설명을 정리하고 싶을 때 호출하세요.

주요 인자: id (정답셋 ID) · name · description.
안전장치: 기본은 dry-run 미리보기(검증만, 미변경) → confirm=true 로 다시 호출해야 실제 수정.

`delete_ground_truth_dataset`¶

정답셋을 삭제합니다. 더 이상 쓰지 않는 정답셋 컨테이너를 정리할 때만 신중히 호출하세요.

주요 인자: id (정답셋 ID) · name.
안전장치: 기본은 dry-run 미리보기(검증만, 미삭제) → confirm=true 로 다시 호출해야 실제 삭제.

`list_ground_truths`¶

🧠 정답셋(GT)의 개별 항목 목록입니다. classes 인자로 클래스 코드 기준 GT 검색이 가능하며, 이는 서버 필터라서 스캔 없이 바로 좁혀집니다. "OO 클래스가 들어간 정답 데이터를 찾고 싶다"면 이 도구입니다.

클래스로 찾기 — 대상이 무엇인가요?

정답셋(GT) 항목을 클래스로 찾기 → 이 도구의 classes 서버 필터 (빠름).
아직 GT 가 아닌 라벨링 task 를 클래스로 찾기 → find_tasks_by_class (별개 대상).

주요 인자: ground_truth_dataset (정답셋 ID) · task (작업 ID) · classes (클래스 코드 배열, 서버 필터) · category (train/validation/test) · 페이지네이션(cursor/per_page).
함께 보기: 컨테이너(정답셋 자체) 목록은 list_ground_truth_datasets · 항목 상세는 get_ground_truth.

`get_ground_truth`¶

🧠 정답셋 항목 1건의 상세를 확인합니다. list_ground_truths 에서 얻은 id 로 조회하며, classes 와 data(라벨 payload)를 포함합니다 — 긴 값은 절단 요약됩니다.

주요 인자: ground_truth_id (정답셋 항목 ID).

`list_ground_truth_versions`¶

🧠 정답셋(GT 데이터셋)의 학습데이터 버전(GTDV) 목록입니다. "이 정답셋에 어떤 버전이 있는지" 확인할 때 호출하세요. 버전은 그 시점 구성을 불변으로 얼린 스냅샷이므로, 학습에 실제로 쓰이는 단위가 무엇인지 여기서 봅니다.

주요 인자: gt_dataset_id (정답셋 ID) · 페이지네이션(cursor/per_page).
주의: 버전 생성은 범위 밖 — 이 도구는 조회 전용입니다.
함께 보기: 버전을 소비하는 다음 단계(학습→모델)는 실험·모델·추론 · 모델이 어떤 버전에서 왔는지는 get_model_lineage.

`create_ground_truths`¶

🧠 정답셋을 채웁니다 — 원본의 결과로 GT 항목을 일괄 생성합니다. 빈 정답셋은 create_ground_truth_dataset으로 먼저 만듭니다.

source=project (project_id): 프로젝트 작업 결과 → GT. 원본 프로젝트가 정답셋과 연결돼 있어야 하며, 아니면 "선택한 정답 데이터셋과 호환되지 않는 원본 데이터" 오류가 납니다.
source=version (source_version_id): 다른 정답셋의 학습데이터 버전(스냅샷) 을 복사합니다. 버전 id 는 list_ground_truth_versions로 찾습니다.
중복 자동 제외: 이 정답셋에 이미 들어 있는 데이터유닛은 백엔드가 빼고 추가합니다.

기본 필터 — 라벨 있는 작업 · 불량 아닌 작업

source=project 는 기본으로 has_data=true(라벨 있는 작업)·is_discarded=false(불량 아닌 작업)만 고릅니다. 값을 바꾸거나 null 로 해제하거나 schema 를 더해 원하는 조합으로 만들 수 있습니다. 세 필터를 모두 해제하면 프로젝트 전체가 대상이 되므로 거부합니다. 특정 작업만 넣으려면 task_ids(예: "11,20-25")를 함께 주세요 — 다른 프로젝트의 작업이 섞이면 백엔드가 거부합니다. 학습에 넣기 전 check_training_eligibility로 적격 여부를 먼저 확인하세요.

주요 인자: gt_dataset_id, source, project_id 또는 source_version_id, has_data·is_discarded·schema·task_ids (project 전용)
안전장치: 기본 dry-run 검증(백엔드가 건수를 주지 않음) → confirm=true 재호출 시 비동기 작업으로 실행. 진행은 get_async_job으로 확인합니다.
권한: 원본 프로젝트(또는 정답셋)에 항목 추가 권한이 필요합니다.

`update_ground_truths`¶

🧠 정답셋에 이미 들어 있는 GT 를 일괄로 고칩니다. 대상은 gt_dataset_id 하나로 고정되며, categories (train·validation·test 중 여러 개)로 좁힐 수 있습니다.

action=refresh_data — 데이터 새로고침: 원본(original_type=project 또는 ground_truth_dataset_version, original_id)의 현재 결과로 GT 데이터를 다시 채웁니다. 원본은 같은 워크스페이스의 프로젝트/버전만 지정할 수 있습니다(다른 워크스페이스 id 는 "존재하지 않는 원본"으로 거부).
action=split_categories — 재분배: train·validation·test 비율(0~100 정수, 합 100)로 GT 를 다시 나눕니다. 합이 100이 아니면 API 호출 없이 거부합니다.

필요 권한 — 정답셋이 연결된 프로젝트의 변경 권한

백엔드가 미리보기(dry-run)보다 먼저 권한을 확인하므로, 권한이 없으면 confirm=false 단계에서도 "이 정답셋이 연결된 프로젝트의 변경 권한이 없습니다" 안내가 나옵니다. 프로젝트 매니저에게 권한을 요청하세요.

주요 인자: gt_dataset_id, action, categories, original_type·original_id (refresh_data), train·validation·test (split_categories)
안전장치: 기본 dry-run 검증 → confirm=true 재호출 시 비동기 작업으로 실행. 처리 건수·분배 결과는 작업 완료 후 get_async_job의 결과 데이터에서 확인합니다.

🧠 학습데이터(정답셋)¶

도구 한눈에¶

도구 상세¶

check_training_eligibility¶

list_ground_truth_datasets¶

get_ground_truth_dataset¶

create_ground_truth_dataset¶

update_ground_truth_dataset¶

delete_ground_truth_dataset¶

list_ground_truths¶

get_ground_truth¶

list_ground_truth_versions¶

create_ground_truths¶

update_ground_truths¶