🏭 프로젝트 · 라벨링¶

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 로 조회합니다.

주요 인자: id
함께 보기: 라벨링 규칙의 내용은 get_labeling_schema

`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·검증 규칙을 조회합니다. 인자 없이 부르면 전체 카테고리를 응답합니다.

주요 인자: 없음
함께 보기: create_project

`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

🏭 프로젝트 · 라벨링¶

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

도구 한눈에¶

도구 상세¶

list_projects¶

get_project¶

create_project¶

update_project¶

delete_project¶

get_annotation_configurations¶

get_labeling_schema¶

list_tasks¶

get_task¶

get_task_data¶

find_tasks_by_class¶

manage_project_tags¶

annotate_task_data¶