레이블링 엔진 설정

레이블링 엔진이 하는 모든 일은 labeling_engine 블록 하나에서 설정합니다. 블록이 유효하지 않으면 서버가 시작 단계에서 멈추고 모든 문제를 한꺼번에 나열합니다. 주석자에게 엔진의 요청을 제공하려면 assignment_strategy: engine도 설정하세요. 엔진을 켜지 않은 채 이 전략을 설정하면 검증 오류가 납니다.

블록은 다음 섹션으로 이루어지며, 각 섹션은 아래에서 다룹니다.

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  schemas: [sentiment]            # default: every scheme a source can label
  sources: []
  cascade: [laya, gemma]          # default: the first source alone
  contracts: []
  humans: {}
  crowd: {}
  budgets: {}
  runtime: {}
  features: {}
  redaction: {}
  distill: {}

최상위 키

labeling_engine 바로 아래에는 키 다섯 개가 있습니다.

소스

소스는 각 항목에 대해 레이블과 신뢰도를 제안하는 모델 또는 기존 레이블 집합입니다. 모든 소스에는 고유한 id와 kind가 있으며, 소스에 알 수 없는 키가 있으면 오류입니다.

답을 바꿀 수 있는 모든 것(모델, 프롬프트, temperature, 옵션)은 소스의 버전 해시에 들어갑니다. 새 버전이 생기면 그 소스에 의존하는 모든 계약이 stale이 됩니다.

스키마가 가질 수 없는 값인 답, 예를 들어 목록에 없는 레이블, 숫자가 아닌 숫자 필드, N개 중 하나 선택 스키마에 대한 목록은 오류로 기록되며 레이블로는 절대 기록되지 않습니다. 실행 메시지는 이런 오류의 수를 셉니다. 호출이 실패한 항목은 이후 실행에서 소스 버전당 최대 세 번까지 다시 요청되며, 그 뒤에는 소스가 바뀔 때까지 기다립니다(키나 프롬프트를 고치면 새 버전이 됩니다). 한 소스가 실패한 실행에서도 다른 단계는 멈추지 않습니다. 다음 단계가 모든 항목에 레이블을 달고, potato label run은 상태 1로 종료하며 실패한 소스를 알려 줍니다.

신뢰도 방식

엔진의 수락 규칙은 각 예측의 신뢰도에 임계값을 적용하므로, 소스가 신뢰도를 어떻게 산출하는지가 엔진이 얼마나 수락할 수 있는지를 결정합니다. confidence.method는 다섯 가지 값 중 하나를 받습니다.

종류별 옵션

다섯 가지 소스 종류는 각자의 옵션을 읽습니다.

• **decision**은 프로세스 내 Laya, 또는 호스팅된 Jev나 OpenJev 같은 모든 /v1/systemone 서버를 다룹니다. 순전파 한 번으로 모든 선택지의 확률을 돌려주며, radio, select, likert, slider 스키마에서 동작합니다. endpoint_type은 laya 또는 systemone이어야 하고, systemone에는 서버 루트인 base_url이 필요합니다(/v1/systemone으로 끝나는 URL도 받아들입니다). 두 경우 모두 상태는 {"text": ...}로 전송되므로 하나의 체크포인트가 프로세스 안에서든 laya-serve 뒤에서든 같은 답을 내며, options: {state_key: ""}를 쓰면 대신 문자열만 그대로 보냅니다. 평가 척도(likert, slider)에서는 Laya의 점수가 척도를 거의 따라가지 못할 수 있으므로, 의존하기 전에 항목 몇 개를 확인하세요. 프로세스 내 laya 엔드포인트에는 pip install 'potato-annotation[decision]'이 필요합니다.
• **detector**는 image_annotation 스키마에서 객체 탐지기의 상자를 읽습니다. keep_threshold(0.35)는 상자가 예측에 포함되는 최소 점수를 정합니다. candidate_threshold(0.05)와 keep_threshold 사이의 상자는 이미지의 신뢰도를 낮춥니다. label_map은 탐지기의 클래스를 스키마 레이블에 대응시키며, 대응되지 않은 클래스는 무시됩니다. image_field는 이미지 경로나 URL이 있는 항목 필드를 지정합니다. 경로는 주석 페이지와 같은 방식으로 해석되어, /media/x.jpg는 작업의 media_directory 아래에서, 상대 경로는 task_dir 아래에서 찾습니다.
• **judge**는 rubric(기본값은 스키마의 설명), fields(판정자에게 보여 줄 항목 필드, 순서대로), 그리고 레이블 순서를 뒤집어 두 번 묻고 판정이 뒤바뀌면 기권으로 처리하는 swap_order를 받습니다. 에이전트 트레이스 스키마(process_reward, trajectory_eval, ...)에서는 판정자가 각 단계에 레이블을 답니다.
• **vlm**은 비전 엔드포인트(openai_vision, anthropic_vision, ollama_vision)를 씁니다. OpenAI 호환 서버 뒤에 있는 자체 호스팅 모델에는 openai_vision과 base_url을 쓰세요.
• **trained**는 artifact_dir, trainer(기본값 sklearn-text), run_id를 받습니다. 이 소스는 대개 직접 작성한 설정이 아니라 증류 과정에서 만들어집니다.

