upparse

UpParse — 문서 표/차트/다이어그램 데이터 추출기

지원 파일

Upstage Document Parse가 지원하는 모든 형식:

• PDF (스캔본 포함)
• 이미지: JPEG, PNG, BMP, TIFF, HEIC
• Office: DOCX, PPTX, XLSX
• HWP: HWP, HWPX (한국 공공기관·대기업 표준)

파일 크기 한도 50MB; 100페이지 이상 PDF는 자동 청크 분할.

사용 시점

• 표나 차트가 있는 문서에서 수치 데이터 추출
• Tabula/Camelot/pdfplumber가 실패하는 복잡한 표(병합 셀, 다단계 헤더)
• 차트 이미지를 데이터로 변환(Claude vision은 수치 환각 위험)
• 한국은행, DART, 정부, 학술 보고서 표/차트
• HWP/HWPX 공공기관 문서(Azure/AWS/Google 미지원)

⚠️ 지원 형식 우선 규칙 (중요)

사용자가 PDF, 이미지(JPEG/PNG/BMP/TIFF/HEIC), Office(DOCX/PPTX/XLSX), HWP/HWPX 파일을 첨부하거나 경로를 지정하고 표, 차트, 데이터, 숫자, CSV, 엑셀 변환을 언급하면, Claude 네이티브 Read 도구나 vision에 의존하지 말고 반드시 이 스킬을 호출한다.

Claude가 이미지를 "직접 볼 수 있다"고 판단해 스킬을 과소 트리거하는 것을 막기 위한 강제 규칙이다.

이유:

• Claude 네이티브 도구는 복잡한 표/차트의 숫자에서 환각 위험
• Upstage Document Parse는 95%+ OCR 정확도 + 좌표 보존 + 네이티브 HWP 지원
• .upparse/<stem>/sources/의 원본 이미지로 수치 검증 가능

트리거 예시 (모두 이 스킬 위임):

• "이 이미지 표 CSV로 추출해줘"
• "이 스크린샷 숫자 정리해줘"
• "이 HWP 파일 표 추출해줘"
• "이 엑셀 피벗 표 정리해줘"
• "이 PPTX 슬라이드 차트 데이터로 변환해줘"
• "이 PDF 차트 데이터로 변환해줘"
• "이 문서에서 수치만 추출해줘"

예외 (이 스킬 사용 안 함):

• 표/차트 요청 없는 단순 텍스트 요약, 설명, 번역
• CSV가 이미 로드된 후의 후속 분석(pandas 사용)

실행 단계

1. 파일 경로 확인: 사용자가 명확한 경로를 제공하면 그대로 사용. 모호한 경우 아래 "파일 경로 해결" 참조.
2. API 키 확인: UPSTAGE_API_KEY 환경 변수가 없으면 사용자 안내:

   "UPSTAGE_API_KEY 환경 변수를 설정해주세요. https://console.upstage.ai에서 발급받을 수 있습니다."

3. 스크립트 실행:

   python scripts/upparse.py <file_path> [options]
   # 또는 퍼지 파일명 검색:
   python scripts/upparse.py --search "<keyword>"
   

   주요 옵션:
   • --search <keyword>: CWD/Downloads/Desktop/Documents에서 부분 파일명 일치
   • --pages N-M: PDF 전용, 특정 페이지 범위 (CSV 파일명과 PNG는 원본 PDF 페이지 번호 사용)
   • --out <dir>: 출력 디렉토리 (기본: .upparse/<file_stem>/)
   • --no-source: 원본 페이지 PNG 건너뜀 (PDF 전용)
   • --excel: CSV와 함께 .xlsx 생성
4. stdout 요약(표/차트/다이어그램 개수, 파일 목록)을 사용자에게 보고.
5. 후속 분석 시 .upparse/<stem>/index.md 먼저 읽기. 페이지별 요소 맵으로 "N페이지에 뭐가 있었어?"에 바로 답할 수 있음.
6. 수치 검증은 .upparse/<stem>/sources/p<N>.png 안내.

