MinerU GitHub 추천: PDF·DOCX를 RAG·Agent용 데이터로 바꾸는 문서 파서

 

MinerU GitHub 추천: PDF와 Office 문서를 RAG·Agent용 Markdown/JSON으로 바꾸기

설치, 첫 테스트, MCP 연동, 사내 문서 리스크까지 보는 실무 도입 메모

 

MinerU GitHub 추천: PDF와 Office 문서가 RAG 품질을 흔들 때

 

MinerU는 PDF, DOCX, PPTX, XLSX, 이미지, 웹 페이지를 LLM이 다루기 쉬운 Markdown·JSON으로 바꾸는 오픈소스 문서 파싱 엔진입니다. 2026년 6월 11일 GitHub API 기준 `pushed_at`은 2026-06-11T03:08:03Z였고, 최신 공개 릴리스 `mineru-3.2.3-released`는 2026년 6월 4일 게시됐습니다.

PDF를 RAG에 넣어 본 사람이라면 비슷한 장면을 봅니다. 본문보다 헤더와 페이지 번호가 더 크게 잡히고, 표는 한 줄 문장처럼 눌려 버리며, 스캔본 OCR 결과가 검색 품질을 흔듭니다. 이때 모델 크기보다 먼저 봐야 할 것은 원문을 쓸 만한 구조로 풀어 주는 파서입니다.

MinerU GitHub PDF DOCX RAG Agent document parser를 찾는 독자는 저장소 이름만 보고 판단하기 어렵습니다. 로컬 설치가 되는지, DOCX와 PPTX도 처리되는지, 생성된 Markdown과 JSON을 벡터DB 앞단에 둘 수 있는지, Cursor나 Claude Desktop 같은 Agent 흐름에 붙일 수 있는지까지 확인할 일이 남습니다.

저라면 데모 문구보다 출력물부터 열어 봅니다. 한국 회사 문서는 결재선, 표 병합, 스캔 도장, 각주가 한 파일 안에 같이 들어오는 경우가 많습니다. `*.md`, `content_list.json`, `layout.pdf`가 원문 구조를 얼마나 살리는지 본 뒤에 MCP나 Agent 연동으로 넘어가도 늦지 않습니다.

 

 

2026년 6월 기준으로 볼 신호

 

2026년 6월 11일 기준 MinerU에서 볼 신호는 Office 포맷 지원, VLM+OCR 기반 파싱, RAG·Agent 생태계 연결, MCP 서버 흐름이 한 저장소 주변에 모였다는 점입니다.

MinerU의 공개 맥락은 2024년 9월 arXiv 기술 보고서에서 시작됐습니다. 2026년에 다시 볼 부분은 논문보다 사용 경로입니다. 3월에는 DOCX 파싱과 pipeline backend 변화가 있었고, 4월에는 PPTX·XLSX 네이티브 파싱과 VLM 모델 업그레이드가 있었습니다. 6월 `mineru-3.2.3`에는 위첨자·아래첨자 감지 출력과 post-OCR fallback 처리가 들어갔습니다.

2026년 6월 11일 GitHub API 기준 `pushed_at`은 2026-06-11T03:08:03Z였고, 확인 시점 별 수는 67,192개였습니다. 웹 UI에서는 별 수가 67.2k처럼 반올림되어 보일 수 있으니 숫자를 인용할 때는 확인 시점을 붙이는 편이 낫습니다.

제가 보기에는 별 수 그래프보다 출력 폴더가 더 빠른 판단 재료입니다. PDF, DOCX, 스캔본, 표 많은 보고서를 넣었을 때 `*.md`, `content_list.json`, `layout.pdf`가 읽을 만하게 나오는지 확인해야 합니다. 한국 독자에게는 그 결과가 MinerU 평가의 첫 기준에 가깝습니다.

 

RAG 앞단의 문서 정리

 

MinerU는 PDF·Office 파일에서 읽기 순서, 표, 수식, 이미지, OCR 결과를 남기고, 출력물을 RAG 후처리에 쓰기 쉬운 Markdown·JSON 형태로 정리합니다.

