DEV Community

정상록
정상록

Posted on

Firecrawl Fire-PDF v2: 5 lines of code to turn any PDF/Excel/Word into LLM-ready markdown

TL;DR

  • Firecrawl released Fire-PDF v2 on April 14, 2026 — a Rust-based PDF engine that's 3.5-5.7x faster than the previous version, averaging under 400ms per page.
  • URL 하나만 넘기면 PDF/Excel/Word 모두 LLM-ready 마크다운으로 자동 변환돼요.
  • 3가지 PDF 모드 (auto/fast/ocr) 중에 auto만 써도 텍스트 PDF + 스캔 PDF 하이브리드 케이스를 다 커버합니다.
  • RAG 파이프라인에서 문서 파싱이 병목이었다면 코드 5줄로 해결됩니다.

문제: 문서 파싱이 RAG의 첫 번째 병목

RAG 파이프라인을 만들어본 적이 있다면 이 흐름에 익숙하실 거예요.

Documents (PDF/Excel/Word)
    ↓  ← 여기가 가장 지저분함
Parsing (PyPDF2 / unstructured / Tesseract / openpyxl / python-docx)
    ↓
Chunking → Embedding → Vector DB → Retrieval → LLM
Enter fullscreen mode Exit fullscreen mode

파싱 단계의 문제점은 두 가지입니다:

  1. 포맷별로 다른 라이브러리 — PDF는 PyPDF2, Excel은 openpyxl, Word는 python-docx, 스캔 PDF는 Tesseract. 각각 출력 형식도 다르고 에러 케이스도 다릅니다.
  2. 스캔 PDF의 OCR 비용 — 모든 페이지에 OCR을 무차별로 돌리면 500페이지 문서 하나에 수 분이 걸립니다.

Firecrawl의 Fire-PDF v2가 이 두 문제를 어떻게 푸는지 보겠습니다.

해결: Fire-PDF 5-stage Pipeline

Fire-PDF의 핵심 아이디어는 "모든 페이지에 OCR을 돌리지 말자"입니다. 5단계 파이프라인으로 동작합니다:

  1. Classify — pdf-inspector라는 오픈소스 Rust 라이브러리가 페이지를 밀리초 단위로 텍스트/이미지/혼합으로 분류
  2. Render — OCR이 필요한 페이지만 200 DPI로 이미지화 (전체 X)
  3. Layout Detection — 뉴럴 모델로 텍스트 블록, 테이블, 수식, 이미지 감지 + 리딩 순서 결정
  4. Extraction — 텍스트 페이지는 GPU 없이 네이티브 추출, 스캔 페이지만 GLM-OCR
  5. Assembly — 리딩 순서대로 마크다운 조립. 테이블 → 마크다운 테이블, 수식 → LaTeX

결과적으로 페이지당 평균 400ms 미만이고, 기존 엔진 대비 3.5~5.7배 빠릅니다.

설치 

pip install firecrawl
# 또는
npm install @mendable/firecrawl-js
Enter fullscreen mode Exit fullscreen mode

API 키는 firecrawl.dev에서 발급. 환경 변수로 관리하세요:

export FIRECRAWL_API_KEY="fc-..."
Enter fullscreen mode Exit fullscreen mode

3가지 모드 사용법

1. auto 모드 (기본, 99% 케이스) 

from firecrawl import Firecrawl

fc = Firecrawl(api_key=os.environ['FIRECRAWL_API_KEY'])

result = fc.scrape(
    url='https://example.com/report.pdf',
    formats=['markdown']
)

print(result['markdown'])
Enter fullscreen mode Exit fullscreen mode

텍스트 추출을 먼저 시도하고 실패하면 OCR로 폴백. 하이브리드 문서(텍스트 + 스캔 섞인 PDF)에서 가장 잘 동작합니다.

2. fast 모드 (속도 최우선) 

result = fc.scrape(
    url='https://example.com/doc.pdf',
    formats=['markdown'],
    parsePDF='fast'
)
Enter fullscreen mode Exit fullscreen mode

