From a530d2139fe34a51d37bb13fc133119ac6162db1 Mon Sep 17 00:00:00 2001 From: hbyang Date: Tue, 11 Aug 2026 09:05:48 +0900 Subject: [PATCH] =?UTF-8?q?AI=20=EC=9D=98=EC=8B=AC=EB=8F=84=20=EB=B0=B1?= =?UTF-8?q?=EB=B6=84=EC=9C=84=20=EC=BA=98=EB=A6=AC=EB=B8=8C=EB=A0=88?= =?UTF-8?q?=EC=9D=B4=EC=85=98=20(=ED=95=99=EC=8A=B5=C2=B7=EC=A7=80?= =?UTF-8?q?=ED=91=9C=20=EC=97=86=EC=9D=B4=20=EC=9A=B4=EC=98=81)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AI 생성 표본이 없어 정확도를 측정할 수 없는 상태에서, 규칙 기반 휴리스틱을 실제로 쓸 수 있게 만든다. 점수의 의미를 "AI일 확률"에서 "등록 코퍼스의 인간 저작물 대비 문체 이례도"로 재정의해, 라벨 없이도 참인 진술이 되도록 했다. 덤으로 high 배지 비율이 정의상 고정되어 검토 부하가 예측 가능해진다. - ai_detector: low_cut/high_cut 주입 지원. 둘 다 주어질 때만 적용하고, 적용되면 model_version 에 +corpus-percentile 을 붙여 컷 출처를 드러낸다. is_stub 은 여전히 true — 컷을 맞췄을 뿐 학습된 모델이 아니다. - calibrate_cuts/percentile/score_text_heuristic 순수 함수 추가. - scripts/calibrate_ai_detector_cuts.py: 코퍼스 표본의 점수 분포에서 백분위 컷을 산출하고 .env 두 줄을 출력한다. - 규칙 점수가 상단에서 clip 되어 p90=p98 이 되면 그 컷은 high 배지를 영원히 0건으로 만든다. 이 경우 .env 를 출력하지 않고 exit 3 으로 중단하며 saturated_share/distinct_scores 진단을 남긴다. 유효 표본 100건 미만은 exit 2. - kiwipiepy 유무가 점수를 바꾸므로 실제 사용 여부를 리포트에 기록하고 경고한다. 기본값은 그대로 비활성(AI_DETECTOR_ALLOW_HEURISTIC=false)이라 켜지 않으면 동작이 바뀌지 않는다. 컷 미설정 시에는 자리표시자임을 note 로 경고한다. 테스트 180건 통과 (신규 13건). Co-Authored-By: Claude Opus 5 (1M context) --- .env.example | 6 + app/core/config.py | 5 + app/engine/ai_detector.py | 104 ++++++++++++- app/engine/detector.py | 2 + docs/AI_DETECTION.md | 58 ++++++++ scripts/calibrate_ai_detector_cuts.py | 205 ++++++++++++++++++++++++++ tests/test_ai_detector.py | 144 ++++++++++++++++++ 7 files changed, 517 insertions(+), 7 deletions(-) create mode 100644 scripts/calibrate_ai_detector_cuts.py diff --git a/.env.example b/.env.example index cd522ff..6710943 100644 --- a/.env.example +++ b/.env.example @@ -30,7 +30,13 @@ PERSISTENT_MIN_COVERAGE=0.30 PERSISTENT_RERANK_TOP_K=20 PRECEDENTS_PATH=./data/precedents/precedents.jsonl AI_DETECTOR_MODEL_PATH=./data/models/ai_detector.joblib +# 학습 모델이 없을 때 규칙 기반 점수를 낼지. true 면 is_stub=true 로 노출된다. AI_DETECTOR_ALLOW_HEURISTIC=false +# 휴리스틱 컷. scripts/calibrate_ai_detector_cuts.py 출력값을 넣는다. +# 비워두면 근거 없는 자리표시자(0.40/0.70)가 쓰이므로 배지가 무의미해진다. +# 값이 없으면 아래 두 줄은 주석 처리한 채로 둘 것 (빈 값은 파싱 오류). +#AI_DETECTOR_LOW_CUT= +#AI_DETECTOR_HIGH_CUT= AI_DETECTOR_USE_POS=true # PDF VII-4 권장 보수적 임계값 (정밀도 우선) diff --git a/app/core/config.py b/app/core/config.py index faf4466..00fdc11 100644 --- a/app/core/config.py +++ b/app/core/config.py @@ -40,6 +40,11 @@ class Settings(BaseSettings): ai_detector_model_path: str = "./data/models/ai_detector.joblib" ai_detector_allow_heuristic: bool = False ai_detector_use_pos: bool = True + # 휴리스틱 모드 의심도 구간. scripts/calibrate_ai_detector_cuts.py 가 등록 + # 코퍼스(전부 인간 저작)의 점수 분포에서 백분위로 산출한다. 둘 다 설정해야 + # 적용되며, 없으면 근거 없는 자리표시자(0.40/0.70)가 쓰인다. + ai_detector_low_cut: float | None = None + ai_detector_high_cut: float | None = None # PDF VII-4 권장: 정밀도 우선 보수적 임계값 similarity_threshold: float = 0.85 diff --git a/app/engine/ai_detector.py b/app/engine/ai_detector.py index 9ec3ead..7585672 100644 --- a/app/engine/ai_detector.py +++ b/app/engine/ai_detector.py @@ -59,10 +59,17 @@ ENV_MODEL_PATH = "AI_DETECTOR_MODEL_PATH" DEFAULT_MODEL_PATH = "./data/models/ai_detector.joblib" #: 잠정 의심도 구간. 학습 시 target FPR 기준으로 재산출되어 아티팩트에 저장되며, -#: 아티팩트 값이 있으면 그쪽이 우선한다. 아래는 모델이 없을 때의 자리표시자다. +#: 아티팩트 값이 있으면 그쪽이 우선한다. 아래는 아무 근거 없는 자리표시자이므로, +#: 휴리스틱 모드로 운영할 때는 scripts/calibrate_ai_detector_cuts.py 로 산출한 +#: 백분위 컷을 설정으로 주입할 것. DEFAULT_LOW_CUT = 0.40 DEFAULT_HIGH_CUT = 0.70 +#: 백분위 캘리브레이션 기본값. 등록 코퍼스(전부 인간 저작) 대비 상위 10%를 +#: medium, 상위 2%를 high 로 본다. "AI 확률"이 아니라 "인간 저작 대비 이례도"다. +DEFAULT_LOW_PERCENTILE = 90.0 +DEFAULT_HIGH_PERCENTILE = 98.0 + Provenance = Literal["human", "ai", "mixed", "edited", "unknown"] SuspicionLevel = Literal["low", "medium", "high"] @@ -592,6 +599,57 @@ def _heuristic_score(feats: dict[str, float]) -> float: return max(0.0, min(1.0, sum(positions) / len(positions))) +def percentile(values: Sequence[float], pct: float) -> float: + """선형 보간 백분위. numpy 없이도 동작하도록 직접 구현한다.""" + if not values: + return 0.0 + ordered = sorted(values) + if len(ordered) == 1: + return float(ordered[0]) + pos = (len(ordered) - 1) * max(0.0, min(100.0, pct)) / 100.0 + low = int(math.floor(pos)) + high = int(math.ceil(pos)) + if low == high: + return float(ordered[low]) + return float(ordered[low] + (ordered[high] - ordered[low]) * (pos - low)) + + +def calibrate_cuts( + human_scores: Sequence[float], + low_percentile: float = DEFAULT_LOW_PERCENTILE, + high_percentile: float = DEFAULT_HIGH_PERCENTILE, +) -> tuple[float, float]: + """인간 저작 코퍼스 점수 분포 → (low_cut, high_cut). + + 라벨이 전혀 필요 없다. "AI가 쓴 글의 점수는 얼마인가"가 아니라 "우리 코퍼스의 + 인간 저작물 중 상위 몇 %인가"로 컷을 정의하기 때문이다. 그래서 정확도를 + 측정하지 않고도 참인 진술("등록 자서전 대비 상위 2% 이례적 문체")이 되고, + 'high' 배지 비율이 정의상 고정되어 검토 부하도 예측 가능해진다. + + 두 백분위가 같은 값으로 뭉개지면(분포가 평평한 경우) high 를 살짝 올려 + medium 구간이 사라지지 않게 한다. + """ + if not human_scores: + raise ValueError("점수 표본이 비어 있어 컷을 산출할 수 없습니다.") + if not 0.0 <= low_percentile < high_percentile <= 100.0: + raise ValueError( + f"백분위는 0 <= low < high <= 100 이어야 합니다: {low_percentile}, {high_percentile}" + ) + low = percentile(human_scores, low_percentile) + high = percentile(human_scores, high_percentile) + if high <= low: + high = min(1.0, low + 0.01) + return round(low, 4), round(high, 4) + + +def score_text_heuristic(text: str, use_pos: bool = True) -> float | None: + """캘리브레이션용 단일 텍스트 점수. 너무 짧으면 None(표본에서 제외).""" + norm = normalize_text(text) + if len(norm) < HARD_MIN_CHARS: + return None + return _heuristic_score(extract_features(norm, use_pos=use_pos)) + + def _heuristic_contributions(feats: dict[str, float]) -> list[tuple[str, float]]: """휴리스틱에서 어느 특징이 점수를 끌어올렸는지.""" out: list[tuple[str, float]] = [] @@ -700,12 +758,17 @@ class AiGenerationDetector: model_path: str | Path | None = None, allow_heuristic: bool = False, use_pos: bool = True, + low_cut: float | None = None, + high_cut: float | None = None, ): self.model_path = str( model_path or os.environ.get(ENV_MODEL_PATH) or DEFAULT_MODEL_PATH ) self.allow_heuristic = allow_heuristic self.use_pos = use_pos + # 휴리스틱 모드에서 쓸 백분위 컷. 둘 다 주어졌을 때만 적용한다. + self.low_cut = low_cut + self.high_cut = high_cut self.artifact = load_artifact(self.model_path) # -- 모드 -------------------------------------------------------------- @@ -720,11 +783,26 @@ class AiGenerationDetector: def model_version(self) -> str: if self.artifact is not None: return self.artifact.model_version - return self.HEURISTIC_VERSION if self.allow_heuristic else "unavailable" + if not self.allow_heuristic: + return "unavailable" + # 컷이 코퍼스로 캘리브레이션되었는지를 버전 문자열에 드러낸다. + return ( + f"{self.HEURISTIC_VERSION}+corpus-percentile" + if self.cuts_calibrated else self.HEURISTIC_VERSION + ) + + @property + def cuts_calibrated(self) -> bool: + """컷이 자리표시자가 아니라 실제 코퍼스 분포에서 나왔는지.""" + if self.artifact is not None: + return True + return self.low_cut is not None and self.high_cut is not None def _cuts(self) -> tuple[float, float]: if self.artifact is not None: return self.artifact.low_cut, self.artifact.high_cut + if self.low_cut is not None and self.high_cut is not None: + return self.low_cut, self.high_cut return DEFAULT_LOW_CUT, DEFAULT_HIGH_CUT def _level(self, score: float) -> SuspicionLevel: @@ -862,10 +940,17 @@ class AiGenerationDetector: segments = self._score_segments(norm) if with_segments else [] provenance = self._infer_provenance(score, segments) - if self.artifact is None: + if self.artifact is None and self.cuts_calibrated: note = ( - "⚠️ 미검증 휴리스틱 baseline 입니다. 학습된 모델이 아니며 " - "판정 근거로 사용할 수 없습니다. 검토 우선순위 참고용." + "학습 모델이 아니라 언어특징 규칙 점수입니다. 'AI일 확률'이 아니라 " + "등록 코퍼스의 인간 저작물 대비 문체 이례도이며, 검토 우선순위 " + "정렬용입니다. 판정 근거로 사용할 수 없습니다." + ) + elif self.artifact is None: + note = ( + "⚠️ 미검증 휴리스틱 baseline 입니다. 학습된 모델도 아니고 컷도 " + "캘리브레이션되지 않았습니다(자리표시자). 판정 근거로 사용할 수 " + "없습니다. scripts/calibrate_ai_detector_cuts.py 로 컷을 산출하세요." ) else: note = ( @@ -1008,21 +1093,26 @@ def get_ai_detector( model_path: str | Path | None = None, allow_heuristic: bool | None = None, use_pos: bool = True, + low_cut: float | None = None, + high_cut: float | None = None, ) -> AiGenerationDetector: """탐지기 인스턴스(프로세스 캐시). allow_heuristic 을 생략하면 환경변수 AI_DETECTOR_ALLOW_HEURISTIC 을 따르고, 그것도 없으면 False(= 모델 없으면 unavailable) 다. 기본값을 False 로 두는 이유는, 미검증 점수가 조용히 운영에 노출되는 상황을 막기 위해서다. + + low_cut/high_cut 은 휴리스틱 모드에서만 쓰이며, 둘 다 주어져야 적용된다. """ if allow_heuristic is None: allow_heuristic = os.environ.get( "AI_DETECTOR_ALLOW_HEURISTIC", "" ).strip().lower() in {"1", "true", "yes"} - key = (str(model_path or ""), bool(allow_heuristic), bool(use_pos)) + key = (str(model_path or ""), bool(allow_heuristic), bool(use_pos), low_cut, high_cut) if key not in _detector_cache: _detector_cache[key] = AiGenerationDetector( - model_path=model_path, allow_heuristic=allow_heuristic, use_pos=use_pos + model_path=model_path, allow_heuristic=allow_heuristic, use_pos=use_pos, + low_cut=low_cut, high_cut=high_cut, ) return _detector_cache[key] diff --git a/app/engine/detector.py b/app/engine/detector.py index 1459708..3d29d38 100644 --- a/app/engine/detector.py +++ b/app/engine/detector.py @@ -70,6 +70,8 @@ class PlagiarismDetector: self.settings.ai_detector_model_path, allow_heuristic=self.settings.ai_detector_allow_heuristic, use_pos=self.settings.ai_detector_use_pos, + low_cut=self.settings.ai_detector_low_cut, + high_cut=self.settings.ai_detector_high_cut, ) self._persistent: PersistentCorpusIndex | None = None diff --git a/docs/AI_DETECTION.md b/docs/AI_DETECTION.md index 3b0bc5e..01379f6 100644 --- a/docs/AI_DETECTION.md +++ b/docs/AI_DETECTION.md @@ -269,3 +269,61 @@ python -m pytest tests/test_ai_detector.py -q 일치 / unavailable 시 점수 미산출 / 휴리스틱의 스텁 표기와 방향성 / 짧은 텍스트 거부·경고 / 구간 오프셋 유효성 / provenance 규칙 / 추론 실패 전파 / 특징 불일치 아티팩트 로드 거부 / JSON 직렬화. + +--- + +## 8. 지표 없이 운영하기 — 백분위 컷 (권장 경로) + +AI 생성 표본이 없어 정확도를 측정할 수 없을 때의 실용 경로다. **모델 학습도 +성능지표도 없이** 규칙 점수만으로 검토 우선순위를 매긴다. + +### 8.1 점수의 의미를 바꾼다 + +"AI일 확률"은 라벨 없이 측정할 수 없다. 대신 등록 코퍼스가 전부 인간 저작이라는 +사실을 이용해, 그 점수 분포의 상위 백분위를 컷으로 잡는다. 그러면 결과는 + +> "등록 자서전 대비 상위 2% 이례적 문체 → 우선 검토" + +가 되며, 이 진술은 **정확도를 측정하지 않아도 참**이다. 덤으로 `high` 배지 비율이 +정의상 고정되어 검토 부하가 예측 가능해진다. 반면 "AI 확률 72%"는 어떤 근거로도 +방어할 수 없다. 이 차이 때문에 백분위 컷을 권장한다. + +### 8.2 절차 + +```bash +# 서버와 같은 환경(kiwipiepy 포함)에서 실행할 것 — 품사 특징 유무가 점수를 바꾼다 +python scripts/calibrate_ai_detector_cuts.py \ + --database data/runtime/corpus.sqlite3 --sample 3000 +``` + +출력된 두 줄을 `.env` 에 넣고 `AI_DETECTOR_ALLOW_HEURISTIC=true` 와 함께 재시작한다. + +```dotenv +AI_DETECTOR_ALLOW_HEURISTIC=true +AI_DETECTOR_LOW_CUT=0.7024 +AI_DETECTOR_HIGH_CUT=0.7352 +``` + +`--low-percentile`(기본 90) / `--high-percentile`(기본 98) 로 배지 비율을 조절한다. +low/high 는 **둘 다** 설정해야 적용된다. 하나만 넣으면 자리표시자로 되돌아간다. + +### 8.3 스크립트가 거부하는 경우 + +규칙 점수는 각 규칙이 [0,1] 로 clip 되므로 상단에서 **포화**할 수 있다. 포화가 +심하면 p90 과 p98 이 같은 값이 되고, 그 컷을 쓰면 `high` 배지가 영원히 0건이 된다. +이 경우 스크립트는 `.env` 를 출력하지 않고 **exit 3** 으로 중단하며 진단을 남긴다 +(`saturated_share`, `distinct_scores`). 대응은 `--high-percentile` 을 낮추거나, +표본을 늘리거나, 표본이 특정 도서에 치우쳤는지 확인하는 것이다. + +유효 표본 100건 미만이면 백분위가 불안정하므로 **exit 2** 로 중단한다. + +### 8.4 캘리브레이션해도 달라지지 않는 것 + +- `is_stub` 은 **여전히 `true`** 다. 컷을 맞췄을 뿐 학습된 모델이 아니다. +- `model_version` 만 `heuristic-baseline-v1` → `heuristic-baseline-v1+corpus-percentile` + 로 바뀌어 컷의 출처를 드러낸다. +- AI 생성 텍스트를 실제로 구분한다는 근거는 **여전히 없다.** 이 점수가 높다는 것은 + "등록된 인간 원고들과 문체 통계가 다르다"는 뜻일 뿐이며, 번역체·대필·윤문·장르 + 차이 모두가 같은 방향으로 점수를 올린다. +- 따라서 저자·편집자에게 노출할 때는 "AI 생성 의심도"보다 **"문체 이례도"** 로 + 표기하고, 검토 우선순위 정렬 용도로만 쓸 것을 권한다. diff --git a/scripts/calibrate_ai_detector_cuts.py b/scripts/calibrate_ai_detector_cuts.py new file mode 100644 index 0000000..8af1ed0 --- /dev/null +++ b/scripts/calibrate_ai_detector_cuts.py @@ -0,0 +1,205 @@ +#!/usr/bin/env python3 +"""등록 코퍼스로 AI 의심도 컷을 백분위 캘리브레이션한다. + +왜 이렇게 하나: + AI 생성 표본이 없으면 "AI일 확률"은 측정할 수 없다. 그래서 점수의 의미를 + 바꾼다. 등록 코퍼스는 전부 인간 저작이므로, 그 점수 분포의 상위 백분위를 + 컷으로 잡으면 결과는 **"우리 코퍼스의 인간 저작물 대비 얼마나 이례적인 문체인가"** + 가 된다. 라벨도 지표도 필요 없고, "상위 2% 이례적 문체"라는 진술은 정확도를 + 측정하지 않아도 참이다. 덤으로 'high' 배지 비율이 정의상 고정되어 검토 부하가 + 예측 가능해진다. + + 이 값은 여전히 **AI 작성 판정이 아니다.** 검토 우선순위 정렬용이다. + +입력: 영속 코퍼스 SQLite (기본) 또는 data/reference/*.txt +출력: JSON 리포트 + 그대로 붙여넣을 .env 두 줄 + +사용: + python scripts/calibrate_ai_detector_cuts.py \ + --database data/runtime/corpus.sqlite3 --sample 3000 +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import logging +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(ROOT)) + +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s") +logger = logging.getLogger("calibrate-cuts") + +from app.engine.ai_detector import ( # noqa: E402 + DEFAULT_HIGH_PERCENTILE, + DEFAULT_LOW_PERCENTILE, + HARD_MIN_CHARS, + calibrate_cuts, + percentile, + score_text_heuristic, +) + + +def _stable_pick(key: str) -> int: + """표본 추출용 결정적 해시. 같은 코퍼스면 항상 같은 표본이 뽑힌다.""" + return int(hashlib.sha1(key.encode("utf-8")).hexdigest()[:8], 16) + + +def load_texts(database: Path | None, reference_dir: Path | None, sample: int) -> list[str]: + """코퍼스에서 텍스트를 표본 추출. 전량 처리는 느리므로 기본은 표본이다.""" + items: list[tuple[int, str]] = [] + + if database and database.exists(): + from app.engine.provenance import CorpusStore + + for seg in CorpusStore(database).iter_segments(): + items.append((_stable_pick(seg.segment_id), seg.text)) + logger.info("SQLite 세그먼트 %d건 로드: %s", len(items), database) + elif reference_dir and reference_dir.exists(): + for path in sorted(reference_dir.glob("*.txt")): + try: + items.append((_stable_pick(path.name), path.read_text(encoding="utf-8"))) + except UnicodeDecodeError: + logger.warning("UTF-8 아님, 건너뜀: %s", path.name) + logger.info("텍스트 파일 %d건 로드: %s", len(items), reference_dir) + else: + raise SystemExit("코퍼스를 찾을 수 없습니다. --database 또는 --reference-dir 확인.") + + items.sort(key=lambda kv: kv[0]) + if sample > 0: + items = items[:sample] + return [text for _, text in items] + + +def main() -> int: + ap = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter + ) + ap.add_argument("--database", type=Path, default=Path("data/runtime/corpus.sqlite3")) + ap.add_argument("--reference-dir", type=Path, default=Path("data/reference"), + help="SQLite 가 없을 때 쓰는 폴백") + ap.add_argument("--sample", type=int, default=3000, + help="표본 수 (0이면 전량). 3000이면 백분위 추정에 충분하다.") + ap.add_argument("--low-percentile", type=float, default=DEFAULT_LOW_PERCENTILE) + ap.add_argument("--high-percentile", type=float, default=DEFAULT_HIGH_PERCENTILE) + ap.add_argument("--no-pos", action="store_true", help="품사 특징 사용 안 함") + ap.add_argument("--out", type=Path, default=Path("data/models/ai_cuts.json")) + args = ap.parse_args() + + texts = load_texts(args.database, args.reference_dir, args.sample) + if not texts: + logger.error("표본이 0건입니다.") + return 2 + + # 실제로 품사 특징이 쓰였는지 확인 (kiwipiepy 없으면 자동 폴백된다) + from app.engine.ai_detector import extract_features + + pos_used = ( + not args.no_pos + and extract_features(texts[0], use_pos=not args.no_pos)["pos_available"] >= 1.0 + ) + if not args.no_pos and not pos_used: + logger.warning( + "kiwipiepy 를 쓸 수 없어 품사 특징 없이 채점합니다. 운영 서버와 " + "동일 조건이 아니면 컷이 맞지 않으니, 반드시 서버와 같은 환경에서 " + "실행하세요." + ) + + scores: list[float] = [] + skipped = 0 + for i, text in enumerate(texts, 1): + value = score_text_heuristic(text, use_pos=not args.no_pos) + if value is None: + skipped += 1 + continue + scores.append(value) + if i % 500 == 0: + logger.info("채점 %d/%d", i, len(texts)) + + logger.info("채점 완료: %d건 (%d자 미만 %d건 제외)", len(scores), HARD_MIN_CHARS, skipped) + if len(scores) < 100: + logger.error( + "유효 표본이 %d건뿐이라 백분위가 불안정합니다(최소 100). " + "--sample 을 늘리거나 코퍼스를 확인하세요.", len(scores) + ) + return 2 + + low_cut, high_cut = calibrate_cuts(scores, args.low_percentile, args.high_percentile) + + distribution = {f"p{p}": round(percentile(scores, p), 4) + for p in (5, 25, 50, 75, 90, 95, 98, 99)} + expected_medium = sum(1 for s in scores if low_cut <= s < high_cut) / len(scores) + expected_high = sum(1 for s in scores if s >= high_cut) / len(scores) + + # 포화 진단: 규칙 점수가 상단에서 clip 되면 p90=p98 이 되어 컷이 무의미해진다. + # 이 경우 .env 를 그대로 쓰면 high 배지가 영원히 0건이 되므로 거부한다. + top = max(scores) + saturated_share = sum(1 for s in scores if s >= top - 1e-9) / len(scores) + distinct = len(set(round(s, 4) for s in scores)) + target_high = (100.0 - args.high_percentile) / 100.0 + + report = { + "source": str(args.database if args.database.exists() else args.reference_dir), + "n_scored": len(scores), + "n_skipped_short": skipped, + "use_pos_requested": not args.no_pos, + "pos_actually_used": pos_used, + "low_percentile": args.low_percentile, + "high_percentile": args.high_percentile, + "low_cut": low_cut, + "high_cut": high_cut, + "distribution": distribution, + "distinct_scores": distinct, + "saturated_share": round(saturated_share, 4), + "expected_rate_on_human_corpus": { + "medium": round(expected_medium, 4), + "high": round(expected_high, 4), + "target_high": target_high, + }, + "note": ( + "인간 저작 코퍼스 대비 문체 이례도 컷이며 AI 작성 판정이 아니다. " + "expected_rate 는 인간 원고에서도 이 비율만큼 medium/high 가 나온다는 뜻." + ), + } + + args.out.parent.mkdir(parents=True, exist_ok=True) + args.out.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8") + print(json.dumps(report, ensure_ascii=False, indent=2)) + + if expected_high <= 0.0: + logger.error( + "이 컷을 쓰면 'high' 배지가 **영원히 0건**입니다. 점수가 상단에서 " + "포화(최고점 동률 %.1f%%, 서로 다른 점수 %d개)되어 p%.0f 와 p%.0f 가 " + "같은 값이기 때문입니다. .env 를 출력하지 않습니다.", + saturated_share * 100, distinct, args.low_percentile, args.high_percentile, + ) + logger.error( + "대응: ① --high-percentile 을 낮춰 동률 구간 아래로 컷을 내리거나 " + "② --sample 을 늘려 분포를 넓히거나 ③ 표본이 특정 도서에 치우쳤는지 " + "확인하세요. 리포트는 %s 에 저장했습니다.", args.out, + ) + return 3 + + if expected_high > target_high * 3 or expected_high < target_high / 3: + logger.warning( + "예상 high 비율 %.2f%% 가 목표 %.2f%% 에서 크게 벗어났습니다" + "(점수 동률 때문). 배지 비율이 설계와 다르게 나옵니다.", + expected_high * 100, target_high * 100, + ) + + print("\n# .env 에 아래 두 줄을 추가하세요") + print(f"AI_DETECTOR_LOW_CUT={low_cut}") + print(f"AI_DETECTOR_HIGH_CUT={high_cut}") + print( + f"\n# 인간 원고 기준 예상 배지 비율: medium {expected_medium:.1%}, " + f"high {expected_high:.1%}" + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_ai_detector.py b/tests/test_ai_detector.py index 69fb157..818b659 100644 --- a/tests/test_ai_detector.py +++ b/tests/test_ai_detector.py @@ -511,3 +511,147 @@ def test_valid_artifact_roundtrip(tmp_path): det = AiGenerationDetector(model_path=path, allow_heuristic=False) assert det.mode == "trained" assert det.detect(UNIFORM_TEXT, with_segments=False).score == pytest.approx(0.66) + + +# --------------------------------------------------------------------------- +# 백분위 컷 캘리브레이션 (라벨 없이 인간 코퍼스만으로) +# --------------------------------------------------------------------------- + +def test_percentile_matches_known_values(): + values = [0.0, 0.25, 0.5, 0.75, 1.0] + assert ad.percentile(values, 0) == pytest.approx(0.0) + assert ad.percentile(values, 50) == pytest.approx(0.5) + assert ad.percentile(values, 100) == pytest.approx(1.0) + assert ad.percentile([], 50) == 0.0 + assert ad.percentile([0.3], 90) == pytest.approx(0.3) + + +def test_calibrate_cuts_from_human_scores(): + scores = [i / 1000 for i in range(1000)] # 0.000 ~ 0.999 균등 + low, high = ad.calibrate_cuts(scores, 90, 98) + assert low == pytest.approx(0.899, abs=0.01) + assert high == pytest.approx(0.979, abs=0.01) + assert low < high + + +def test_calibrate_cuts_keeps_medium_band_when_distribution_is_flat(): + low, high = ad.calibrate_cuts([0.5] * 200, 90, 98) + assert high > low, "분포가 평평해도 medium 구간이 사라지면 안 된다" + + +def test_calibrate_cuts_rejects_bad_input(): + with pytest.raises(ValueError): + ad.calibrate_cuts([]) + with pytest.raises(ValueError): + ad.calibrate_cuts([0.5], 98, 90) # low >= high + with pytest.raises(ValueError): + ad.calibrate_cuts([0.5], -1, 50) + + +def test_calibrated_cuts_produce_expected_badge_rate(): + """컷의 존재 이유 — 인간 코퍼스에서 high 비율이 설계값으로 고정된다.""" + scores = [i / 1000 for i in range(1000)] + low, high = ad.calibrate_cuts(scores, 90, 98) + high_rate = sum(1 for s in scores if s >= high) / len(scores) + assert high_rate == pytest.approx(0.02, abs=0.005) + + +def test_score_text_heuristic_skips_short_text(): + assert ad.score_text_heuristic("너무 짧다.") is None + value = ad.score_text_heuristic(UNIFORM_TEXT) + assert value is not None and 0.0 <= value <= 1.0 + + +def test_detector_uses_injected_cuts(tmp_path): + det = AiGenerationDetector( + model_path=tmp_path / "none.joblib", allow_heuristic=True, + low_cut=0.10, high_cut=0.20, + ) + assert det.cuts_calibrated is True + assert det._cuts() == (0.10, 0.20) + assert det.model_version == "heuristic-baseline-v1+corpus-percentile" + assert det._level(0.05) == "low" + assert det._level(0.15) == "medium" + assert det._level(0.50) == "high" + + +def test_partial_cuts_are_ignored(tmp_path): + """한쪽만 주면 자리표시자로 되돌아가야 한다 (반쪽 설정 방지).""" + det = AiGenerationDetector( + model_path=tmp_path / "none.joblib", allow_heuristic=True, low_cut=0.1, + ) + assert det.cuts_calibrated is False + assert det._cuts() == (ad.DEFAULT_LOW_CUT, ad.DEFAULT_HIGH_CUT) + assert det.model_version == "heuristic-baseline-v1" + + +def test_uncalibrated_heuristic_note_warns(tmp_path): + det = AiGenerationDetector(model_path=tmp_path / "none.joblib", allow_heuristic=True) + res = det.detect(UNIFORM_TEXT, with_segments=False) + assert res.is_stub is True + assert "캘리브레이션되지 않았습니다" in res.note + + +def test_calibrated_heuristic_note_states_relative_meaning(tmp_path): + det = AiGenerationDetector( + model_path=tmp_path / "none.joblib", allow_heuristic=True, + low_cut=0.3, high_cut=0.6, + ) + res = det.detect(UNIFORM_TEXT, with_segments=False) + assert res.is_stub is True, "캘리브레이션해도 학습 모델은 아니다" + assert "문체 이례도" in res.note + assert "확률" in res.note + + +def test_artifact_cuts_win_over_injected_cuts(): + det = _stub_detector(0.5) + det.low_cut, det.high_cut = 0.01, 0.02 + assert det._cuts() == (0.40, 0.70), "학습 아티팩트가 있으면 그쪽이 우선" + + +def test_calibration_script_refuses_degenerate_corpus(tmp_path): + """포화된 코퍼스에서 'high 배지 0건' 설정을 출력하면 안 된다.""" + import subprocess + import sys + from pathlib import Path + + ref = tmp_path / "ref" + ref.mkdir() + # 완전히 동일한 텍스트 200건 → 점수 전부 동률 = 포화 + for i in range(200): + (ref / f"ref-{i:04d}__같은책.txt").write_text(UNIFORM_TEXT, encoding="utf-8") + + root = Path(__file__).resolve().parents[1] + proc = subprocess.run( + [sys.executable, "scripts/calibrate_ai_detector_cuts.py", + "--database", str(tmp_path / "absent.sqlite3"), + "--reference-dir", str(ref), "--sample", "0", + "--out", str(tmp_path / "cuts.json")], + cwd=root, capture_output=True, text=True, + ) + assert proc.returncode == 3, proc.stderr[-1500:] + assert "AI_DETECTOR_LOW_CUT" not in proc.stdout, "죽은 설정을 출력하면 안 된다" + assert "영원히 0건" in proc.stderr + # 진단 리포트는 남아야 한다 + assert (tmp_path / "cuts.json").exists() + + +def test_calibration_script_fails_on_tiny_sample(tmp_path): + import subprocess + import sys + from pathlib import Path + + ref = tmp_path / "ref" + ref.mkdir() + for i in range(5): + (ref / f"ref-{i}__책.txt").write_text(UNIFORM_TEXT, encoding="utf-8") + + proc = subprocess.run( + [sys.executable, "scripts/calibrate_ai_detector_cuts.py", + "--database", str(tmp_path / "absent.sqlite3"), + "--reference-dir", str(ref), "--sample", "0", + "--out", str(tmp_path / "cuts.json")], + cwd=Path(__file__).resolve().parents[1], capture_output=True, text=True, + ) + assert proc.returncode == 2 + assert "불안정" in proc.stderr