Document Parser 운영과 개선

진행 기간: 2026.05–현재

PDF·이미지·오피스 문서를 LLM이 다룰 수 있는 Markdown으로 변환하는 Document Parser를 담당했다. OCR 제품을 만드는 게 아니라 OCR을 활용해 문서를 Markdown으로 변환하는 서비스다.

• 스택: Python 3.11, FastAPI, docling(+TableFormer), 멀티프로세스 워커 풀, Docker(CUDA)/GPU
• 입력: PDF / DOC(X) / PPTX / XLSX / HWP / CSV / 이미지 → markdown
• 한국어는 NHN Cloud OCR, 일본어는 PaddleOCR을 내부 호출
• 품질 기준: 변환 결과가 기준 출력과 얼마나 일치하는지 0부터 1까지 점수로 측정하며, 아래 출력 품질 검증에서 0.95 이상을 합격으로 판단

진행한 업무 개요

각 항목은 "무엇을 / 어떻게 바꿔 기여 / 결과" 순서로 정리했다.

코드를 고치기 전에 관측과 반복 검증 환경을 먼저 마련했다. 단계별 지표와 로그를 추가하고, 포맷별 대표 샘플 문서를 갖추고, 테스트용 GPU 인스턴스를 발급받아 CLI로 같은 조건에서 반복 검증하는 자동화 환경을 만들었다. 이후 개선을 검증할 때 이 환경을 사용했다. 이 글의 성능 수치는 당시 기록이며, 2026년 10월 문서 보강에서는 동일 조건의 측정 원본을 모두 다시 확인하거나 재실행하지 않았다.

OCR 처리 병렬화

• 문서를 한 번에 하나씩 처리하던 구조를, 여러 워커(작업을 나눠 맡는 별도 프로세스)가 동시에 처리하는 구조로 전환
• 워커를 별도 OS 프로세스로 분리해 각자 GPU 연산 환경을 갖게 하고, GPU 상태를 고려해 워커에 번갈아 분배
• 워커 풀은 한국어·일본어·우선순위 세 종류로 나눠 작업을 보냄
• 워커 수는 인스턴스당 4개로 설정했다. OCR 모델 백엔드가 최대 16개 인스턴스까지 확장되는 점을 고려한 값이다.
• 결과: 운영 환경(인스턴스 8대 × 워커 4개)에서 문서를 동시에 처리할 수 있게 됐다

비대해진 단일 파서 모듈 분해

• 한 덩어리로 커진 파서를 입력 받기 / 적재 / 변환 / markdown 생성 네 단계로 분리
• 결과: 새 형식·변환 경로를 추가할 때 한 단계만 고치면 되도록 변경 비용 축소

관측 체계 구축과 정보 단일화

• 시작 상태: 처리량·처리 시간·워커 상태를 볼 지표와 화면이 없었다. 문제가 생기면 로그를 모아 지난 상황을 추정해야 했다.
• 관측 도입: HTTP 요청과 문서 변환, OCR 호출, 워커 상태 메트릭을 추가했다. 여러 프로세스가 남긴 값을 /metrics 한 곳에서 제공하고, Prometheus로 수집해 Grafana 대시보드에서 확인하도록 구성했다.
• 정리 기준: 지표가 보여주는 요청 수·처리 시간·워커 상태는 로그와 조회 API에서 제거했다. 캐시 구성과 GPU별 워커 배치처럼 지표만으로 확인하기 어려운 디버깅 정보는 조회 API에 남겼다.
• 함정 회피: 비슷해 보여도 의미가 다른 값은 함께 지우지 않았다. 예를 들어 재시작에 걸린 누적 시간은 현재 재시작 중인 상태를 대신하지 못한다. 제거할 코드와 그 값을 사용하는 API를 함께 추적해 정리했다.
• 결과: 운영 상태를 Grafana에서 먼저 확인할 수 있게 됐고, 같은 값이 로그·지표·조회 API에서 서로 달라지는 문제와 중복 로그를 줄였다.