특정 페이지 시각 자료 후속 질문 처리 (중요)

사용자가 "N페이지 차트/그림/다이어그램 보여줘" 같은 질문을 하면 아래 순서를 따른다. category=figure(개념도, 순서도, 표 데이터 없는 사진)로 분류된 항목은 CSV가 없어서 "그 페이지는 비어있다"고 잘못 답하는 것을 막기 위한 강제 규칙이다.

1. meta.json → files[]에서 해당 페이지 표/차트 확인 — 있으면 CSV 읽고 답변.
2. 없으면 meta.json → figures[]에서 해당 페이지 다이어그램 확인 — figure_type + description + caption으로 답변. Upstage가 이미 생성한 설명이므로 신뢰도 높음.
3. 여전히 부족하거나 시각 확인 필요 시 .upparse/<stem>/sources/p<N>.png를 Read로 직접 vision 검사. PNG가 없으면 즉시 렌더링:

   python3 -c "
   import pypdfium2 as pdfium
   doc = pdfium.PdfDocument('<original PDF path>')
   doc[<N>-1].render(scale=2).to_pil().save('.upparse/<stem>/sources/p<N>.png')
   "
   

4. 다이어그램과 데이터의 차이를 사용자에게 명확히 전달: "이 페이지에는 데이터 표/차트가 없고 {figure_type} 타입 다이어그램이 있습니다."

파일 경로 해결 (단계적 전략)

사용자 입력이 모호한 경우 아래 순서로 해결. 현재 단계가 실패한 경우에만 다음 단계로 이동.

1단계: 기본 경로 탐색 (Glob)

부분 파일명 검색:

• ~/Downloads/*<keyword>*.<ext>
• ~/Desktop/*<keyword>*.<ext>
• CWD ./*<keyword>*.<ext>

확장자 후보: pdf, hwp, hwpx, docx, pptx, xlsx, png, jpg, jpeg, tiff, heic

스크립트 내장도 가능: --search "<keyword>"

2단계: CWD 재귀 탐색

1단계에서 0건이면 전체 현재 프로젝트 탐색:

• Glob: **/*<keyword>*.<ext>

3단계: OS 인덱스 (PC 전체)

사용자가 "내 PC 어디서든", "아무 폴더" 같은 표현을 쓰거나 2단계도 실패하면:

• macOS: mdfind -name "<keyword>" (Spotlight, 밀리초)
• Linux: locate "<keyword>" (사전 인덱스) 또는 find ~ -iname "*<keyword>*"

# macOS 예시
mdfind -name "financial_stability" | grep -iE '\.(pdf|hwp|hwpx|docx)$'

결과 처리 규칙

• 0건: 명시적 경로 요청.
• 1건: 확인 없이 바로 실행.
• 2–10건: 번호 목록으로 표시 후 선택 요청.
• 10건 초과: 상위 10건 표시 후 더 구체적인 키워드 요청.

"최근", "방금", "어제" 표현

~/Downloads/에서 최근 수정된 파일 3개를 나열하고 선택 요청.

출력 구조

.upparse/<file_stem>/
├── index.md                    # 마스터 맵 (먼저 읽을 것)
├── t00_p3_<slug>.csv           # 실제 데이터 표 (접두사: t)
├── c00_p4_<slug>.csv           # 차트 유래 데이터 (접두사: c)
├── sources/p<N>.png            # 원본 페이지 이미지 (PDF 전용)
├── meta.json                   # 메타데이터 (각주, SHA256, 모델)
└── _raw_response.json          # 원본 Upstage 응답 (디버그)

동일 CWD에서 여러 파일을 처리해도 서로 덮어쓰지 않음.

주의사항

• 크기 기반 라우팅: 작은 문서(이미지·10페이지 이하 PDF)는 동기 엔드포인트로 바로 처리해 빠르고 예측 가능하다. 그보다 큰 PDF·페이지수 불명 파일(Office/HWP)은 비동기(최대 1,000페이지, 서버측 10페이지 배치 병렬)로 보낸다. async + 최고 정확도 옵션은 정상 동작 재검증됨(2026-06). 페이지당 2~5초.