기능 범위는 일반 PDF 텍스트 추출보다 넓습니다. 헤더, 푸터, 페이지 번호 제거, 복잡한 레이아웃의 읽기 순서 출력, 이미지·표·수식 추출, 수식의 LaTeX 변환, 표의 HTML 변환, 스캔 또는 깨진 PDF OCR, 109개 언어 OCR, 시각화 파일 출력까지 포함합니다. 실행 환경도 Windows, Linux, macOS와 CPU/GPU/NPU/MPS를 함께 적고 있습니다.

다만 한국어 문서는 별도 샘플로 확인하는 편이 맞습니다. CLI에는 OCR 언어 선택지로 `korean`이 보이고, 문서 홈은 109개 언어 OCR을 말합니다. 한국 공공기관 양식이나 국내 기업 문서에 특화됐다는 근거는 없습니다. 제 테스트라면 10~20페이지 샘플에서 줄바꿈, 표 셀, 도장 이미지, 각주, 스캔 품질을 기록합니다. 국내 문서는 표 위에 결재란이 붙고, 본문 중간에 도장 이미지와 각주가 섞이는 경우가 많아서 영어 논문 PDF만으로 판단하면 놓치는 부분이 생깁니다.

본문 텍스트만 빨리 뽑는 작업에는 더 가벼운 도구가 맞을 수 있습니다. MinerU를 볼 이유는 표, 수식, 다단 레이아웃, Office 파일, 이미지가 섞인 문서를 RAG에 넣어야 할 때 생깁니다.

 

 

설치와 첫 테스트는 작게 시작하기

 

첫 검증은 Python 3.10~3.13 환경에서 uv 기반으로 `mineru[all]`을 설치하고, 작은 PDF나 DOCX를 `mineru -p 입력경로 -o 출력경로`로 처리한 뒤 md와 content_list.json을 확인하는 정도가 적당합니다.

로컬 설치는 pip 갱신, uv 설치, `uv pip install -U "mineru[all]"` 순서로 잡습니다. PyPI 메타데이터에는 `mineru` 3.2.3 패키지의 Python 요구 조건이 `>=3.10,<3.14`로 표시됩니다. 소스 설치가 필요하면 GitHub 저장소를 clone한 뒤 `uv pip install -e .[all]` 경로를 씁니다.

처음부터 큰 문서 묶음을 돌리면 원인 추적이 어려워집니다. 5~10페이지짜리 PDF 하나, 표가 있는 DOCX 하나를 골라 `mineru -p sample_pdf -o out_dir`처럼 실행합니다. CPU만 있는 환경이라면 문서 예시처럼 `-b pipeline`을 붙여 pure CPU 경로의 속도와 결과를 봅니다. CLI 도움말 기준 backend 선택지는 `pipeline`, `vlm-engine`, `hybrid-engine`, `vlm-http-client`, `hybrid-http-client`이고 기본 backend는 `hybrid-engine`입니다.

테스트가 끝나면 Markdown 하나만 읽고 닫지 않습니다. `*.md`는 RAG 인덱싱 후보, `content_list.json`은 텍스트·이미지·표 같은 단순화된 구조 확인, `layout.pdf`와 `span.pdf`는 레이아웃 추출을 눈으로 보는 파일입니다. 한글 PDF 한 개와 표가 많은 DOCX 한 개는 샘플에 넣는 쪽이 안전합니다. 후처리 코드를 만들 계획이면 `middle.json`과 `model.json`도 따로 봅니다.

 

 

운영 모델: CLI, FastAPI, Gradio, MCP

 

개인 검증은 CLI나 Gradio로 충분한 경우가 많고, 팀 파이프라인은 FastAPI로 붙이는 그림이 더 또렷합니다. Cursor·Claude Desktop·Windsurf 같은 Agent 작업에는 MinerU-Ecosystem의 MCP 서버 흐름을 따로 봐야 합니다.