워커 작업 대기 현황 대시보드 정립

문서 변환은 여러 워커에 나눠 처리한다. 작업이 어디에 얼마나 쌓이는지 정확히 봐야 "워커를 늘려야 하나"를 판단할 수 있어, 운영 그래프 화면(Grafana)에 작업 대기 현황 패널을 추가했다.

• 작업은 두 곳에 쌓인다.
  • 대기 작업(pending): 처리를 기다리는 전체 작업. 제한 없이 쌓인다.
  • 전달 버퍼(call_queue): 워커에 곧바로 넘기려고 미리 담아두는 짧은 칸. 크기가 작게 고정돼 있다.
• 그래서 실제로 밀린 양은 대기 작업으로 보고, 전달 버퍼는 "꽉 찼다/아니다" 신호로만 읽도록 해석 기준을 정했다.
• 결과: "대기 칸이 늘 천장을 친다"는 오해(원래 작게 고정된 칸)를 바로잡고, 대기 작업이 계속 늘면 워커를 늘리는 신호로 삼는 판단 근거를 마련했다.

출력 품질 다층 검증 체계 구축

문서를 markdown으로 바꾸는 과정은 OCR 설정이나 라이브러리를 조금만 바꿔도 결과물이 달라지기 쉽다. 그래서 "바꾼 뒤에도 품질이 유지되는지, 혹은 더 좋아졌는지"를 자동으로 확인하는 검증 장치를 두 겹으로 쌓았다.

• 1차: 회귀 검증(바꾸기 전과 달라졌는지 확인)
  • 회귀(regression) 검증은 코드를 바꾼 뒤 출력이 예전과 달라졌는지 비교해, 의도치 않은 품질 저하를 잡는 안전장치다.
  • OCR 응답을 미리 저장해 두고, 새 변환 결과를 기준 출력과 글자 단위로 비교한다.
  • 얼마나 같은지는 코드에서 NED라고 부르는 문자열 유사도로 잰다. 회귀 검증의 지표 함수는 실제로 difflib.SequenceMatcher.ratio()를 사용하며 정규화 Levenshtein 거리가 아니다. 1이면 동일하고, 기존 검증에서는 0.95 이상을 합격선으로 뒀다.
  • 검증은 한 번 쓰고 버리는 GPU 인스턴스에 운영과 똑같은 이미지를 띄워 돌린다. 일부러 출력을 바꾼 변경은 "실패가 아님"으로 따로 표시해 구분한다.
• 2차: 정답지 채점(golden 기준으로 정답에 얼마나 가까운지 확인)
  • 1차만으로는 "출력이 달라졌다"는 알 수 있어도 "좋아졌는지 나빠졌는지"는 모른다. 예전과 다르기만 하면 무조건 실패로 잡기 때문이다.
  • 그래서 사람이 정한 "정답 출력"(정답지, golden)을 따로 두고, 새 결과가 그 정답에 얼마나 가까운지 절대 점수로 잰다.
  • 정답지는 LLM이 초안과 교정안을 만들고 사람이 검수한다. 다만 현재 채점 코드는 미검수·판단 불가 정답지도 점수를 계산해 전체 요약에 포함하므로, 검수 상태를 확인한 뒤 결과를 해석해야 한다. 모든 정답지가 최종 확정됐다는 뜻은 아니다.
• 표는 따로 채점한다
  • 전체 글자 유사도(NED) 하나만 보면 표의 셀이 빠지거나 밀린 오류가 점수에 묻힌다.
  • 그래서 표는 셀 단위로 맞았는지 F1 점수(빠뜨린 것과 틀린 것을 함께 보는 정확도 지표)로 따로 잰다.
• 결과: 품질이 나빠지는 변경은 막고, 품질을 높이는 변경은 안전하게 시도·측정할 수 있는 환경을 만들었다. 라이브러리 업그레이드처럼 위험한 변경도 "검증 장치가 잡아준다"는 전제 위에서 자신 있게 진행할 수 있게 됐다.

