콘텐츠로 이동

🏭 프로젝트 · 라벨링

Workforce 척추의 중간 구간입니다: 프로젝트(라벨링 규칙) → 태스크(작업 단위) → 라벨링 내용. "어노테이션 프로젝트를 만들고 싶다", "이 프로젝트에 어떤 클래스가 있나", "이 태스크는 라벨링이 어떻게 됐나", "특정 클래스를 쓴 태스크를 찾아 달라" 같은 요청이 모두 이 페이지의 도구로 흘러갑니다. 데이터를 올리는 앞 구간은 데이터 준비, 사람을 배치해 제출·검수하는 뒷 구간은 워크샵 · 할당 · 검수를 보세요.

flowchart LR
    A[데이터유닛<br/>data-preparation.md] --> B["프로젝트<br/>(라벨링 규칙)"]
    B --> C["태스크<br/>(프로젝트×데이터유닛)"]
    C --> D[라벨링 내용]
    D --> E[할당·검수<br/>workshops-review.md]
    style B fill:#e8f0fe,stroke:#4285f4,color:#202124
    style C fill:#e8f0fe,stroke:#4285f4,color:#202124
    style D fill:#e8f0fe,stroke:#4285f4,color:#202124

불변식 — 미리 알아야 할 것

  • 프로젝트의 어노테이터 종류(annotator_type)와 작업당 최대 할당 수(max_assignments_per_task)는 생성 시에만 정할 수 있습니다.
  • 프로젝트에 작업(Task)이 1개라도 생기면 컬렉션을 바꿀 수 없습니다.
  • 컬렉션의 데이터 종류(category)는 생성 후 불변이며, 프로젝트·어노테이터·라벨링 유형·스키마까지 사슬로 전파됩니다.
  • 작업 태그·할당작업 태그(TaskTag)의 category 는 생성 후 변경 불가입니다 (manage_project_tags).

두 종류의 "보는 도구" — T2 렌즈 vs T3 워크플로

이 페이지에는 성격이 다른 조회 도구가 섞여 있습니다.

  • 🔍 T2 콘텐츠 렌즈 — 한 대상의 내용을 들여다보는 도구. get_labeling_schema는 프로젝트의 라벨링 규칙(클래스→속성→옵션 트리)을, get_task_data는 태스크 1건의 어노테이션 내용을 요약해 보여줍니다.
  • 🔗 T3 여정 워크플로 — 여러 대상을 가로질러 찾아가는 도구. find_tasks_by_class는 렌즈로 확인한 클래스 코드를 들고 프로젝트에서 "그 클래스를 쓴 태스크"를 모아 줍니다.

즉 전형적인 여정은 스키마 렌즈로 클래스 코드 확인 → 워크플로로 태스크 탐색 → 태스크 데이터 렌즈로 내용 확인 순입니다.

도구 한눈에

도구 무엇을 할 때 쓰기 여부
list_projects 프로젝트 찾기·둘러보기 읽기
get_project 프로젝트 1건 설정·상태 확인 읽기
create_project 새 프로젝트 생성 ✏️ 쓰기(confirm)
update_project 프로젝트 title/description·LLM 검수 설정 수정 ✏️ 쓰기(confirm)
delete_project 프로젝트 삭제 ⚠️ 파괴적(confirm)
get_annotation_configurations 프로젝트 configuration 작성 규칙 조회 읽기
get_labeling_schema 라벨링 스키마(클래스 트리) 확인 — 🔍 T2 렌즈 읽기
list_tasks 태스크 목록 조회 읽기
get_task 태스크 1건 상세 읽기
get_task_data 태스크의 라벨링 내용 요약 — 🔍 T2 렌즈 읽기
find_tasks_by_class 클래스 코드로 태스크 탐색 — 🔗 T3 워크플로 읽기
manage_project_tags 작업 태그·할당작업 태그(TaskTag) 정의 관리 ✏️ 쓰기(confirm)
manage_tag_attachments 작업·할당작업 여러 건에 태그 붙이기/떼기 ✏️ 쓰기(confirm)
annotate_task_data 태스크 어노테이션 저장/제출 ⚠️ 파괴적(confirm)

도구 상세

list_projects

프로젝트(어노테이션 작업의 상위 단위) 목록을 봅니다. 프로젝트를 찾거나 둘러볼 때 가장 먼저 부릅니다. name 인자는 현재 페이지 안에서만 부분일치로 거르는 것이고 서버 검색이 아닙니다 — 매칭이 없으면 cursor 로 다음 페이지를 계속 조회해야 합니다.

  • 주요 인자: category (audio·image·pcd·prompt·text·time_series·video), is_archived, name (페이지 내 부분일치), 페이지네이션(cursor/per_page)
  • 함께 보기: 상세는 get_project

get_project

프로젝트 1건의 설정·상태를 확인합니다. list_projects에서 얻은 id 로 조회합니다.

  • 주요 인자: id
  • 표시: 진행 설정과 함께 LLM 검수 설정(llm_review_enabled·llm_review_prompt)도 보입니다.
  • 함께 보기: 라벨링 규칙의 내용은 get_labeling_schema