humans

humans 블록은 누가 레이블을 달고 엔진이 어떻게 표본을 뽑는지 정합니다.

crowd

crowd 블록은 humans.pools에 crowd가 있을 때 적용되며, 엔진이 구동할 수 있는 크라우드 플랫폼은 Prolific뿐입니다.

크라우드 모집은 기본적으로 시험 실행(dry run)이며, 플래너는 무엇을 할지 보고만 합니다. 실제로 돈을 쓰려면 features.crowd_live_spend: true와 budgets.human_usd 상한이 필요하며, 상한 없이 실제 지출을 켠 설정은 거부됩니다. Prolific 연구 자체를 설정하는 방법은 크라우드소싱에서 다룹니다.

budgets

budgets 블록은 한도를 넘기 전에 지출을 멈춥니다.

runtime

runtime 블록은 배치 처리, 동시성, 사람이 요청을 맡고 있을 수 있는 시간을 제어합니다.

features

drift를 제외한 모든 기능은 기본으로 꺼져 있습니다.

redaction

redaction.categories는 email, url, ip, card, ssn, phone, handle 중 무엇을 가릴지 나열하며, 기본값은 전부입니다. 가리기는 features.pii_redaction이 켜져 있을 때만, 그리고 제3자 API에만 적용됩니다. 자체 호스팅 엔드포인트 유형(vllm, ollama, laya, yolo, ...)은 어디서 실행되든 가리지 않으며, base_url이 같은 컴퓨터에 있는 엔드포인트도 가리지 않습니다.

distill

features.distill을 켜면 엔진은 연구의 레이블로 저렴한 모델을 학습시켜 캐스케이드 맨 앞에 둡니다.

cert 분할과 감사 분할의 항목은 절대 학습 세트에 들어가지 않으므로, 증류 모델은 자신이 학습한 레이블로 검정받는 일이 없습니다.

검증

potato validate config.yaml은 설정의 나머지 부분과 함께 labeling_engine 블록을 검사하며, 각 오류는 해당 키를 짚습니다. 예를 들면 labeling_engine.sources[1].kind must be one of ... 또는 labeling_engine.contracts[0].error is required for selective_risk와 같습니다. 검증은 다음도 거부합니다.

• 해당 계약 종류가 읽지 않는 계약 키(예: error의 오타)
• 어떤 캐스케이드 소스도 레이블을 달 수 없는 스키마에 대한 계약(각 소스의 이유와 함께)
• 엔진이 채점할 수 없는 스키마(자유 텍스트, 쌍대 비교)에 대한 계약
• endpoint_type이 의사결정 모델이 아닌 decision 소스, 그리고 endpoint_type이 의사결정 모델인 llm, vlm, judge 소스
• humans.overlap_k가 3보다 작은 no_worse_than_human

검증은 또한 기계의 답이 모두 맞더라도 budgets.human_labels가 너무 작아 selective_risk 계약을 인증할 수 없을 때 경고합니다. 그 경고가 사라질 때까지 예산을 늘리거나 error를 완화하세요.

더 읽어보기

• 레이블링 엔진
• 레이블링 엔진 계약
• 명령줄, REST API, MCP 도구, SDK
• 소스가 Potato의 나머지 부분과 공유하는 엔드포인트 유형을 다루는 AI 지원

구현에 관한 자세한 내용은 소스 문서를 참고하세요.