150e729aef
기능 실효성 평가에서 확정된 판별력 붕괴를 고친다. 신호조합 224개 전수에서 77.7% 가 high, 56% 가 정확히 100점에 붙고 low 는 3.6% 뿐이었다. 큐 기본 정렬이 riskScore 내림차순인데 전건이 100 이면 정렬이 no-op 이므로, 점수가 운영자에게 주는 우선순위 정보가 0비트였다. 동인은 하나가 아니라 둘이었고 둘 다 "같은 사실을 여러 행으로 센다"는 같은 형태다. 라벨 풀 (WEB_ENTITY_MAX_POINTS = 20) category 없는 raw Vision 웹 엔티티가 이름별 버킷이라 서로 dedup 되지 않고 round(40*conf) 씩 무한 누적됐다. Vision 은 maxResults=10 이라 모든 이미지에 라벨을 붙이므로, 이미지 매칭이 0건이어도 0.8 짜리 라벨 3개면 100/high 였고 웹에 전혀 없는 오리지널 사진이 66/medium 이었다. 모집단 전체에 상수로 존재하는 신호는 판별에 기여할 수 없다. medium 임계(30) 아래로 묶어 라벨이 케이스를 물들일 수는 있어도 밴드를 정하지는 못하게 했다. category(character/celebrity/work) 가 붙은 엔티티는 풀에서 제외한다 — 그것은 raw 라벨이 아니라 권리 분류이고 엔티티별 +45 를 유지한다. 조사 단계에서 "test_two_distinct_web_entities_stack_into_high_risk 가 이 동작을 고정하므로 함께 개정해야 한다"고 봤으나 틀렸다. 그 테스트는 category 있는 엔티티를 다루므로 두 분기를 가르면 개정 없이 통과한다. 웹 존재 풀 (WEB_PRESENCE_MAX_POINTS = 60) Vision 응답 1회가 "이 이미지가 웹에 있다"는 하나의 사실을 full / partial / page / visual 4개 상관된 뷰로 동시에 보고하는데, 스코어러가 이를 독립 신호로 합산해 45+35+35+10 = 125 -> 상한 100 이 됐다. 널리 게시된 평범한 이미지와 명백한 침해물이 같은 100/high 로 수렴한 이유다. high 임계(70) 아래로 묶었다. 원칙: 웹에 존재한다는 사실만으로는 high 가 되지 않는다. high 가 되려면 두 번째 종류의 신호(인물, 지식DB 지문 매칭, 승격된 검색 히트)가 필요하다. 존재 자체는 침해가 아니고 그 판단은 운영자의 몫이다. 측정 (224조합, v1 -> v2) 웹 신호만으로 high 가 되는 조합 2/7 -> 0/7 100점 포화 66.5% -> 51.3% 웹에 없는 오리지널 사진, 라벨만 100/high -> 20/low 이미 안전 확인한 자산(cleared) 100/high -> 20/low 웹 존재 광범위(4개 매치 타입) 100/high -> 60/medium 완전일치 사본 + 식별가능 인물 80/high -> 80/high (불변) 명백한 침해(전 신호) 100/high -> 100/high (불변) 전체 high 비율은 82.6% -> 76.3% 로 크게 안 움직인다. 이 격자는 신호 축을 균등 샘플링하므로(지식DB 강매칭이 1/4) 실제 큐 분포의 대리값이 아니며, 실 DB 6건도 100x4 -> 95x4 로 밴드가 바뀌지 않는다 — 그 4건은 전부 "완전일치 사본 + 인물" 이라 high 가 맞다. 고친 것은 거짓 high 이지 진짜 high 가 아니다. 두 상한은 신호의 구조적 성질에서 나온 값이지 캘리브레이션 결과가 아니다. 판정 30~50건이 쌓이면 decision_stats 교차표로 임계와 함께 재조정해야 한다. 라운드트립 버킷 보존 테스트(test_review_fixes.py)는 신뢰도 1.0 에서 두 엔티티가 모두 캡에 붙어 성질이 가려졌다. 검증 대상은 점수가 아니라 엔티티 이름 버킷이 직렬화를 넘어 살아남는가이므로, 풀 아래(신뢰도 0.2)에서 재작성하고 동일 엔티티 반복이 여전히 1건으로 접히는지도 함께 본다. 테스트 5건 추가. pytest 570 passed(착수 전 565), 린트 클린. |
||
|---|---|---|
| docs | ||
| src/rights_filter | ||
| tests | ||
| web/operator-gui | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| CLAUDE.md | ||
| package.json | ||
| pytest.ini | ||
| README.md | ||
| requirements-dev.txt | ||
| requirements.txt | ||
| ruff.toml | ||
| run_copyrighter_server.py | ||
| verify.ps1 | ||
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의 공용 픽스처를 사용합니다.
문서
- 프로젝트 구조 지도 (PROJECT_MAP) — 파일·라우트·스키마 위치, 로드 순서, 알려진 부채
- 작업 이력 (INDEX)
- 프로젝트 소개 및 기술 구현
- 운영 워크리스트
- 오프라인 설치 절차