MiniCPM-OCR SDK v1.0.4: 페이지별 JSON 출력, 적응형 회전 기본값

1. 페이지 결과를 온라인 응답 구조에 맞춘다

v1.0.4 릴리스는 2026년 11월 3일 공개됐다. 각 페이지의 JSON 파일이 pages_json/<image_id>.json 경로에 추가로 기록된다. 구조는 온라인 문서 파싱 API의 단일 페이지 응답과 일치하도록 맞췄다.

응답에는 페이지 번호, 인식된 내용, 문서 속 인식 영역인 블록의 목록, 회전 정보와 사용량이 포함된다. 로컬에서 저장한 파일과 온라인 응답이 같은 항목을 갖게 되므로, 후속 프로그램은 결과를 읽는 틀을 공유하기 쉬워진다.

2. 페이지별 결과를 문서 전체로 묶는다

파일을 지정해 JSON을 얻는 명령과 페이지별 결과를 조립하는 함수가 추가됐다. 릴리스 노트는 이들이 만드는 전체 결과를 요청 후 결과를 받는 온라인 비동기 작업의 결과와 같은 구조로 맞췄다고 설명한다. 페이지별 저장에 더해 문서 전체를 한 번에 다룰 수 있는 출력도 제공하는 변화다.

minicpmvocr parse --json FILE
assemble_document_json()

첫 줄은 지정한 파일을 처리하는 명령이고, 둘째 줄은 조립 함수 이름이다. 페이지 하나씩 넘기는 작업에는 개별 파일을 활용하고, 문서 전체를 전달하는 작업에는 조립된 결과를 활용하는 식으로 후처리를 구성할 수 있다.

3. 블록 상태와 회전 기록을 일관되게 남긴다

블록 상태값은 네 종류로 통일됐다. 인식 실패와 잘라낸 이미지 영역이 없는 경우는 모두 failed로 표시하되 구체적인 이유는 실행 로그에 남긴다. 인장 인식을 끄면 인장 블록은 skipped_seal로 기록된다.

후속 프로그램에서는 상태값으로 실패한 영역을 찾고, 운영자는 로그로 원인을 좁혀볼 수 있다. 실패 표시와 상세 원인을 서로 다른 곳에서 읽도록 역할이 나뉜 셈이다.

회전 정보는 ocr.rotation에 남으며 온라인 응답의 필드와 같은 기준을 따른다. 페이지별 결과 안에서 인식 영역의 상태와 방향 보정 내역을 함께 읽을 수 있어 인식 결과를 다음 단계에서 다듬는 후처리가 확인할 위치도 일정해진다.

4. 자동 방향 보정은 편의와 실행 비용을 함께 바꾼다

방향 보정은 기본으로 켜지고, 빠른 시작 과정에서는 Paddle 방향 보정 모델 3개를 자동으로 내려받는다. 별도로 회전 기능을 켜고 모델을 준비하는 수고를 줄이는 대신, 실행 환경에는 모델 다운로드와 방향 보정 단계가 추가된다.

이미지가 작으면 회전을 건너뛰며, paddleocr가 없으면 회전 정보를 사용할 수 없다. 이 모듈이 설치되지 않았을 때는 오류로 중단하지 않고 경고를 남긴 뒤 방향 보정을 생략한다.

5. 평가를 재현할 때는 회전 설정을 명시한다

기존 평가를 이어가는 개발자는 입력 방향을 그대로 둘지, 자동으로 바로잡을지 먼저 정할 수 있다. 릴리스 노트는 OmniDocBench 점수를 재현할 때 방향 보정을 끄도록 권고한다. 회전 없는 결과가 필요한 처리 흐름에서도 다음 설정으로 보정을 끌 수 있다.

--set upright.enabled=false

자동 보정을 사용하는 작업은 모델 준비와 보정 단계를 실행 환경에 반영하고, 평가를 재현하는 작업은 권고된 설정을 적용하는 식이다. 출력 구조를 맞추는 변경과 입력 방향을 바꾸는 기본 동작을 각각 후처리와 실행 설정에 반영하면 된다.

v1.0.4의 실질적인 변화는 페이지별 결과의 연결성을 높이는 동시에 방향 보정을 기본 처리 단계로 편입한 데 있다.