HWP 마크다운 변환, 병합 표를 살리는 kordoc 사용법

병합 관계를 남기려면 HTML 표를 유지한다

HWP·HWPX 표의 병합 관계가 필요하다면 HTML 표가 포함된 Markdown을 받아야 한다. 글자만 복사하면 여러 행에 걸친 머리글이 어느 숫자에 적용되는지 구분하기 어려워질 수 있다.

kordoc은 문서 구조를 읽어 Markdown으로 바꾸고, 병합은 rowspan·colspan이 있는 HTML 표로 나타낸다. Markdown 파일 안에 HTML이 들어가는 방식이다. 모든 표를 HTML로 받으려면 --html-tables 옵션을 쓴다.

반대로 HTML을 받지 않는 검색 시스템에는 --table-format gfm을 선택할 수 있다. 사용 문서에 따르면 세로 병합 셀은 덮인 행마다 같은 값을 쓰고, 가로 병합 셀은 시작 칸에만 값을 둔다. 중첩 표는 부모 표 뒤의 독립 표로 꺼내며 관계 표지를 남긴다. 원래의 병합 모양을 그대로 저장하는 출력은 아니다.

읽을 파일과 검색에 넣을 데이터를 나눠 받는다

기본 변환에는 Node.js 20 이상이 필요하다. 문서의 CLI 예시를 적용하면 다음처럼 출력 목적을 나눌 수 있다.

npx kordoc report.hwp -o report.md
npx kordoc report.hwpx --html-tables -o report-tables.md
npx kordoc report.hwpx --table-format gfm -o report-gfm.md
npx kordoc report.hwpx --format json
npx kordoc report.pdf --format chunks

Markdown은 사람이 읽을 변환본, JSON은 블록·쪽·메타데이터를 받는 경로다. chunks는 제목 경로와 독립 표 청크를 내보내 검색 증강 생성(RAG)의 입력으로 쓸 수 있다. HTML 표와 GFM 표 옵션은 함께 쓰지 않는다.

예를 들어 여러 사업 행 위에 하나의 부서명이 병합돼 있다면, HTML 출력에서는 병합 범위를 확인하고 GFM 출력에서는 각 행의 부서명 배치를 확인하는 식이다. 이는 변환본을 점검할 때 쓸 수 있는 예시다. 표 모양을 보존할지, 행마다 검색할 데이터를 만들지에 따라 선택이 달라진다.

HWPX의 10,342개 표와 OCR의 67개 표는 다른 시험이다

개발자가 공개한 검증 기록은 원본 구조가 있는 문서와 이미지에서 읽은 문서를 나눠 평가한다. ‘표 구조 100%’라는 숫자를 스캔 문서 전체에 적용하면 결과를 잘못 읽게 된다.

표 구조 일치는 셀의 내용이나 화면 배치가 모두 같다는 뜻도 아니다. 원본 HWPX를 받을 수 있는 업무와 스캔 PDF만 있는 업무는 확인할 결과가 달라진다. AI에 넘기기 전에는 원본 유형을 구분하고, 병합 머리글 아래의 값이 올바른 행·열에 연결됐는지 확인하는 편이 유용하다.

통신 차단 전에 OCR 모델까지 반입해야 한다

내장 OCR은 API 키 없이 로컬 CPU에서 실행된다. 다만 처음 필요한 모델을 내려받는 과정과 문서 변환 자체는 구분해야 한다. 폐쇄망 배포 문서는 반입 대상과 같은 OS·CPU에서 번들을 만들고, OCR 엔진과 캐시된 모델을 함께 준비하도록 안내한다.

KORDOC_OFFLINE=1은 kordoc의 모델 다운로드와 webhook 요청을 보내기 전에 막는다. 모델이 없는 상태에서 이 설정만 켠다고 OCR이 준비되지는 않는다. models --status로 상태를 확인할 수 있으며, 선택형 서버 검출 모델과 손글씨 모델은 기본 모델 묶음에 포함되지 않아 별도 반입이 필요하다.

MCP 파일 접근 범위는 KORDOC_ROOT로 제한한다. 이 두 설정은 kordoc의 동작 범위에 적용된다. 변환한 내용을 외부 AI 대화에 전달하는 클라이언트의 통신까지 차단하는 설정은 아니다.

변환본을 고를 때는 병합 범위를 유지할 HTML이 필요한지, 행마다 값을 다룰 GFM이 필요한지를 먼저 정한다. 스캔 문서는 그 출력 선택에 앞서 표의 행·열과 병합 영역이 제대로 인식됐는지도 확인해야 한다.