문서 몇 개를 혼자 확인할 때는 CLI가 가장 단순합니다. 비개발자와 업로드 결과를 같이 봐야 하면 `mineru-gradio --server-name 0.0.0.0 --server-port 7860`으로 WebUI를 엽니다. 내부 서비스에 붙일 때는 `mineru-api --host 0.0.0.0 --port 8000`으로 FastAPI 서버를 띄우고 `/health`, `/tasks`, `/file_parse` 같은 엔드포인트를 확인합니다.

MCP로 넘길 문서에서는 조건이 달라집니다. MinerU-Ecosystem은 Claude Desktop, Cursor, Windsurf, 호환 MCP 클라이언트용 MCP 서버를 문서화하고, `uvx mineru-open-mcp` 설정과 streamable HTTP 모드 포트 8001을 안내합니다. flash mode는 API key 없이 파일당 20페이지와 10MB 무료 제한 안에서 쓸 수 있고, precision/API-token workflow에는 `MINERU_API_TOKEN`이 필요하다고 설명합니다.

국내 팀에서 자주 막히는 지점은 데이터가 어디를 지나가느냐입니다. 사내 문서를 로컬 CLI로만 처리할지, FastAPI를 내부망에 둘지, MCP flash mode나 precision API 사용으로 외부 전송이 생기는지에 따라 보안 검토 범위가 달라집니다. 이 선을 초반에 그어 두지 않으면 기술 검증을 통과해도 운영 단계에서 멈출 수 있습니다.

 

RAG와 Agent workflow에서의 자리

 

RAG 파이프라인에서는 MinerU를 벡터DB 앞단의 문서 전처리 단계에 둡니다. LangChain·LlamaIndex를 이미 쓰는 팀은 MinerU-Ecosystem의 로더와 리더부터 비교하면 됩니다.

RAG 파이프라인에서 MinerU의 자리는 업로드 직후, 청킹과 임베딩 전입니다. `*.md`는 일반 청킹에, `content_list.json`은 이미지·표·문단 타입을 나누는 후처리에, `layout.pdf`와 `span.pdf`는 품질 검수에 둡니다. 자체 파서를 덧댈 계획이라면 `middle.json`의 비중이 커집니다.

MinerU-Ecosystem은 `langchain-mineru`와 `llama-index-readers-mineru`도 문서화합니다. LangChain 쪽은 `MinerULoader`가 flash mode를 기본으로 쓰고 precision mode에는 token, pages, split_pages 옵션이 있다고 설명합니다. LlamaIndex 쪽은 PDF, Word, PPT, image, Excel 파일을 MinerU로 처리해 LlamaIndex Document 객체로 반환하는 reader로 제시됩니다.

제품 매뉴얼 PDF, 표 많은 보고서, PPTX 교육자료, XLSX 운영문서가 섞인 사내 지식검색 PoC에서는 샘플별 차이가 금방 드러납니다. 모든 원문을 이미 Markdown으로 관리하는 팀은 MinerU를 붙여도 새로 얻는 효용이 작을 수 있습니다. 한국 회사에서 흔한 '최종본_v3_진짜최종.pdf'류 문서까지 다뤄야 한다면, 도구 선택 전에 샘플 묶음부터 잘 잡아야 합니다.

 

 

 

도입 전 리스크: 성능, 라이선스, 민감 문서

 

GPU가 없으면 일부 VLM 경로를 쓰기 어렵거나 CPU pipeline의 속도를 감수해야 합니다. 라이선스는 GitHub API의 NOASSERTION과 공식 문서의 MinerU Open Source License 설명을 함께 확인하는 쪽이 안전합니다.

리스크는 설치 실패보다 결과 품질에서 먼저 드러나는 경우가 많습니다. Quick Start는 문서 파싱이 어렵고, 복잡한 레이아웃, 스캔 페이지, 손글씨 문서에서 기대보다 낮은 결과가 나올 수 있다고 안내합니다. 환경 표도 가볍지 않습니다. Python 3.10~3.13, RAM 최소 16GB와 권장 32GB 이상, pipeline disk space 20GB 이상과 SSD 권장을 적고 있습니다. CPU 실행은 pipeline/hybrid 경로에서 가능하지만 VLM engine 경로와는 조건이 다릅니다.

