김경종
4.9 KiB
4.9 KiB
Architecture Decision Records
철학
- 공학적인 PDF 문서를 AI가 쉽게 이해할 수 있도록 수식, 이미지, 표, 글의 구조를 정확하게 변환한다.
- AI가 쉽게 분할된 문서에 접근할 수 있도록 챕터나 문단별로 파일명, line 위치, 원본 page 정보를 연결하는 index 파일을 생성한다.
- 로컬 실행과 재현 가능한 변환 결과를 1차 목표로 삼고, 외부 API와 UI는 이후 단계로 분리한다.
ADR-001: Marker를 1차 PDF Parser로 채택
결정: Nougat 대신 Marker를 1차 기본 PDF parser로 사용한다.
이유:
- 1차 MVP 범위인 텍스트, 수식, 이미지, 표 구조화, Markdown 변환에 더 넓게 대응하기 위해서이다.
- Marker는 PDF를 Markdown/JSON 계열 구조로 변환하는 흐름에 적합하며, 후처리 파이프라인과 연결하기 좋다.
- Nougat은 수식 중심 과학 문서에 장점이 있지만, 현재 목표에서는 전체 문서 구조와 표/이미지 처리가 함께 중요하다.
트레이드오프:
- Nougat 기반 수식 변환 품질을 기본값으로 활용하지 않는다.
- Marker 결과 품질이 부족한 문서 유형에 대비해 향후 fallback adapter를 열어두어야 한다.
- Marker와 관련 모델의 라이선스와 Windows/GPU 실행 제약은 별도 검증이 필요하다.
ADR-002: 1차 목표는 Windows Native Local Execution
결정: 1차 MVP는 Windows native 환경에서 완전 로컬로 실행한다.
이유:
- 현재 목표 사용 환경이 Windows이며, 개인 프로젝트로 로컬 문서 처리를 우선하기 때문이다.
- 외부 API 의존을 제거하면 개인정보, 비용, 네트워크 실패 문제를 줄일 수 있다.
- VRAM 8GB 환경을 기준으로 chunk 처리와 배치 크기 제어를 설계할 수 있다.
트레이드오프:
- 외부 API 기반 LaTeX 복구, 이미지 설명, 품질 검토는 1차 범위에서 제외한다.
- Windows native에서 일부 ML 의존성 설치가 까다로울 수 있다.
- GPU OOM과 CPU fallback 정책을 반드시 고려해야 한다.
ADR-003: Obsidian 친화 Markdown을 출력 표준으로 채택
결정: 변환 결과는 Obsidian에서 바로 탐색 가능한 Markdown 문서 묶음으로 출력한다.
이유:
- 사용자가 변환 결과를 개인 지식 관리와 AI Agent 탐색에 활용하려는 목적에 맞다.
- 내부 링크, heading 기반 이동, 이미지 embed, 수식 렌더링을 활용할 수 있다.
- 긴 PDF를 여러 Markdown 파일과 index로 나누는 구조와 잘 맞는다.
트레이드오프:
- 순수 GitHub Markdown만 목표로 할 때보다 링크/이미지/수식 규칙을 더 신중하게 정해야 한다.
- Obsidian 내부 링크와 표준 Markdown 링크 사이의 호환성 정책이 필요하다.
- 파일명 slug, heading anchor, 이미지 경로 규칙을 프로젝트 표준으로 고정해야 한다.
ADR-004: 내부 Document Model과 Source Provenance를 사용
결정: Marker 출력물을 바로 최종 Markdown으로 저장하지 않고 내부 Document Model을 거쳐 렌더링한다.
이유:
- parser engine 교체 가능성을 유지하기 위해서이다.
- Markdown 출력, index 생성, 품질 검증, 재시도, 로그 진단을 동일한 구조 위에서 처리할 수 있다.
- AI Agent가 변환된 문장을 원본 PDF page, block id, bbox, line 위치와 연결할 수 있어야 한다.
트레이드오프:
- 초기 구현량이 늘어난다.
- Document Model schema를 먼저 정의해야 한다.
- Marker 원본 출력과 내부 모델 사이의 매핑 오류를 테스트해야 한다.
ADR-005: CLI/Library First, PyQt UI Second
결정: 1차는 CLI와 라이브러리 변환 엔진을 먼저 만들고, PyQt UI는 2차 목표로 둔다.
이유:
- 변환 품질과 테스트 자동화가 UI보다 먼저 안정화되어야 한다.
- CLI/라이브러리 계층이 안정적이면 PyQt UI는 얇은 호출 계층으로 만들 수 있다.
- Harness/TDD 기반 검증 흐름과 잘 맞는다.
트레이드오프:
- 초기 사용자 경험은 UI보다 제한적이다.
- UI 관련 상태 관리와 진행률 표시 설계는 후속 단계에서 다룬다.
ADR-006: Chunked and Resumable Conversion
결정: 긴 PDF는 기본적으로 20페이지 단위 chunk로 나누고, chunk별 상태와 캐시를 보존한다.
이유:
- AI Agent가 긴 문서를 한 번에 읽기 어렵고, 변환도 오래 걸리기 때문이다.
- GPU VRAM 8GB 환경에서 큰 문서를 안정적으로 처리하려면 chunk 단위 작업이 필요하다.
- 실패한 chunk만 재시도할 수 있어야 실사용성이 높다.
트레이드오프:
- chunk 경계에서 문단, 표, 그림, 수식이 걸칠 수 있다.
- chunk 결과를 합쳐 index를 만들 때 page range와 heading 연결을 신중히 처리해야 한다.
- 캐시 무효화 정책이 필요하다.