레이블링 엔진 CLI, REST API, MCP 도구, SDK

potato label, /api/engine/v1 REST 경로, 엔진 MCP 도구 다섯 개, Python Study 클래스로 레이블링 엔진을 구동합니다. 모두 하나의 engine.sqlite 파일을 통해 동작합니다.

주석 서버, 명령줄, REST API, MCP 도구, Python SDK는 모두 작업 디렉터리의 같은 engine.sqlite 파일을 통해 같은 레이블링 엔진을 구동합니다. 명령줄에서 연구를 시작하고, 서버로 사람에게 요청을 제공하고, 노트북에서 인증할 수 있습니다.

한 번에 하나의 프로세스만 연구를 구동합니다. 실행 중인 서버의 플래너가 연구의 쓰기 잠금을 쥐고 있으며, 그동안 potato label run, potato label certify, Study.run()은 실행을 거부하고 그 이유를 알려 줍니다. 이때는 POST /api/engine/v1/certify나 관리자 페이지를 이용해 서버를 통해 인증하세요. 이 잠금이 있는 이유는 구동 주체가 둘이면 보정 표본을 두 개 뽑고 서로의 레이블에 대해 인증하게 되기 때문입니다. 잠금은 잠금을 쥔 프로세스가 종료되면 풀립니다. 같은 컴퓨터에서 강제 종료된 프로세스의 잠금은 즉시 넘겨받고, 다른 컴퓨터에 있는 프로세스의 잠금은 하트비트 없이 2분이 지나면 넘겨받습니다. 읽기 전용 명령(status, certificate, calls, export)은 언제든 동작합니다.

명령줄

모든 엔진 명령은 연구의 설정 파일을 받습니다.

bash

potato label <command> <config.yaml> [options]

명령 아홉 개가 첫 모델 호출부터 데이터셋 내보내기까지 연구 전체를 다룹니다.

명령	동작
`run`	캐스케이드로 모든 항목에 레이블을 달고, 블라인드 보정 표본을 뽑고, 인증하고, 해소합니다. `--until predicted`(기본값)는 한 번 실행한 뒤 멈추고, `--until met`은 모든 계약이 충족되거나 엔진이 사람을 기다리게 될 때까지 계속합니다. `--max-items N`, `--budget-usd X`(이번 실행에 한해 `budgets.model_usd`를 덮어씀), `--max-ticks N`(기본 20), `--json`도 받습니다. 강제 종료된 실행은 모델 호출을 반복하지 않고 멈춘 곳에서 재개됩니다. 소스의 마지막 실행이 실패했거나 소스가 낸 모든 답이 오류였을 때, 또는 계약이 지정한 스키마에 어떤 소스도 레이블을 달 수 없을 때 해당 소스를 알려 주며 상태 1로 종료합니다.
`status`	항목, 예측, 용도별 요청, 계약, 지출, 아직 레이블이 없는 항목, 그리고 오류가 있거나 실행이 실패 또는 일시 중지된 소스마다 한 줄씩 표시합니다. `--json`.
`certify`	새 cert 레이블과 새 예측으로 모든 계약을 검정합니다. dev 레이블만 바뀐 경우에는 저장된 결과가 메모와 함께 돌아오며, `--retest`를 쓰면 이제 dev가 고르는 규칙을 다음 회차에서 검정합니다(검정 회차 참고). `--json`.
`certificate`	품질 인증서입니다. `--format md`(기본값), `html` 또는 `json`, 그리고 `--out FILE`.
`export`	출처 정보가 붙은 레이블, 인증서(JSON, Markdown, HTML), 데이터셋 카드, 호출 로그를 `--out DIR`(기본값 `<output_annotation_dir>/labeling_engine`)에 씁니다.
`calls`	모델 호출 감사 로그를 JSON lines로 출력합니다. `--out FILE`.
`distill`	지금까지의 레이블로 모델을 학습시켜 캐스케이드 맨 앞에 둡니다.
`optimize`	캐스케이드의 모든 부분집합을 dev 레이블로 채점하고, 커버리지를 유지하는 가장 저렴한 조합을 보고합니다. 커버리지를 조금이라도 유지하는 부분집합이 없으면 아무것도 추천하지 않습니다. `--prompts N`을 쓰면 LLM 단계에 프롬프트를 N가지로 바꿔 쓰게 하고 각각을 dev 항목에서 채점합니다. 이것은 모델 호출이므로 기록되고 예산에 포함되며 각자의 소스 버전 아래에 저장되고, 현재 프롬프트는 저장된 예측으로 채점합니다. 캐스케이드와 인증서는 바뀌지 않습니다.
`migrate-config`	이전 AI 키에 해당하는 `labeling_engine` 블록을 넣은 설정 사본을 작성합니다. `--out FILE`. 레이블링 엔진으로 이전하기를 참고하세요.