라이선스도 한 줄로 처리하면 곤란합니다. GitHub API metadata는 license `spdx_id`를 NOASSERTION/Other로 돌려주고, 공식 문서는 Apache 2.0에 추가 조건을 둔 MinerU Open Source License를 설명합니다. 회사 제품에 붙이거나 고객 데이터 처리에 넣으려면 저장소의 LICENSE, 공식 문서, 법무 검토를 함께 봐야 합니다.

개인 실험은 샘플 결과만으로도 다음 결정을 내릴 수 있습니다. 사내 문서 RAG는 기준이 더 엄격합니다. 로컬 CLI 샘플, 내부 FastAPI 서버, MCP flash/precision 모드, API 토큰이 필요한 흐름은 데이터 이동 경로가 다릅니다. 설치 성공보다 로그, 임시 파일, 업로드 위치, API token 사용, 결과 파일 보관 정책을 먼저 정해야 합니다.

 

추천 판단: 써볼 경우와 미룰 경우

 

복잡한 PDF·Office 문서를 RAG와 Agent workflow에 넣는 개인 개발자, AI 서비스 팀, 사내 지식검색 PoC 팀은 MinerU를 짧게 시험해 볼 만합니다. 본문 텍스트 추출만 필요하거나, 낮은 사양에서 대량 처리해야 하거나, 라이선스·보안 검토가 어려운 환경에서는 도입 순서를 뒤로 미루는 쪽이 현실적입니다.

판단 항목	써볼 만한 경우	미룰 만한 경우
문서 유형	PDF, DOCX, PPTX, XLSX, 이미지가 섞임	이미 Markdown이나 깨끗한 텍스트로 정리됨
RAG 목표	표, 수식, 이미지, 읽기 순서를 살리고 싶음	본문 텍스트만 빠르게 뽑으면 됨
운영 방식	CLI, FastAPI, Gradio, MCP 중 하나를 선택할 수 있음	외부 API·토큰·로컬 서버 검토가 불가능함
품질 검수	md와 content_list.json 외에 layout.pdf, span.pdf를 볼 수 있음	샘플 검수 없이 전체 인덱싱해야 함

MinerU GitHub PDF DOCX RAG Agent document parser를 테스트하는 첫날에는 문서 2~3개만 고릅니다. Markdown과 JSON이 읽을 만하게 나오는지, 원문 구조가 어디서 흐트러지는지 보는 정도면 충분합니다. 원문 구조가 흐트러지면 좋은 검색기와 큰 모델을 붙여도 답변 품질이 쉽게 흔들립니다.

제 기준에서는 한국어 샘플 하나를 꼭 끼워 넣겠습니다. OCR 품질이 낮은 스캔본, 손글씨가 많은 문서, 라이선스 확인이 필요한 상용 제품 내장, 외부 API 전송이 금지된 사내 문서는 작은 샘플과 로컬 경로 검증을 먼저 통과해야 합니다.

 

자주 묻는 질문

 

Q. MinerU는 PDF를 RAG용 Markdown으로 어떻게 변환합니까?
A. 공식 문서 기준 MinerU는 PDF, 이미지, DOCX, PPTX, XLSX 입력을 처리해 Markdown과 구조화 JSON을 출력합니다. RAG에서는 md를 청킹 후보로 쓰고, content_list.json으로 표·이미지·문단 단위를 확인하며, layout.pdf와 span.pdf로 추출 품질을 검수합니다.

Q. 로컬 첫 테스트는 어떤 명령부터 시작하면 됩니까?
A. Python 3.10~3.13 환경에서 `uv pip install -U "mineru[all]"`로 설치한 뒤 `mineru -p sample_pdf -o out_dir`처럼 작은 PDF나 DOCX를 처리합니다. CPU만 쓸 경우 공식 문서의 pure CPU 예시처럼 `-b pipeline`을 붙여 속도와 결과를 비교합니다.