안전한 일회성 테스트 환경 구축 (NHN Cloud CLI 자체 제작)

출력 품질 검증을 운영에 영향 없이 돌리려면 운영과 똑같은 환경의 테스트 인스턴스가 필요하다.

• 처음에는 운영 인스턴스 하나를 트래픽에서 빼내(drain) 검증했다. 운영 자원을 점유하고 검증 중 장애 위험이 있어 부담이 컸다.
• 이후 NHN Cloud API를 다루는 CLI 도구를 직접 만들어, 일회성 테스트 인스턴스를 필요할 때 발급하고 검증이 끝나면 종료하는 방식으로 바꿨다.
• 결과: 운영 인스턴스를 건드리지 않아 검증이 안전해졌고, 인스턴스를 검증하는 시간에만 켜 두므로 비용도 줄였다.

워커 RSS 누적 대응

문서 변환 워커의 실제 메모리 사용량(RSS)이 시간당 약 1.4GB씩 계속 늘어나는 문제가 있었다.

• 처음 방어: 워커가 일정 작업 수를 처리하면 종료하고 새로 띄워 OS가 프로세스 메모리를 회수하게 했다. 대신 새 워커가 모델과 캐시를 다시 준비하는 시간이 필요했다.
• 관측: 청크 처리가 끝날 때 gc.collect()를 호출해도 RSS가 줄지 않았고, 프로세스가 종료되면 메모리가 반환됐다. Python 객체 수거와 OS가 보는 RSS는 다른 계층이라는 점을 확인했다.
• 대응: 메모리 정리 함수를 한곳으로 모으고 gc.collect() 뒤에 glibc의 malloc_trim을 호출했다. 운영 중 기능을 끌 수 있도록 환경 변수도 두고, 워커 교체는 안전장치로 유지했다.
• 확인: 워커당 최대 작업 수를 3건에서 20건, 다시 100건으로 올렸다. 이후 79일 동안 100만 건이 넘는 요청을 처리한 구간에서 호스트 메모리가 장기간 계속 증가하지 않았고, malloc_trim이 실제 메모리를 반환한 호출도 확인했다.
• 부수 확인: 메모리가 급증하면 전체 프로세스를 재시작하던 보호 로직이 적용 이후 거의 동작하지 않는 것도 함께 확인했다.
• 해석 범위: malloc_trim을 끈 비교군을 같은 기간에 운영하지 않아 결과를 이 호출 하나의 효과로 분리할 수는 없다. 워커 교체 정책과 트래픽 분포가 함께 작용했을 가능성을 남겼다.
• 상세: Python 서버 RSS가 줄지 않을 때 malloc_trim을 적용한 과정

일본어 OCR(PaddleOCR) 오류 복구 구조 개선

• 오류를 같은 프로세스 안에서 잡아 이어가는 대신, 캐시·GPU 메모리를 정리하고 워커를 종료한 뒤 감시 장치가 새 워커를 띄우는 방식으로 전환
• 사유: 오류가 난 뒤에는 OCR 엔진·GPU 상태가 오염돼 같은 프로세스에서 안전하게 복구할 수 없음
• 결과: 한 번의 OCR 오류가 뒤따르는 요청까지 오염시키는 문제 방지

코드 변경 검증·리뷰 자동화

• 사내 GitHub Enterprise 환경의 자체 실행기에 자동 테스트와 코드 리뷰를 붙이고, 인증·호스트 관련 문제를 디버깅해 안정화

정답지 재검수와 OCR 입력 품질 개선

