콘텐츠로 이동

🏭 프로젝트 · 라벨링

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 수정 ✏️ 쓰기(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 task 분류용 프로젝트 태그 관리 ✏️ 쓰기(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 로 조회합니다.

create_project

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

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

update_project

프로젝트의 title/description 을 수정합니다.

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

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, 페이지네이션(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로 먼저 확인합니다. 서버에 클래스 필터가 없어 bulk-fetch 로 청크 스캔하는 방식이라, 한 호출당 스캔 상한이 있고 다 못 찾으면 cursor 로 다음 호출을 이어가라고 정직하게 안내합니다.

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

manage_project_tags

🏭 Workforce. task 를 분류하는 프로젝트 태그(TaskTag) 를 조회/생성/수정/삭제합니다 (action=list|create|update|delete).

검수 반려 사유 태그와 혼동 주의

manage_review_tags는 검수 반려 사유 전용 태그로, 대상이 다릅니다. 이 도구는 task 분류용 태그입니다.

불변식: 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_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