Q. GPU 없이 MinerU를 써도 됩니까?
A. 공식 Quick Start는 pipeline/hybrid 경로에서 pure CPU 실행을 설명하지만, VLM engine 경로는 CPU만으로 같은 조건을 기대하기 어렵습니다. RAM 최소 16GB, 권장 32GB 이상, pipeline disk 20GB 이상 조건도 같이 봐야 합니다.

Q. Cursor나 Claude Desktop에서 MinerU를 쓰는 흐름은 무엇입니까?
A. MinerU-Ecosystem은 Claude Desktop, Cursor, Windsurf, 호환 MCP 클라이언트용 MCP 서버를 문서화합니다. `uvx mineru-open-mcp` 설정과 streamable HTTP 포트 8001 경로가 있으며, flash mode의 무료 제한과 precision mode의 `MINERU_API_TOKEN` 필요 여부가 운영 조건에 들어갑니다.

Q. LangChain이나 LlamaIndex를 이미 쓰는 팀은 어디에 연결해야 합니까?
A. 문서 업로드 직후, 청킹과 임베딩 전에 MinerU를 둡니다. MinerU-Ecosystem은 `langchain-mineru`와 `llama-index-readers-mineru`를 문서화합니다. 기존 파이프라인에서는 loader 또는 reader 단계에 붙여 샘플 문서 결과를 비교하면 됩니다.

Q. 한국어 문서에 바로 써도 됩니까?
A. 공식 문서와 CLI 옵션은 109개 언어 OCR과 korean OCR language 선택지를 보여줍니다. 한국 문서 특화 성능이나 국내 채택은 제공된 출처로 확인되지 않았으므로, 표·도장·각주·스캔 품질이 섞인 10~20페이지 샘플 검수가 필요합니다.

Q. 어떤 경우에는 MinerU 도입을 미뤄야 합니까?
A. 본문 텍스트 추출만 필요하거나, 라이선스 검토 없이 상용 제품에 넣어야 하거나, 민감 문서를 외부 API로 보낼 수 없는 환경인데 로컬 실행 경로도 없다면 도입 우선순위가 낮습니다. 공식 문서도 복잡한 레이아웃, 스캔 페이지, 손글씨 문서의 결과가 기대보다 낮을 수 있다고 안내합니다.

함께 읽으면 좋은 글

 

• Goose GitHub 추천: AI 코딩 에이전트의 프롬프트 인젝션 방어까지 살펴보기 — GITHUB 추천
• rtk-ai/rtk GitHub 추천: AI 코딩 도구 토큰 비용을 줄이는 CLI 프록시 실험 — GITHUB 추천
• repowise GitHub 추천: AI 코딩 에이전트에 코드베이스 지식그래프와 건강도 붙이기 — GITHUB 추천
• Xinference GitHub 추천: 로컬 LLM을 OpenAI 호환 API로 서빙하기 — GITHUB 추천
• Context7 GitHub 추천: AI 코딩 도구에 최신 문서를 넣는 MCP 서버 — GITHUB 추천

참조 링크

 

• opendatalab/MinerU GitHub repository — README feature scope, installation surface, release history, repository identity
• GitHub REST API metadata for opendatalab/MinerU — stars, forks, pushed_at, open issues, default branch, license metadata
• MinerU 3.2.3 release — latest public release date and recent release changes
• MinerU documentation home — feature scope, OCR, platform support, license note
• MinerU Quick Start — installation, environment requirements, first command, limitations
• MinerU Quick Usage — FastAPI and Gradio commands plus endpoints
• MinerU CLI Tools — backend choices and OCR language option
• MinerU Output File Format — md, content_list.json, layout.pdf, span.pdf, model.json, middle.json usage
• opendatalab/MinerU-Ecosystem — MCP server, LangChain, LlamaIndex, Dify/FastGPT/Flowise related workflow
• mineru PyPI package — package version and Python requirement
• MinerU: An Open-Source Solution for Precise Document Content Extraction — technical report timeline and research context