PIA-Auditor — 기술스택 선정서 및 개발기획서

대상 05_분석툴_기능명세서.md v1.0 구현
문서 버전 v1.0 · 2026-08-04
전제 본 문서의 모든 수치는 이번 세션에서 실측한 값(문서 크기, 하드웨어 사양, 변환 결과)에 기반한다. 추정치는 추정치라고 표기했다.

1. 요약 — 선정 결과 한 장

가장 중요한 아키텍처 결정 하나: 수행안내서 456쪽이 Claude의 1M 컨텍스트 윈도우에 통째로 들어간다. 따라서 기준문서에 대한 RAG(청킹→검색→재구성)를 만들지 않는다. 대신 안내서에서 추출한 지식베이스(121지표 + 12체크리스트)를 프롬프트 캐시 프리픽스에 상주시킨다. 근거와 비용 계산은 §5.

2. 실측 제약조건

2.1 실행 환경 (maindev, 실측)

CPU     24 코어        MEM  62 GB (가용 33 GB)
GPU     없음  ← 결정적 제약
DISK    652 GB 여유
Python  3.10.12 (시스템)
있음    docker, git, node
없음    uv, poetry, soffice(LibreOffice), tesseract, nvidia 드라이버

GPU 부재가 세 가지를 강제한다.
1. 로컬 비전 모델(Qwen2.5-VL 등)로 슬라이드를 판독하는 선택지가 사라진다 → 클라우드 vision 또는 CPU OCR.
2. 임베딩은 CPU 배치 추론 (BGE-M3, 수천 청크 기준 수 분 — 실용적).
3. 리랭커(cross-encoder) 도입은 비용 대비 효과가 나쁘다 → 도입하지 않는다.

2.2 데이터 실측치

2.3 보안 제약

입력 문서에 미공개 사업정보와 실명 인력정보가 들어 있다(수탁사 목록, 투입인력 경력·자격). 이는 스택 선정에 직접 영향을 준다.

• 기본 모드는 로컬 처리. 외부 API 전송은 명시적 opt-in + 전송 항목 로깅.
• 완전 로컬 모드(--offline)를 1급 기능으로 지원해야 한다 → OCR 폴백 경로가 장식이 아니라 필수인 이유.

3. 선정 원칙

1. 검증된 것을 승계한다. tools/pdf2md.py는 456쪽·81쪽 문서로 동작을 확인했다. 재작성하지 않는다.
2. 결정론을 LLM보다 앞에 둔다. 룰로 판정 가능한 것에 LLM을 쓰지 않는다 — 비용·재현성·오탐 모두에서 진다.
3. 서버를 늘리지 않는다. Postgres·Redis·벡터DB·워크플로우 엔진 없이 SQLite 단일 파일로 간다. 다중 사용자 웹이 필요해지면 그때 바꾼다.
4. 라이선스를 나중에 확인하지 않는다. 사내 도구로 시작해도 배포·SaaS 전환 시 막히는 선택은 처음부터 추상화한다.
5. API 계약을 기억이 아니라 문서에서 가져온다. 모델 파라미터는 세대마다 바뀐다(§4.6이 그 사례).

4. 스택 결정 (ADR)

4.1 언어/런타임 — Python 3.12, uv

4.2 PDF 처리 — PyMuPDF, 단 추상화 필수 ⚠️

4.3 HWP — 3단 폴백

HWPX는 zip+XML이므로 표준 라이브러리로 직접 파싱한다.

4.4 이미지 판독 — Claude vision 기본 / PaddleOCR 로컬

해상도 정책: Opus 5 / Sonnet 5는 고해상도 비전(장변 2576px, 최대 4784 토큰/이미지)을 지원한다. 이번 세션은 110 dpi(장변 약 1180px)로 충분히 판독됐다 — 슬라이드는 원래 저밀도 문서다. 기본 110 dpi, 판독 실패 시 200 dpi 재시도. 기본을 고해상도로 두면 이미지 토큰이 3배가 되므로 올리지 않는다.

4.5 LLM — 단계별 3단 배치

Anthropic Claude API. 모델 ID는 날짜 접미사 없는 정확한 문자열을 쓴다.

프롬프트 캐싱 (핵심 비용 레버):
- 캐시 프리픽스 = 지식베이스(121지표 + 12체크리스트) + 룰 정의. 문서별로 바뀌지 않는다.
- 캐시 읽기 ≈ 입력가의 0.1배, 쓰기 1.25배(5분 TTL) / 2배(1시간 TTL).
- 5분 TTL 기준 2회 요청부터 이득. 한 번의 분석이 수십 회 호출이므로 항상 이득.
- 주의: 최소 캐시 가능 프리픽스가 모델별로 다르다 — Opus 5는 512토큰, Sonnet 5는 1024토큰. 지식베이스는 수만 토큰이므로 문제없다.
- 캐시 무효화 방지: 프리픽스에 타임스탬프·UUID·요청 ID를 넣지 않는다. JSON 직렬화는 sort_keys=True. 도구 목록은 이름순 정렬 고정.

구조화 출력: Finding 스키마(§05 M10-F02)를 Pydantic으로 정의하고 client.messages.parse()로 검증받는다. 파싱 실패·재시도 루프를 직접 짜지 않는다.

Citations API — M9의 1차 방어선:

{"type": "document", "source": {...}, "citations": {"enabled": True}}