create_project

프로젝트를 생성합니다. title 과 category(image·video·audio·text·pcd)만 고르면 되고, 클래스·속성 등 세부 설정(configuration)은 생략했다가 나중에 채울 수 있습니다.

  • 주요 인자: title, category, data_collection (작업을 만들 컬렉션 id), description, configuration (생략 가능), llm_review_enabled·llm_review_prompt (LLM 검수)
  • ⚠️ data_collection 은 생성 시에만 지정할 수 있습니다 — update_project 로는 못 바꿉니다. 이 프로젝트로 작업(태스크)을 만들 계획이면 반드시 함께 넘기세요. 프로젝트와 데이터유닛의 컬렉션이 다르면 create_tasks_from_units 가 400 으로 거부합니다.
  • 안전장치: 기본 dry-run 미리보기(검증만, 미생성) → confirm=true 재호출 시 실제 생성
  • 함께 보기: configuration JSON 작성 규칙은 get_annotation_configurations · 이후 수정은 update_project

update_project

프로젝트의 title/description 과 LLM 검수 설정을 수정합니다. 지정한 값만 바뀝니다.

  • 주요 인자: id, name (제목), description, llm_review_enabled, llm_review_prompt
  • 안전장치: 기본 dry-run 미리보기(검증만, 미변경) → confirm=true 재호출 시 실제 수정

LLM 검수 설정

할당작업이 제출(submit)될 때 LLM 이 결과를 자동 점검하게 할 수 있습니다.

  • 켜는 조건: llm_review_enabled=true 와 점검 기준을 적은 llm_review_prompt(최대 8000자)가 둘 다 있어야 실행됩니다.
  • 우선순위: 워크샵에 값이 있으면 프로젝트 값보다 우선합니다(manage_workshop).
  • LLM 연결 필요: 프로젝트에 LLM 연결이 없으면 검수는 건너뜁니다. 연결(API 키 등)은 MCP 가 다루지 않으며 웹 UI 에서 설정합니다.
  • 결과 보기: get_assignment_llm_reviews — 참고용이며 작업 상태를 바꾸지 않습니다.

delete_project

프로젝트를 삭제합니다. 파괴적 작업이므로 미리보기로 대상을 확인한 뒤 진행하세요.

  • 주요 인자: id, name
  • 안전장치: 기본 dry-run 미리보기(검증만, 미삭제) → confirm=true 재호출 시 실제 삭제

get_annotation_configurations

🔗 공용 도구. create_project로 프로젝트를 만들 때 configuration JSON 을 구성하는 데 필요한 카테고리별 annotation type·widget type·검증 규칙을 조회합니다. 인자 없이 부르면 전체 카테고리를 응답합니다.

get_labeling_schema

🔍 T2 콘텐츠 렌즈. 프로젝트의 라벨링 스키마 — 클래스→속성→옵션 트리 — 를 조회합니다. "이 프로젝트에 OO 클래스가 있나" 처럼 프로젝트 라벨링 규칙의 내용을 확인할 때 부릅니다. 여기서 확인한 클래스 code 가 find_tasks_by_class와 get_task_data의 코드 해석에 쓰입니다.

  • 주요 인자: project_id
  • 함께 보기: 클래스 코드로 태스크를 찾는 여정은 find_tasks_by_class

list_tasks

태스크(프로젝트×데이터유닛 단위 작업) 목록을 봅니다.

  • 주요 인자: project (프로젝트 ID), is_discarded, has_data, classes (작업 데이터의 클래스 code, 콤마 구분·하나라도 포함), 페이지네이션(cursor/per_page)
  • 함께 보기: 상세는 get_task · 내용 요약은 get_task_data

get_task

태스크 1건 상세를 봅니다. list_tasks에서 얻은 id 로 조회합니다.

  • 주요 인자: id

get_task_data

🔍 T2 콘텐츠 렌즈. 태스크의 어노테이션 내용을 클래스 코드 히스토그램 + 항목 표로 요약합니다 (geometry 좌표는 항상 생략). "라벨링이 됐는지 / 어떻게 됐는지" 확인할 때 부릅니다. mode='detail' 이면 속성값까지 포함합니다.

  • 주요 인자: task_id, mode (summary 기본 | detail)
  • 함께 보기: 클래스 코드→이름 매핑이 필요하면 get_labeling_schema

find_tasks_by_class

🔗 T3 여정 워크플로. 프로젝트 안에서 특정 라벨링 클래스를 사용한 태스크를 찾습니다. 클래스 code 는 get_labeling_schema로 먼저 확인합니다. 찾는 방식(method)은 두 가지입니다.

method 방식 장점 한계
filter (기본) 서버 클래스 필터(작업 데이터 기준) 빠르고 대용량 프로젝트에서도 동작 서버가 클래스 정보를 아직 계산하지 않은 태스크는 빠짐 · 매칭 항목 수 없음
scan 데이터가 있는 태스크만 골라 직접 청크 스캔 태스크별 매칭 항목 수 · 서버 계산 여부와 무관 한 호출당 스캔 상한(이어서 cursor) · 큰 데이터는 스캔 불가