• 정답지 24건을 원본과 다시 대조해, 파서가 놓친 구간이 정답으로 굳어 있던 문제를 발견
• 같은 결과를 다시 채점하자 평균 NED가 0.9912에서 0.9822로, 최저 NED가 0.8804에서 0.6826으로 내려가 실제 결함이 수치에 드러남
• 읽기 순서 붕괴, 하단 각주 누락, 참고문헌 절단, 작은 OCR 영역 오인식으로 원인을 분리
• OCR 영역 렌더 배율을 1배에서 3배로 올려 한 목차 표의 표 셀 F1을 0.8214에서 1.0으로 개선

변환 실패 응답 계약 정리

• 두 변환기가 모두 실패해도 HTTP 200과 빈 markdown을 돌려주던 구조를 수정
• 흡수한 변환 실패를 status="error"와 reason으로 드러내고, 실패 사유별 HTTP 상태코드로 분리
• 정상적인 빈 문서와 변환 실패가 같은 분류에 쌓이지 않게 해 호출자 재시도와 운영 집계 기준을 정리

지원 형식과 검증 표본 정합

• 2026년 9월 1일 기준으로 jpg, webp, csv, doc, ppt, txt 회귀 표본을 보강 중
• 표본 목록과 실제 파일의 불일치를 자동 검사하고, 오류 분류에서 회복된 파일을 다시 검증 대상으로 돌리는 절차를 정비 중
• CSV 제목에 업로드 임시 파일명이 노출되는 결함을 표본 보강 과정에서 발견해 수정

Claude Code 활용과 업무 skill화

위 작업들을 빠르게 반복할 수 있었던 큰 이유는 Claude Code를 적극 활용하고, 자주 하는 작업을 재사용 가능한 skill로 만든 것이다.

• 반복되는 운영·검증·문서 작업의 절차를 skill로 정리해, 같은 작업을 매번 처음부터 하지 않고 호출만으로 처리
• 직접 만든 CLI 도구(NHN Cloud·Dooray 등)를 Claude Code에서 호출해 인스턴스 발급·검증·보고 같은 손이 많이 가는 작업을 자동화
• 결과: 진단 → 검증 → 문서화로 이어지는 사이클을 빠르게 돌려, 분석·설계에 집중하고 반복 작업 비용을 줄였다

사내 기술 세미나로 운영 지식 공유

2026년 8월 31일 사내 랩 세미나에서 Document Parser 안정화 및 개선기를 발표했다. 기능 목록을 나열하기보다, 큰 문서에서 워커가 종료되던 문제를 관측 가능한 상태로 바꾸고 검증 자동화까지 이어 간 흐름을 17쪽으로 구조화했다.

• 관측할 수 없던 워커 메모리와 실패 건수를 지표로 만들고, 요청 ID와 단계별 처리 시간으로 병목을 추적한 과정
• Python 객체 수거만으로는 줄지 않던 RSS를 분석하고, 프로세스를 자주 재시작하던 방식에서 메모리를 직접 반환하는 방식으로 바꾼 근거
• Unit·Regression·Quality·LLM as Judge가 각각 어떤 질문에 답하는지와 적용 위치
• 운영 인스턴스를 건드리지 않고 검증 인스턴스 생성부터 회귀·품질·성능 측정, 종료까지 CLI로 묶은 과정

발표를 준비하면서 흩어져 있던 장애 대응, 설계 결정, 검증 기준을 하나의 이야기로 다시 검토했다. 운영 문제를 해결하는 데서 끝내지 않고, 다른 개발자가 판단 근거와 검증 방법을 재사용할 수 있는 지식으로 전환했다.

협업·운영

• 운영 지표는 사내 Prometheus와 Grafana 화면으로 보고, 작업 추적은 사내 협업 도구로 관리

진행 중

• 파일 형식과 문서 특성이 다른 표본을 정하고, 파싱 단계별 처리 시간을 측정해 병목을 찾고 있다.
• Codex와 Claude Code의 심층 검색으로 개선 후보를 찾고 있다.
• 후보를 하나씩 적용한 뒤 같은 표본으로 처리 시간을 다시 측정해 실제 개선 여부를 확인하고 있다.