진행 상황을 확인하는 데는 아무것도 소모되지 않습니다. status, certificate, 관리자 페이지는 저장된 결과를 읽기 때문입니다. 새 레이블에 대한 certify든 certify --retest든, 새 검정은 매번 계약의 오류 예산 일부를 소모합니다.

export가 기록하는 파일

potato label export는 출력 디렉터리에 네 종류의 파일을 씁니다.

파일	내용
`labels.jsonl`, `labels.csv`	레이블 여부와 관계없이 항목과 스키마마다 한 행이며, `id`, `schema`, `label`, `label_origin`(`auto`, `human`, `adjudicated`, ...), `status`(`accepted`, `threshold_legacy`에서의 `accepted_uncertified`, `pending`, `pending_recert`), `source`, `model`, `source_version`, `confidence`, `contract_version`, `request_ids`가 들어갑니다. 수락된 뒤 소스가 바뀐 기계 레이블은 다음 실행에서 다시 인증될 때까지 `pending_recert`로 표시됩니다.
`certificate.json`, `.md`, `.html`	인증서입니다.
`README.md`	인증서로 만든, Hugging Face 프런트매터가 있는 데이터셋 카드입니다.
`model_calls.jsonl`	모든 모델 호출과 함께 모델, 프롬프트와 답의 해시, 토큰, 지연 시간, 비용, 캐시 적중, 가리기 범주를 기록합니다.

일반 내보내기 도구(python -m potato.export와 관리자 내보내기)는 사람의 주석을 내보내며, 내보내기 형식 페이지에 그 목록이 있습니다. 그중 labeling_engine 형식은 potato label export와 같은 파일을 쓰며, 엔진이 켜져 있지 않으면 실행을 거부합니다. 엔진이 켜져 있으면 CSV, Parquet, Hugging Face 내보내기에 각 주석이 어떤 엔진 요청에 대한 답이었는지 알려 주는 열 두 개가 추가됩니다. engine_purpose에는 용도(예: calibration)가, engine_request에는 용도, 포함 확률, 표시 여부, 분할, 요청 id를 담은 JSON이 들어갑니다. 이 열로 블라인드 무작위 표본과 검증 답을 구분하세요.

REST API

모든 엔진 경로는 /api/engine/v1 아래에 있으며 JSON을 반환합니다. X-API-Key 헤더에 관리자 키를 넣거나 관리자 세션으로 인증하세요. 읽기에는 관리자 대시보드 권한이, certify와 plan에는 할당 관리 권한이, 인증서에는 내보내기 권한이 필요합니다.

