cw2007/POSA_Copyrighter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
POSA_Copyrighter/README.md
changukyu c740c2e6ba feat: 캘리브레이션 측정 도구 + 스코어러 구조적 거동 첫 실측 
SCORER_VERSION 이 v1 에서 v4 까지 갔는데 v3(제공자별 풀링)와 v4(신뢰 출처)는
밴드 분포를 한 번도 측정하지 않고 나갔다. 2026-08-08 평가가 쓴 224조합 하네스는
저장소에 남아 있지 않고, 그 문서의 두 수치(174/224=77.7% 와 82.6%)가 서로 맞지
않아 격자가 달랐음을 시사한다 — 과거 숫자와 비교 가능한 재현은 불가능하다.
그래서 격자를 스크립트에 명시적으로 고정해 새 기준선으로 삼는다.

  scripts/score_distribution.py   432조합 전수, 사람 없이 돈다
  scripts/sweep_thresholds.py     판정 시점 스냅샷 기준 임계 스윕
  docs/operations/calibration-corpus.md  코퍼스 절차

실측 결과(v4, 432조합):

                     신뢰출처 미등록   신뢰출처 등록
  high                      92%            63%
  100점 포화                80%            38%
  웹 신호만으로 high      13/24           0/24

두 가지가 드러났다.

1. v2 가 세운 "웹 존재만으로는 high 가 되지 않는다" 원칙이 이미 깨져 있다.
   presence 풀(최대 60)과 entity 풀(최대 20)이 각각 임계 아래로 캡되지만 합은
   캡되지 않아, full+partial + 엔티티 1개만으로 80/high 가 된다.

2. v3 의 제공자별 풀링이 그 경향을 키웠다. 독립 제공자가 하나 더 있으면 웹 전용
   조합의 high 가 4/12 -> 9/12, 전체 high 가 88% -> 97% 가 된다. 교차 확증이
   high 에 닿아야 한다는 v3 의 의도대로 동작한 결과지만 총량 통제가 없다.

대응 후보(웹 유래 점수 총합 상한)는 적용하지 않았다. 적용하면 또 한 번의
미측정 변경이 되고, 이번 실측이 바로 그 패턴을 지적한 것이기 때문이다.
결정 후 진행한다 — 적용 시 SCORER_VERSION 을 올리고 이 표를 다시 측정한다.

이 격자는 신호 축을 균등 샘플링하므로 실제 큐 분포가 아니다. 92% 는 "실제 큐의
92% 가 high"라는 뜻이 아니고 임계가 맞는지도 말해주지 않는다. 구조적 거동의
기준선일 뿐이다.

임계 검증은 실이미지 30~50장과 **사람의 판정**이 있어야 성립한다. 내가 판정을
만들면 도구의 밴드를 내 라벨과 대조하는 꼴이라 아무것도 검증되지 않는다.
sweep_thresholds.py 는 그때를 위한 도구이고, 지금은 usable pairs 0 을 정직하게
보고한다(가짜 판정 6건을 넣은 사본 DB 로 출력 동작은 확인했다).

검증: ruff clean, pytest 645 passed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BStHFrjQj2VypecSG9ex1V
2026-09-22 08:56:57 +09:00

5.4 KiB
Raw Blame History

POSA Copyrighter

이미지 저작권 위험을 자동 분석하고, 운영자가 콘솔에서 근거를 확인해 승인 / 보류 / 반려를 판정하는 폐쇄망(air-gapped) 운영 도구입니다.

  • 분석 서버: 제출 이미지를 분석해 위험도·근거를 산출하고 SQLite에 저장
  • 운영자 콘솔: 심사 큐, 근거 검토, 판정, 지식 DB, 감사 로그를 제공하는 단일 페이지 웹 GUI
  • 외부 근거 검색: Naver 검색, Google Vision/Custom Search, 로컬 LLM(Ollama) 연동(선택)

요구 사항

  • Python 3.13
  • 런타임 서드파티 의존성은 이미지 처리 라이브러리뿐입니다(지연 로딩): numpy, opencv-python-headless, pillow