임베디드 텍스트만 추출. 디지털 생성 PDF(arxiv 논문, 생성형 리포트)에서 가장 빠르지만, 스캔 PDF는 빈 결과를 반환합니다.

3. ocr 모드 (스캔 문서 전용) 

result = fc.scrape(
    url='https://example.com/scanned.pdf',
    formats=['markdown'],
    parsePDF='ocr'
)
Enter fullscreen mode Exit fullscreen mode

전 페이지 강제 OCR. 완전 스캔 문서, 손글씨 양식, 이미지 위 텍스트에 사용.

Excel/Word도 URL 하나로 

# Excel — 각 시트가 별도 마크다운 테이블로 변환
result = fc.scrape(url='https://example.com/data.xlsx')
print(result['markdown'])
Enter fullscreen mode Exit fullscreen mode

출력 예시:

## Sheet1
| Name   | Value |
|--------|-------|
| Item 1 | 100   |
| Item 2 | 200   |

## Sheet2
| Date       | Description   |
|------------|---------------|
| 2023-01-01 | First quarter |
Enter fullscreen mode Exit fullscreen mode 
# Word — 헤딩 계층, 리스트, 테이블 구조 보존
result = fc.scrape(url='https://example.com/report.docx')
Enter fullscreen mode Exit fullscreen mode

포맷별로 다른 라이브러리를 쓰는 대신 단일 엔드포인트로 처리됩니다.

RAG 파이프라인에 끼워넣기

LangChain 기준:

from firecrawl import Firecrawl
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma

fc = Firecrawl(api_key='fc-...')

# 1) Parse
result = fc.scrape(url='https://example.com/manual.pdf', formats=['markdown'])

# 2) Chunk
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
chunks = splitter.split_text(result['markdown'])

# 3) Embed + Store
vs = Chroma.from_texts(chunks, OpenAIEmbeddings())

# 4) Retrieve
docs = vs.similarity_search("how to install?")
Enter fullscreen mode Exit fullscreen mode

파싱 한 단계가 사실상 한 줄로 끝나서, 나머지 파이프라인에 집중할 수 있게 됩니다.

JSON 추출로 구조화 데이터 뽑기

비정형 PDF에서 스키마 기반으로 데이터 추출:

result = fc.scrape(url='https://example.com/annual-report.pdf', {
    'formats': [{
        'type': 'json',
        'prompt': 'Extract company name, fiscal year, total revenue',
        'schema': {
            'type': 'object',
            'properties': {
                'company': {'type': 'string'},
                'fiscal_year': {'type': 'string'},
                'revenue': {'type': 'number'}
            }
        }
    }]
})

print(result['json'])
# {"company": "Acme", "fiscal_year": "2025", "revenue": 5200000000}
Enter fullscreen mode Exit fullscreen mode

재무제표 100장, 기술 논문 메트릭, 규제 문서 특정 조항 — 모두 API 한 호출로 구조화됩니다.

가격

  • PDF: 페이지당 1크레딧
  • parsers를 []로 넘기면 base64로 1크레딧 정액 (파싱 없음)
  • Free 500 / Standard $19/mo / Growth $99/mo

500페이지 PDF 하나 파싱에 500크레딧 쓰이는 구조예요. 대량 배치는 maxPages로 제한하거나 fast 모드로 비용 최적화하세요.

마무리

Fire-PDF는 "페이지 단위 분류"라는 간단한 아이디어로 속도를 3.5~5.7배 올렸어요. PDF/Excel/Word 통합 파싱 + JSON 추출 + OCR 폴백까지, RAG 파이프라인 첫 단계를 코드 5줄로 줄여줍니다.

여러분의 RAG 파이프라인에서 문서 파싱이 병목이라면 한번 써보세요.

댓글로 이야기해봐요

  • 기존에 쓰던 PDF 파서(unstructured.io, Docling, PyPDF2)와 비교해본 분 계신가요?
  • 한국어 PDF 정확도는 어떤가요?
  • LangChain/LlamaIndex 말고 다른 RAG 프레임워크에 붙여본 경험이 있다면 공유 부탁드려요.

Top comments (0)