결과가 예상보다 적으면 method='scan' 으로 교차 확인하세요. cursor 는 같은 method 로만 이어 씁니다.

scan 에서 데이터가 너무 크거나 원본을 읽을 수 없는 태스크는 "매칭 없음"으로 세지 않고 스캔 불가로 따로 표시합니다(태스크 id·사유 포함). 크기 한도 초과 태스크는 get_task_data로 하나씩 확인할 수 있고, 원본 유실·손상 태스크는 개별 조회도 실패하므로 운영팀 확인이 필요합니다.

  • 주요 인자: project_id, class_code, limit (기본 50), cursor (이어서 조회), method (filter·scan)
  • 함께 보기: 찾은 태스크의 내용 확인은 get_task_data · 이미 정답셋(GT)이 된 항목을 클래스로 찾을 땐 서버 필터 기반인 list_ground_truths (별개 대상)

manage_project_tags

🏭 Workforce. 작업 태그·할당작업 태그(TaskTag) 정의를 조회/생성/수정/삭제합니다 (action=list|create|update|delete). 같은 TaskTag 가 작업(Task)에 붙으면 작업 태그, 할당작업(Assignment)에 붙으면 할당작업 태그라고 부릅니다.

검수 태그와 혼동 주의

manage_review_tags는 검수 태그(ReviewTag) 전용으로, 대상이 다릅니다. 이 도구는 작업 태그·할당작업 태그(TaskTag)를 정의합니다.

불변식: category 는 생성 후 변경 불가 — update 에 category 를 전달하면 API 호출 없이 거부 안내를 반환합니다(name/description/meta 만 수정 가능).

  • 주요 인자: project_id, action, tag_id (update/delete 대상), name, category (export|project, 생성 시), description, meta, 페이지네이션(cursor/per_page)
  • 안전장치: 기본 dry-run 미리보기(검증만, 미적용) → confirm=true 재호출 시 실제 적용
  • 함께 보기: 정의한 태그를 붙이고 떼기는 manage_tag_attachments · manage_review_tags (검수 태그 — 별개 대상)

manage_tag_attachments

🏭 Workforce. manage_project_tags로 정의한 TaskTag 를 여러 건에 한꺼번에 붙이거나 뗍니다 (action=attach|detach). target=task 면 작업 태그, target=assignment 면 할당작업 태그입니다. 붙이기는 기존 태그에 추가하며(교체 아님), 떼기는 지정한 태그만 제거합니다.

대상 조건 필수 — 프로젝트 전체 적용 방지

조건 없이 호출하면 API 호출 없이 거부합니다.

  • target=assignment: ids(예: "1,2,10-20")·filters·search 중 하나 이상.
  • target=task: ids(작업 id, 예: "3,10-20")·has_data·is_discarded·schema 중 하나 이상. 작업 경로는 filters/search 를 지원하지 않아 거부합니다 — 조건식·검색이 필요하면 target=assignment 를 쓰세요.
  • 주요 인자: project_id, target, action, tag_ids (붙이거나 뗄 TaskTag id 목록), 대상 조건(위)
  • 안전장치: 기본 dry-run 미리보기 → confirm=true 재호출 시 실제 적용. 할당작업은 미리보기에 대상·변경 예정·이미 반영·거절 건수가 나오고, 작업은 백엔드가 건수를 주지 않아 대상 범위(지정한 작업 id 또는 필터에 맞는 모든 작업)를 안내합니다.
  • 실행 결과: 비동기 작업으로 등록되며 job_id 를 돌려줍니다 — 진행은 get_async_job으로 확인합니다.
  • 권한: 프로젝트 변경 권한(매니저) 필요. 할당작업 경로의 선택 오류(다른 프로젝트의 할당작업 혼입·대상 없음)는 서버 메시지와 함께 점검 항목을 안내합니다.
  • 예시: "프로젝트 12의 반려된 할당작업 중 3, 5, 9번에 '재검토' 태그 붙여줘" → target=assignment, action=attach, ids="3,5,9"
  • 함께 보기: 태그 정의는 manage_project_tags · 검수 태그는 manage_review_tags

annotate_task_data

🏭 Workforce. 태스크의 어노테이션 데이터(data)를 저장하거나 제출합니다(action=save|submit).

라벨링 산출물을 덮어씁니다

기존 라벨링 산출물을 덮어쓰며 되돌리기 어렵습니다. 반드시 미리보기로 확인 후 진행하세요.

상태전환(승인/반려)은 이 도구와 무관합니다 — 할당작업의 제출/승인/반려는 submit_assignment · approve_assignment · reject_assignment 를 쓰세요.

  • 주요 인자: task_id, data (어노테이션 payload), action (save 기본 | submit)
  • 안전장치: 기본 dry-run 미리보기(검증만, 미변경) → confirm=true 재호출 시 실제 저장/제출
  • 함께 보기: 현재 내용 확인은 get_task_data · 할당작업 데이터 정정은 update_assignment_data