Playground 문서 파싱 파이프라인 — 기여 개요

진행 기간: 2026.05 ~ (진행 중)

AI 서비스 개발팀의 사내 LLM 워크플로 제품 Playground는 다양한 형식의 문서를 입력으로 받는다. 이 입력을 LLM이 다룰 수 있는 markdown으로 정규화하는 문서 파싱 서비스를 맡아 운영·개선했다. 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 점수, 항목 5에서 설명) 0.95 이상

진행한 업무 개요

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

1. OCR 처리 병렬화

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

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

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

3. 관측 정보 단일화

• 무엇: 요청 하나가 처리되는 과정이 지표(Prometheus)·로그·조회 API 세 곳에 동시에 기록되던 구조를, 지표(Grafana 화면) 한 곳으로 통일
• 정리 기준: 지표가 이미 보여주는 정보(요청 수·처리 시간·워커 상태)는 로그·조회 API에서 제거하고, 지표로 표현할 수 없는 디버깅 정보(캐시 상태·워커의 GPU 배치·재시작 여부)만 조회 API에 남김
• 함정 회피: 비슷해 보여도 의미가 다른 지표는 함께 지우지 않음 — 예를 들어 "재시작에 걸린 누적 시간"은 "지금 재시작 중인가"를 대체하지 못한다. 지울 코드와 그것을 쓰는 유일한 API를 한 묶음으로 식별해 정리
• 결과: 같은 정보가 여러 곳에서 서로 어긋나는 문제와 불필요한 로그 누적 제거, 메트릭이 대체하는 중복 조회 API 제거

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

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

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

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

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

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

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

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

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

7. 워커 메모리 누수 진단·해결

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

• 처음 방어: 워커가 일정 작업 수를 처리하면 강제로 종료하고 새로 띄워, OS가 죽은 프로세스의 메모리를 회수하게 했다. 누수는 막지만 새 워커마다 모델 로드·캐시 초기화 비용(예열)이 다시 든다.
• 원인 파악: gc.collect()를 이미 부르고 있는데도 메모리가 안 줄었다. 진단해 보니 Python의 gc.collect()는 OS로 메모리를 돌려주는 동작이 아니고, 작은 메모리 조각들이 OS로 반환되지 않은 채 프로세스 메모리 영역에 흩어져 쌓이는(단편화) 것이 원인이었다.
• 해결: 메모리 정리 의도를 한 함수로 묶어(gc.collect() + OS 반환을 유도하는 malloc_trim) 흩어진 호출을 일괄 교체했다. 운영 중 즉시 끌 수 있게 환경변수로 토글 가능하게 뒀다.
• 결과: RSS가 계속 증가하던 패턴이 사라지고 일정 범위에서 진동, 회귀 0건. 워커 강제 종료에 기대던 예열 비용 의존을 줄였다.
• 상세: Python 서버 RSS 가 안 줄어들어 malloc_trim 을 박은 이야기

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

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

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

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

작업 방식 — Claude Code 활용과 업무 skill화

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

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

협업·운영

• 운영 지표는 사내 Prometheus + Grafana 화면으로 보고, 작업 추적은 사내 협업 도구로 관리
• 코딩 규칙: 비동기 처리 중 동기 입출력 금지(별도 실행기로 위임), 자주 실행되는 경로에 로그 금지, OCR 설정 변경 시 출력 바이트 단위 비교 필수

진행 중·다음 단계

• 진행 중 항목(설정 마이그레이션, 표 인식 모델 v2, OCR API Gateway 제거)은 완료 후 별도 정리