From bb929f88d0f021b8425105acf0635f9ec8870c15 Mon Sep 17 00:00:00 2001 From: hyungi Date: Thu, 18 Jun 2026 15:58:55 +0900 Subject: [PATCH] =?UTF-8?q?feat(extraction):=20MinerU=202.5=20VLM=20?= =?UTF-8?q?=EC=B6=94=EC=B6=9C=20=EC=84=9C=EB=B9=84=EC=8A=A4=20+=20?= =?UTF-8?q?=EC=9B=8C=EC=BB=A4=20=EC=97=94=EB=93=9C=ED=8F=AC=EC=9D=B8?= =?UTF-8?q?=ED=8A=B8=20env=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit marker-service(Surya, ~10GB) 대체 후보. MinerU2.5-Pro-2605-1.2B VLM(vllm-async-engine, ~5.9GB 고정). marker /convert 계약 복제(file_path·start/end·md+base64 images) → 워커는 MARKER_ENDPOINT env 플립만으로 전환. 단일카드(16GB) 검색스택 공존, 40p 윈도우 무변. - services/mineru: Dockerfile(vllm/vllm-openai:v0.21.0 + mineru[core]) + async server.py (NFC/NFD 한글경로 resolver, PyMuPDF page 슬라이스, gpu_memory_utilization 캡) - docker-compose: mineru-service profile-gated(기본 미기동=marker 무영향) + mineru_models vol - marker_worker: MARKER_ENDPOINT 하드코딩 → env(기본 marker, 무변) 격리 PoC A/B 8/8 게이트 PASS (한국어/표/수식LaTeX/heading/figure/40p VRAM). 컷오버(env 플립+marker 제거)는 별 단계(읽기뷰 회귀 0 게이트). Co-Authored-By: Claude Opus 4.8 (1M context) --- app/workers/marker_worker.py | 6 +- docker-compose.yml | 38 +++++ services/mineru/Dockerfile | 45 +++++ services/mineru/server.py | 315 +++++++++++++++++++++++++++++++++++ 4 files changed, 403 insertions(+), 1 deletion(-) create mode 100644 services/mineru/Dockerfile create mode 100644 services/mineru/server.py diff --git a/app/workers/marker_worker.py b/app/workers/marker_worker.py index cc2c70d..6f1055f 100644 --- a/app/workers/marker_worker.py +++ b/app/workers/marker_worker.py @@ -39,7 +39,11 @@ from models.queue import ProcessingQueue logger = logging.getLogger(__name__) -MARKER_ENDPOINT = "http://marker-service:3300/convert" +# 마크다운 추출 엔드포인트. compose env `MARKER_ENDPOINT`(base URL)에서 읽는다 — +# 기본=marker(무변), 컷오버=`http://mineru-service:3301` 로 env 플립만으로 전환. +# marker/mineru 가 동일 /convert 계약(file_path·start/end·md+base64 images)이라 워커 무변. +_MARKDOWN_BASE = os.getenv("MARKER_ENDPOINT", "http://marker-service:3300").rstrip("/") +MARKER_ENDPOINT = _MARKDOWN_BASE if _MARKDOWN_BASE.endswith("/convert") else _MARKDOWN_BASE + "/convert" MARKER_TIMEOUT = 300 # 큰 PDF 5 분 한도 MAX_PAGES = 200 # 소형 1-shot 경로 /convert max_pages 안전장치 diff --git a/docker-compose.yml b/docker-compose.yml index 0f0b349..5fd088a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -87,6 +87,43 @@ services: start_period: 300s restart: unless-stopped + # MinerU 2.5 VLM PDF→markdown 추출 — marker-service 대체 후보(단일카드 markdown VRAM ~10→~5GB). + # profile-gated: 기본 미기동 = marker 무영향. 활성 = `docker compose --profile mineru up -d mineru-service`. + # 컷오버(A/B 8게이트 PASS) 전까지 fastapi depends_on 에 넣지 않는다(격리). 포트 3301 (marker=3300). + mineru-service: + build: ./services/mineru + profiles: ["mineru"] + ports: + - "127.0.0.1:3301:3301" + expose: + - "3301" + environment: + # vlm-engine = 순수 VLM 단일모델. 기본 hybrid-engine 은 다중모델 로드 = OOM(반드시 명시). + - MINERU_BACKEND=vlm-engine + - MINERU_LANG=${MINERU_LANG:-korean} + # 공유 16GB 카드 공존: 절대 VRAM 캡(GB, 공유카드 robust) + vLLM 분율 캡 병용. + - MINERU_VIRTUAL_VRAM_SIZE=${MINERU_VIRTUAL_VRAM_SIZE:-6} + - MINERU_GPU_MEMORY_UTILIZATION=${MINERU_GPU_MEMORY_UTILIZATION:-0.40} + - MINERU_PRELOAD=${MINERU_PRELOAD:-1} + volumes: + - ${NAS_NFS_PATH:-/mnt/nas/Document_Server}:/documents:ro + - mineru_models:/root/.cache + ipc: host # vLLM 공유메모리 — 공식 run 의 --ipc=host 대응. + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: [gpu] + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3301/ready"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 900s # VLM 모델 lazy 다운로드(~2.4GB)+엔진 로드 여유. + restart: unless-stopped + stt-service: # 2026-05-08 (D9 Track B revised): GPU is canonical STT owner. # 정책: Mac mini = Gemma 26B 전용 우선이므로 STT/Whisper 는 호출량 무관 GPU 서버 소유. @@ -271,3 +308,4 @@ volumes: ocr_models: stt_models: marker_models: + mineru_models: diff --git a/services/mineru/Dockerfile b/services/mineru/Dockerfile new file mode 100644 index 0000000..8ed4732 --- /dev/null +++ b/services/mineru/Dockerfile @@ -0,0 +1,45 @@ +# mineru-service — MinerU 2.5 VLM 기반 PDF→markdown 추출기. marker-service 대체. +# 단일카드(RTX 4070 Ti S 16GB→PRO 4000 24GB) markdown VRAM ~10GB(marker)→~5GB(MinerU VLM). +# +# 공식 opendatalab/MinerU global Dockerfile 기반: +# FROM vllm/vllm-openai:v0.21.0 (CUDA 13.0). GPU 호스트 드라이버 595.71.05 / CUDA 13.2 가 +# 13.0 런타임 지원 → cu129 폴백 불필요. vLLM 은 base 이미지가 제공하므로 mineru 는 [core] 만. +# +# 모델은 이미지에 굽지 않고 런타임 warmup 시 HF cache 볼륨으로 lazy 다운로드 (marker/ocr 선례 = +# 서버 .cache 볼륨). 이미지 슬림 유지 + server.py 반복 빌드 빠름 + 모델 볼륨 영속. +FROM vllm/vllm-openai:v0.21.0 + +# base 이미지의 ENTRYPOINT(vLLM OpenAI 서버)를 제거 — 우리는 uvicorn 으로 자체 FastAPI 기동. +ENTRYPOINT [] + +# opencv(libgl) + CJK 폰트(레이아웃/렌더 안전) + curl(healthcheck). 공식 Dockerfile 동일. +RUN apt-get update && apt-get install -y --no-install-recommends \ + fonts-noto-core fonts-noto-cjk fontconfig libgl1 curl \ + && fc-cache -fv \ + && apt-get clean && rm -rf /var/lib/apt/lists/* + +# mineru[core] — 공식 설치 라인. vLLM(vlm-engine 백엔드)은 base 가 이미 제공. +RUN python3 -m pip install -U 'mineru[core]>=3.2.1' --break-system-packages \ + && python3 -m pip cache purge + +# 서비스 wrapper 의존성. base(vllm-openai)+mineru 가 fastapi/uvicorn/pillow 를 이미 제공 → +# pymupdf 만 추가(나머지 명시 핀은 base 의 pillow 12.x 를 불필요하게 다운그레이드해서 제거). +RUN python3 -m pip install --no-cache-dir --break-system-packages \ + 'pymupdf>=1.24.0,<2.0.0' + +# MINERU_MODEL_SOURCE=huggingface = warmup 시 lazy 다운로드 (HF cache 볼륨에 영속). +# PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True = 단편화 완화(연구 권고, 거대 입력 OOM 완충). +ENV MINERU_MODEL_SOURCE=huggingface \ + HF_HOME=/root/.cache/huggingface \ + PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True + +WORKDIR /app +# server.py = 무거운 pip 레이어 뒤에 COPY → 반복 빌드 시 캐시 적중(빠른 재빌드). +COPY server.py /app/server.py + +EXPOSE 3301 +# VLM 모델 lazy 다운로드(~2.4GB)+엔진 로드 여유로 start-period 길게. +HEALTHCHECK --start-period=900s --interval=30s --timeout=10s --retries=3 \ + CMD curl -f http://localhost:3301/ready || exit 1 + +CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "3301"] diff --git a/services/mineru/server.py b/services/mineru/server.py new file mode 100644 index 0000000..dd86cde --- /dev/null +++ b/services/mineru/server.py @@ -0,0 +1,315 @@ +"""mineru-service — POST /convert: PDF → markdown + 추출 이미지 base64. + +marker-service 대체(MinerU 2.5 VLM). **marker 의 /convert 계약을 그대로 복제**해서 +marker_worker 가 엔드포인트만 바꾸면 되도록 한다(요청/응답 동일 shape): + + 요청: {file_path, max_pages?, start_page?, end_page?} (page = 1-based inclusive) + 응답: {md_content, md_content_hash, engine, engine_version, elapsed_ms, + raw_metrics, images:[{slug, format, width, height, bytes_b64}], images_truncated} + +설계 노트: +- **page range 는 PyMuPDF 로 직접 슬라이스**해서 MinerU 에 넘긴다(start_page..end_page → + 0-based [a,b] 페이지만 담은 새 PDF bytes). MinerU 의 `end_page_id=0 falsy 무시` 버그 회피. + 40p 윈도우 분할은 marker_worker 가 그대로 담당. (검증: fitz 슬라이스 렌더 = 원본과 동일 품질.) +- **★ 반드시 async 엔진(`aio_do_parse`) 사용.** 동기 `do_parse`(vllm-engine sync)는 본 모델 + (MinerU2.5-Pro-2605-1.2B)에서 layout 토큰 malformed → 빈 md 산출(실측 G1-2). async + (`aio_do_parse` = vllm-async-engine, mineru CLI 가 쓰는 정상 경로) = 정상 출력. +- **이미지 = stateless**: marker 처럼 NAS write 안 함. MinerU 가 md 에 박는 `![](images/.jpg)` + href 를 그대로 slug 으로 반환 → fastapi(marker_worker)의 `_rewrite_image_refs` 가 basename + 매칭으로 `docimg:img_NNN` 정규화 + NAS persist. (계약 무변) +- **VRAM 캡**: `MINERU_GPU_MEMORY_UTILIZATION`(vLLM 분율, 0.40→~6GB 실측). compose 의 + `MINERU_VIRTUAL_VRAM_SIZE` 도 무해(실측 정상)하나 출력엔 무관 — 캡은 분율로 충분. + backend=`vlm-engine`(기본 hybrid-engine 은 다중모델 로드 OOM, 반드시 명시). + +엔진은 첫 변환(또는 startup warmup) 시 1회 로드 — MinerU ModelSingleton 캐시. 단일 GPU 라 +변환은 _engine_lock 으로 직렬화. +""" +import asyncio +import base64 +import hashlib +import inspect +import io +import logging +import os +import time +import unicodedata +from pathlib import Path + +import fitz # PyMuPDF — page 슬라이스 + 페이지수 +from fastapi import FastAPI, HTTPException, Response +from PIL import Image +from pydantic import BaseModel, Field + +logger = logging.getLogger("mineru-service") +logging.basicConfig(level=logging.INFO) +app = FastAPI() + +try: + import importlib.metadata + _engine_version = importlib.metadata.version("mineru") +except Exception: + _engine_version = "unknown" + +# ---- 설정 (compose env 로 override) ----------------------------------------- +MINERU_BACKEND = os.getenv("MINERU_BACKEND", "vlm-engine") +MINERU_LANG = os.getenv("MINERU_LANG", "korean") +GPU_MEM_UTIL = float(os.getenv("MINERU_GPU_MEMORY_UTILIZATION", "0.40")) + +MAX_IMAGES_PER_DOC = int(os.getenv("MINERU_MAX_IMAGES_PER_DOC", "200")) +MAX_BYTES_PER_IMAGE = int(os.getenv("MINERU_MAX_BYTES_PER_IMAGE", str(10 * 1024 * 1024))) +MAX_PAGES_HARD = int(os.getenv("MINERU_MAX_PAGES_HARD", "200")) # 1-shot max_pages 안전장치 + +_PRELOAD = os.getenv("MINERU_PRELOAD", "1") != "0" + +# ---- 엔진 상태 --------------------------------------------------------------- +_warmup_done = False +_warmup_error: str | None = None +# 단일 GPU async 엔진 — warmup + convert 직렬화(엔진 1개, 임시디렉토리/싱글톤 경합 차단). +_engine_lock = asyncio.Lock() + + +async def _run_mineru(pdf_bytes: bytes, lang: str) -> tuple[str, list[dict]]: + """슬라이스된 PDF bytes → (markdown, 이미지 dict 리스트). **async 엔진 경로.** + + 호출자(_ensure_warmup / convert)가 _engine_lock 을 잡은 상태로 호출한다. + 이미지 dict: {slug, format, width, height, raw_bytes}. slug = md href 그대로. + """ + import glob + import tempfile + + from mineru.cli.common import aio_do_parse + + with tempfile.TemporaryDirectory(prefix="mineru_") as td: + candidate = { + "output_dir": td, + "pdf_file_names": ["doc"], + "pdf_bytes_list": [pdf_bytes], + "p_lang_list": [lang], + "backend": MINERU_BACKEND, + "formula_enable": True, + "table_enable": True, + "f_dump_md": True, + "f_dump_content_list": True, + "f_dump_middle_json": False, + "f_dump_model_output": False, + "f_dump_orig_pdf": False, + "f_draw_layout_bbox": False, + "f_draw_span_bbox": False, + "gpu_memory_utilization": GPU_MEM_UTIL, + } + sig = inspect.signature(aio_do_parse) + has_var_kw = any( + p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values() + ) + kwargs = candidate if has_var_kw else { + k: v for k, v in candidate.items() if k in sig.parameters + } + await aio_do_parse(**kwargs) + + md_files = sorted(glob.glob(f"{td}/**/*.md", recursive=True)) + if not md_files: + raise RuntimeError("mineru produced no markdown output") + md_path = Path(md_files[0]) + md_text = md_path.read_text(encoding="utf-8", errors="replace") + + images: list[dict] = [] + img_dir = md_path.parent / "images" + if img_dir.is_dir(): + for img_file in sorted(img_dir.iterdir()): + if not img_file.is_file(): + continue + raw = img_file.read_bytes() + slug = f"images/{img_file.name}" # md href 와 정확히 일치 + w = h = None + try: + with Image.open(io.BytesIO(raw)) as im: + w, h = im.width, im.height + fmt = (im.format or "JPEG").lower() + except Exception: + fmt = img_file.suffix.lstrip(".").lower() or "jpeg" + images.append( + {"slug": slug, "format": fmt, "width": w, "height": h, "raw_bytes": raw} + ) + return md_text, images + + +async def _ensure_warmup() -> None: + """첫 /convert 또는 startup hook 시 1-page 합성 PDF 로 엔진+모델 적재.""" + global _warmup_done, _warmup_error + if _warmup_done: + return + async with _engine_lock: + if _warmup_done: + return + try: + logger.info("[mineru-service] warmup start (async engine load + model fetch)") + doc = fitz.open() + page = doc.new_page() + page.insert_text((72, 72), "MinerU warmup.") + warmup_bytes = doc.tobytes() + doc.close() + await _run_mineru(warmup_bytes, MINERU_LANG) + _warmup_done = True + _warmup_error = None + logger.info(f"[mineru-service] warmup done engine_version={_engine_version}") + except Exception as exc: + _warmup_error = f"{type(exc).__name__}: {exc}" + logger.exception("[mineru-service] warmup failed") + raise + + +@app.on_event("startup") +async def startup(): + if _PRELOAD: + asyncio.create_task(_ensure_warmup()) + + +# ---- 계약 모델 (marker 와 동일 shape) ---------------------------------------- +class ConvertRequest(BaseModel): + file_path: str + max_pages: int | None = None + start_page: int | None = None # 1-based inclusive + end_page: int | None = None # 1-based inclusive + + +class ConvertImage(BaseModel): + slug: str + format: str + width: int | None = None + height: int | None = None + bytes_b64: str + + +class ConvertResponse(BaseModel): + md_content: str + md_content_hash: str + engine: str + engine_version: str + elapsed_ms: int + raw_metrics: dict + images: list[ConvertImage] = Field(default_factory=list) + images_truncated: bool = False + + +@app.get("/health") +def health(): + return {"status": "ok", "service": "mineru-service"} + + +@app.get("/ready") +async def ready(response: Response): + """marker /ready 의미 복제: warmup_failed 만 503, idle/warming=200(depends_on 굳음 방지).""" + if _warmup_error: + response.status_code = 503 + return {"status": "warmup_failed", "engine": "mineru", + "engine_version": _engine_version, "error": _warmup_error} + if not _warmup_done: + return {"status": "warming_up" if _PRELOAD else "idle", "engine": "mineru", + "engine_version": _engine_version, "models_loaded": False} + return {"status": "ready", "engine": "mineru", + "engine_version": _engine_version, "models_loaded": True} + + +def _resolve_path(file_path: str) -> Path | None: + """NFC(DB) vs NFD(NFS) 한글 경로 정규화 차이 흡수. ocr/server.py 와 동일 패턴 + (필수 — 한글명 파일은 NFS=NFD 저장이라 DB 의 NFC 경로로는 is_file=False).""" + for c in (file_path, + unicodedata.normalize("NFD", file_path), + unicodedata.normalize("NFC", file_path)): + p = Path(c) + if p.exists(): + return p + parent = Path(file_path).parent + if parent.exists(): + target = unicodedata.normalize("NFC", Path(file_path).name) + for child in parent.iterdir(): + if unicodedata.normalize("NFC", child.name) == target: + return child + return None + + +def _slice_pdf(src_path: Path, start_page: int | None, end_page: int | None, + max_pages: int | None) -> tuple[bytes, int]: + """요청 page 범위(1-based inclusive)만 담은 새 PDF bytes + 변환 페이지수 반환.""" + with fitz.open(src_path) as src: + n = src.page_count + if start_page is not None and end_page is not None: + a = max(0, start_page - 1) + b = min(n - 1, end_page - 1) + else: + a = 0 + cap = max_pages if max_pages is not None else MAX_PAGES_HARD + b = min(n - 1, cap - 1) + if b < a: + raise HTTPException(422, detail={"code": "bad_page_range", + "message": f"a={a} b={b} n={n}"}) + out = fitz.open() + out.insert_pdf(src, from_page=a, to_page=b) + pdf_bytes = out.tobytes() + out.close() + return pdf_bytes, (b - a + 1) + + +def _serialize_images(images: list[dict], src_path: str) -> tuple[list[ConvertImage], bool]: + """이미지 dict 리스트 → base64 ConvertImage 리스트 (marker 가드 동일).""" + truncated = len(images) > MAX_IMAGES_PER_DOC + if truncated: + logger.warning(f"[mineru-service] images truncated path={src_path} " + f"total={len(images)} cap={MAX_IMAGES_PER_DOC}") + images = images[:MAX_IMAGES_PER_DOC] + out: list[ConvertImage] = [] + for img in images: + raw = img["raw_bytes"] + if len(raw) > MAX_BYTES_PER_IMAGE: + logger.warning(f"[mineru-service] image too large skipped path={src_path} " + f"slug={img['slug']} bytes={len(raw)} cap={MAX_BYTES_PER_IMAGE}") + continue + out.append(ConvertImage( + slug=img["slug"], format=img["format"], + width=img.get("width"), height=img.get("height"), + bytes_b64=base64.b64encode(raw).decode("ascii"), + )) + return out, truncated + + +@app.post("/convert", response_model=ConvertResponse) +async def convert(req: ConvertRequest): + p = _resolve_path(req.file_path) + if p is None or not p.is_file(): + raise HTTPException(404, detail={"code": "file_not_found", "message": req.file_path}) + if req.start_page is not None and req.end_page is not None: + if req.start_page < 1 or req.end_page < req.start_page: + raise HTTPException(422, detail={"code": "bad_page_range", + "message": f"start_page={req.start_page} end_page={req.end_page}"}) + + pdf_bytes, page_count = _slice_pdf(p, req.start_page, req.end_page, req.max_pages) + + await _ensure_warmup() # 엔진 로드 보장(내부에서 _engine_lock 잡았다 놓음) + async with _engine_lock: # 실제 변환 직렬화(단일 GPU) + start = time.monotonic() + try: + md_text, raw_images = await _run_mineru(pdf_bytes, MINERU_LANG) + except HTTPException: + raise + except Exception as exc: + logger.exception(f"[mineru-service] conversion failed path={p}: {exc}") + raise HTTPException(422, detail={"code": "conversion_failed", + "message": f"{type(exc).__name__}: {exc}"}) from exc + elapsed_ms = int((time.monotonic() - start) * 1000) + + images_payload, truncated = _serialize_images(raw_images, str(p)) + + return ConvertResponse( + md_content=md_text, + md_content_hash=hashlib.sha256(md_text.encode("utf-8")).hexdigest(), + engine="mineru", + engine_version=_engine_version, + elapsed_ms=elapsed_ms, + raw_metrics={ + "page_count": page_count, + "image_count_extracted": len(raw_images), + "image_count_returned": len(images_payload), + }, + images=images_payload, + images_truncated=truncated, + )