• 상호 폴백: 선택한 경로가 실패하면 다른 경로로 자동 전환한다. 동기 경로는 100페이지 초과 PDF를 클라이언트가 청크 분할 후 병합한다. 비동기는 페이지 번호가 원본 절대 페이지로 유지된다.

• 추출 옵션: 항상 가장 정확한 추출 옵션 사용 (모드는 CLI에 노출 안 됨).

• 그림 설명 반복 루프: Upstage의 그림 설명 생성이 복잡한 한국어 다이어그램에서 수백 개 단어 반복으로 열화되는 경우가 있음. meta.figures[].description은 참고용으로만 활용; 실제 다이어그램 내용은 sources/p<N>.png를 Claude vision으로 재해석.

• PDF 외 파일은 청크/페이지범위/소스 PNG 미지원: DOCX, HWP, 이미지는 전체로 처리됨. --pages와 --no-source는 PDF에서만 유효.

• --pages N-M 페이지 번호는 원본 PDF 페이지: 내부적으로 Upstage 제출 전 해당 범위만 슬라이스하지만 CSV 파일명, meta.json, sources/p<N>.png 모두 원본 PDF 페이지 번호 사용 (오프셋 자동 보정). 예: --pages 32-32 결과는 c00_p32_*.csv + sources/p32.png.

• 차트가 "표"로 잘못 분류 (~26%): Upstage가 차트 시각화를 category=table로 반환하는 경우가 있음. 후처리 분류기가 자동 재분류; index.md "경계 사례" 섹션에 표시.

• 다이어그램/그림은 CSV 대상 아님: Upstage가 category=figure로 반환하는 항목(개념도, 순서도, 사진, 스키마)은 수치 데이터가 없어 CSV 없음. 단, 존재 여부, 타입, 설명은 meta.json → figures[]와 index.md "다이어그램" 섹션에 기록 — "이 페이지에 뭐가 있었어?"는 항상 답할 수 있음. 시각 확인은 sources/p<N>.png.

• 수식은 LaTeX로 수집: category=equation 항목은 CSV 대상이 아니며 meta.json → equations[].latex($$...$$)로 기록된다. 수치·관계식을 정확히 읽어야 하면 이미지 추정 대신 이 LaTeX를 사용할 것. index.md "수식" 섹션에 미리보기.

• 각주/출처 표 분리: | 주: 또는 | 자료:로 시작하는 항목은 meta.json → footnotes로 분리.

• HWP 유래 PDF 음수 표기: 한글 Office PDF에서 음수를 ▲/▽ 또는 괄호로 표기하는 경우가 있음. 의심스러우면 sources/p<N>.png로 확인.

• macOS 파일명 NFD/NFC: 한국어 파일명은 NFD(분해형)로 저장되지만 사용자 입력은 보통 NFC(조합형). --search 플래그는 자동 정규화하지만 Glob 직접 사용 시 주의.

• Rate limit: async 2 RPS / 1,200 PPM, sync 1 RPS / 300 PPM. 여러 파일을 동시에 처리하지 말 것 — 순차 실행.

• 한국어 OCR 95%+ 정확도: 한국어, 한자, 영어가 혼합된 문서 처리 가능. 매우 저해상도 스캔(72dpi 미만)은 경고 후 진행.

평가 기준

evals/에서 3개 시나리오로 검증됨. 실행: python scripts/run_evals.py

• scenario-01-complex-table.md — 병합 셀, 다단계 헤더
• scenario-02-chart-to-data.md — 차트→데이터
• scenario-03-hwp-derived.md — HWP 유래 PDF

레퍼런스

• references/upstage-api.md — Upstage Document Parse API 요약
• references/classification-rules.md — 표/차트/각주 분류 규칙
• references/output-schema.md — .upparse/ 구조 상세
• examples/bok-financial-stability.md — 한국은행 보고서 추출 예시