폐쇄망(air-gapped) 원칙: 모든 의존성·자산은 빌드/스테이징 머신에서 미리 받아 오프라인 휠로 설치합니다. 대상 서버는 설치·실행 시 인터넷에 접근하지 않습니다. 자세한 절차는 docs/operations/offline-install.md를 참고하세요.

설치

# 개발 머신 (온라인) — 의존성 설치
pip install -r requirements.txt          # 런타임
pip install -r requirements-dev.txt      # 테스트 포함

# 폐쇄망 대상 — 오프라인 휠로 설치 (예시)
pip install --no-index --find-links wheelhouse -r requirements.txt

.env.example를 복사해 .env를 만들고 필요한 값(인증 토큰, 검색 API 키 등)을 채웁니다. 키를 비워 두면 해당 외부 검색은 자동으로 비활성화됩니다.

cp .env.example .env

실행

python run_copyrighter_server.py
# 옵션은 런처에 그대로 전달됩니다
python run_copyrighter_server.py --host 127.0.0.1 --port 9500

python -m rights_filter.server 로 직접 실행하려면 src/ 가 import 경로에 있어야 합니다 (PYTHONPATH=src, Windows PowerShell 은 $env:PYTHONPATH="src"). 런처는 이 경로 설정과 작업 디렉터리 고정을 대신 해 주므로 run_copyrighter_server.py 사용을 권장합니다.

주요 옵션: --host, --port, --db(SQLite 경로), --images(제출 이미지 폴더), --static(운영자 GUI 경로), --env(.env 경로).

기본값으로 실행하면 http://127.0.0.1:9500 에서 운영자 콘솔이 열립니다.

보안: COPYRIGHTER_AUTH_TOKEN이 비어 있으면 데이터 라우트가 인증 없이 열립니다. 단일 호스트 개발 환경 외에는 반드시 토큰을 설정하세요.

토큰을 설정하면 틀린 토큰을 제시한 시도는 클라이언트 주소별로 60초당 10회로 제한되고, 초과 시 429와 Retry-After를 반환합니다. 토큰을 아직 입력하지 않은 요청(콘솔 최초 로드)은 시도로 세지 않으므로 정상 운영자가 잠기지 않습니다.

프로젝트 구조

src/rights_filter/      분석·서버·통합·도메인 로직 (Python)
  server/               http.server 기반 API + 정적 파일 서빙, SQLite 저장소
  analysis/             이미지 분석·위험도 산출
  integrations/         Naver / Google / LLM 어댑터
web/operator-gui/       운영자 콘솔 (정적 SPA: index.html, app-*.js, styles.css)
tests/                  pytest 테스트
  operator_gui/         운영자 GUI 정적 검증 + Playwright E2E
docs/                   기획·설계·운영 문서

콘솔 스크립트는 관심사별로 app-*.js 15개로 나뉘어 있고, index.html 의 로드 순서가 의미를 갖습니다(클래식 스크립트가 하나의 전역 스코프를 공유). 순서와 목록은 docs/PROJECT_MAP.md 에 있으며 정적 테스트가 이를 고정합니다.

검증 / 테스트

커밋 전 게이트는 단일 명령입니다(CI 도 같은 명령을 호출합니다). ruff 린트와 pytest 전체를 순서대로 실행합니다.

.\verify.ps1              # 린트 + 테스트 전체
.\verify.ps1 -SkipLint    # 빠른 내부 루프 (테스트만)
.\verify.ps1 -Coverage    # src/ 커버리지 리포트 포함

개별 실행이 필요할 때:

python -m pytest                 # 또는 그냥 pytest — pytest.ini 가 경로를 설정합니다
python -m ruff check src tests   # 설정: ruff.toml

# 운영자 GUI E2E (Playwright)
playwright install chromium      # 빌드 머신에서 1회 — 브라우저 바이너리는 오프라인 번들에 포함
python -m pytest tests/operator_gui/
  • 브라우저(E2E) 테스트는 Playwright/Chromium이 없으면 자동으로 건너뜁니다(importorskip + graceful skip).
  • 운영자 워크벤치는 tests/operator_gui/pages/의 Page Object(OperatorWorkbench)와 conftest.py의 공용 픽스처를 사용합니다.

문서