메서드와 경로	반환
`GET /status`	항목, 예측, 요청, 호출 합계, 예산, 그리고 각 스키마의 캐스케이드, 계약, 해소된 레이블 수
`GET /schemes/<name>/contracts`	스키마의 각 계약에 대한 최신 결과. 캐스케이드가 바뀌었으면 `stale`로 표시
`GET /schemes/<name>/risk_coverage`	마지막 단계의 각 임계값에 대해 cert 레이블 기준 수락 비율, 관측 오류, 보장된 상한
`GET /schemes/<name>/reliability`	보정 레이블 기준 단계별 신뢰도 구간, ECE, Brier 점수
`GET /schemes/<name>/drift`	선택적 위험 계약별 감사 모니터
`GET /schemes/<name>/optimize`	dev 레이블로 채점한 더 저렴한 캐스케이드 보고서
`GET /requests`	용도와 상태별 요청 수와 요청 목록. 필터는 `purpose`, `status`(매개변수를 반복하거나 값을 쉼표로 구분), `schema`, `limit`(최대 1000)
`GET /calls`	최신순 호출 로그와 소스별 합계. `limit`(최대 500), `offset`
`GET /certificate`	인증서. `format=json`(기본값), `md` 또는 `html`이며, `save=1`을 쓰면 저장도 함
`GET /crowd`	플래너의 마지막 크라우드 계획. 실제 지출이 켜져 있지 않으면 시험 실행
`POST /certify`	지금 모든 계약을 검정. `?retest=1`(또는 `{"retest": true}`)을 쓰면 dev 레이블만 바뀐 규칙도 검정
`POST /plan`	지금 플래너를 한 번 실행

연구에서 엔진이 꺼져 있으면 경로는 404로 응답합니다. 숫자가 아닌 limit, 알 수 없는 purpose나 status, json, md, html이 아닌 format처럼 유효하지 않은 매개변수에는 JSON 오류와 함께 400으로 응답합니다.

예를 들어, 다음 요청은 포트 8000의 서버에서 현재 인증서를 Markdown으로 가져옵니다.

bash

curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

MCP 도구

MCP 서버는 REST 경로와 같은 권한으로 엔진 도구 다섯 개를 제공합니다.

engine_status
engine_requests
플래너를 한 번 실행하는 engine_run
retest를 받는 engine_certify
json, md 또는 html 형식의 engine_certificate

엔진이 꺼져 있는데 이 도구를 허용하면 검증 경고가 납니다. potato mcp connect를 통해 거부된 호출(권한 없음, 잘못된 매개변수)은 서버의 메시지를 담은 도구 오류로 돌아옵니다. 도구를 허용하고 클라이언트를 연결하는 방법은 MCP 서버 문서에서 다룹니다.

Python SDK

Study 클래스는 예를 들어 노트북에서 Python으로 엔진을 구동합니다.

python

from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

각 메서드는 명령이나 경로 하나에 대응합니다.

메서드	동작
`Study(config_path)`	설정과 항목을 불러옵니다
`run(until="predicted", max_ticks=20)`	`potato label run`과 같으며, 쓰기 잠금을 가져갑니다
`label(item_id, scheme, value, user, request_id=None)`	사람의 레이블을 기록합니다. `request_id`를 닫거나, 없으면 이 사람이 그 항목에서 맡고 있는 요청을 닫으며, 그 밖의 경우에는 자연 발생 레이블로 보관되고 이 레이블은 인증에 쓰이지 않습니다. 같은 사람이 같은 항목에 두 번째 레이블을 달면 첫 레이블이 갱신됩니다
`status()`	`GET /status`와 같습니다
`requests(status=None, purpose=None, ...)`	요청 대장입니다
`certify(retest=False)`	`potato label certify`와 같습니다
`certificate(fmt="json")`	`json`, `md` 또는 `html`
`export(out_dir)`	`potato label export`와 같습니다

이 예제는 호출 방법을 보여 주려고 열린 모든 요청에 "positive"를 달 뿐입니다. Study.label로 기록했지만 어떤 요청에도 답하지 않는 레이블은 자연 발생 레이블로 보관되고, 자연 발생 레이블은 인증에 쓰이지 않습니다. 따라서 엔진이 요청하지 않은 항목에 레이블을 다는 스크립트는 어떤 계약도 읽지 않는 레이블을 보탤 뿐입니다.

더 읽어보기

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