응답이 cited_text와 page_location(1-indexed)을 직접 반환한다. 인용을 모델에게 "적어달라"고 요청하는 대신 API가 구조적으로 보장하므로, M9-F04의 문자열 대조는 2차 검증이 된다. 단 구조화 출력(output_config.format)과 동시 사용 시 400 — 두 경로를 분리해야 한다:
- 근거 추출 호출 → Citations 사용, 자유 텍스트
- 판정 호출 → 구조화 출력 사용, 근거는 앞 단계 결과를 입력으로 받음

4.6 ⚠️ 재현성 — 온도 0은 쓸 수 없다 (05 문서 정정)

05_분석툴_기능명세서.md의 비기능 요구사항에 "LLM 온도 0" 이라고 적었는데, 이는 현행 모델에서 틀렸다. Claude Opus 5 / Sonnet 5는 temperature·top_p·top_k를 파라미터 자체로 거부한다(400). 05 문서는 정정했다.

재현성은 다른 세 축으로 확보한다.

추가로 model·프롬프트 해시·지식베이스 버전·룰 버전을 매 실행 기록한다. 결정론이 아니라 감사 가능성이 목표다.

4.7 임베딩 — BGE-M3 (CPU)

4.8 저장소 — SQLite

4.9 오케스트레이션 — 자체 DAG + 콘텐츠 해시 캐시

Prefect·Dagster·Airflow를 쓰지 않는다. 이유:

• 재현성 NFR이 입력 해시 → 출력 캐시를 어차피 요구한다. 그 캐시가 곧 DAG 실행기다.
• 워크플로우 엔진은 서버·스케줄러·UI를 끌고 온다(§선정원칙 3 위반).
• 단계가 10개, 분기가 2개(텍스트/이미지)뿐이다.

@stage(inputs=["doc.pdf"], version="m2-v3")
def convert(doc): ...          # 입력 해시 + 코드 버전 → 캐시 키

LLM 호출 결과도 같은 캐시에 들어간다 → 재실행 시 API 비용 0. 개발 중 가장 큰 비용 절감 수단이다.

4.10 나머지

5. 비용 모델

5.1 단가 (2026-06 기준, 백만 토큰당)

캐시 읽기 ≈ 입력가 × 0.1 / 캐시 쓰기 = 입력가 × 1.25(5분) 또는 × 2(1시간) / Batch API = 전 항목 50%

5.2 왜 RAG를 만들지 않는가

안내서 408,506자를 토큰으로 환산하면 — 한국어+마크다운 혼합 기준 대략 1.5~2.5자/토큰으로 잡아 약 165K~270K 토큰(반드시 count_tokens로 실측할 것).

중간을 택한다. RAG는 비용을 10배 더 줄이지만, 청킹 경계에서 지표가 잘리고 검색 실패가 조용한 누락으로 이어진다 — 이 도구의 핵심 실패 모드(§05 원칙 3)와 정면 충돌한다. 지식베이스 방식은 121개 지표를 항상 전부 본다는 보장을 유지하면서 비용을 10배 줄인다. 이것이 M4가 "정리"가 아니라 압축 단계인 이유다.

5.3 1회 분석 비용 추정 (이번 마사회 건 규모)

이 숫자의 지위: 실측이 아니라 단가 × 추정 토큰이다. Phase 1의 토큰 회계가 붙는 즉시 실측으로 교체한다. 다만 자릿수는 신뢰할 만하다 — 컨설턴트 1인시 대비 압도적으로 싸다는 판단에는 충분하다.

5.4 개발 중 비용 통제

1. 콘텐츠 해시 캐시(§4.9) — 재실행 비용 0
2. 골든셋 고정 — 매번 새 문서로 테스트하지 않는다
3. Batch API — 비대화형 단계 전부
4. count_tokens 사전 호출 — 대형 요청 전 예상 비용 로깅

6. 개발기획

6.1 목표와 비목표

6.2 사용자와 가치

6.3 성공지표

6.4 리스크 등록부

6.5 일정·투입 (개발자 1인 기준)

P2 종료(4주) 시점에 이미 실사용 가능하다. LLM 없이 미기입·결번·산출물 누락을 잡아내며, 이번 세션 §4의 6건이 전부 P2 범위다. 상세 슬라이스 계획은 07_개발계획서_vertical_slice.md.

6.6 도입 전제

• Anthropic API 키 (또는 ant auth login 프로파일)
• 초기 벤치마크용 문서 5쌍(RFP + 제안서) — 오탐률 측정용
• 기준문서 개정 추적 담당자 지정 (R3은 도구가 아니라 사람이 감당한다)

부록 A. 의존성 초안

[project]
requires-python = ">=3.12"
dependencies = [
  "pymupdf>=1.28",          # AGPL — 4.2 참조
  "pdfplumber>=0.11",       # MIT, 대체 백엔드
  "pypdfium2>=4",           # BSD/Apache, 대체 렌더러
  "anthropic>=0.116",
  "pydantic>=2.9",
  "pydantic-settings>=2",
  "typer>=0.12",
  "jinja2>=3.1",
  "xlsxwriter>=3.2",
  "sentence-transformers>=3",
  "structlog>=24",
]
[project.optional-dependencies]
offline = ["paddleocr>=2.8", "paddlepaddle>=2.6"]
hwp     = ["pyhwp>=0.1"]      # GPL — 4.3 참조

부록 B. 라이선스 요약

AGPL·GPL 2건이 이 스택의 유일한 법적 리스크다. 사내 도구로만 쓴다면 문제없고, 외부 제공 계획이 생기면 §4.2의 대체 경로로 전환한다. 전환 비용을 낮게 유지하는 것이 Phase 1의 설계 목표 중 하나다.