anydoc

1. 프로젝트 개요

anydoc는 Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, PDF 파일을 깔끔하고 일관된 GitHub 스타일 Markdown으로 변환하는 빠른 Rust 기반 라이브러리입니다. 개발자와 AI 에이전트에게 모든 오피스 문서를 LLM에 바로 사용할 수 있는 텍스트로 변환하는 단일하고 신뢰할 수 있는 경로를 제공합니다.

2. 배경 및 포지셔닝

Firecrawl이 만든 anydoc는 문서 처리 및 AI 파이프라인에서 끊임없이 발생하는 문제를 해결하기 위해 탄생했습니다. 오피스 파일은 수십 가지의 레거시 및 최신 형식으로 제공되며, 기존의 각 변환기는 그중 일부만 처리하고, 출력 품질과 속도도 제각각인 경우가 많습니다. anydoc의 핵심 임무는 2003년에 저장된 .doc부터 어제 내보낸 .pptx까지 모든 형식에 하나의 공유 문서 모델과 하나의 Markdown 직렬화기를 제공하여, 테이블 이스케이프나 제목 앵커 수정이 모든 형식에 동시에 적용되고 형식별로 다시 구현할 필요가 없도록 하는 것입니다.

Pandoc, LibreOffice의 헤드리스 변환, 또는 markitdown, unstructured, docling과 같은 Python 도구 등 범용 변환기와는 세 가지 측면에서 다릅니다. 순수 Rust로 작성되어 ML 모델이나 외부 서비스가 필요 없고, 확장자가 아닌 파일 콘텐츠에서 형식을 감지하며, 6가지 경쟁 도구와 비교한 anydoc의 자체 공개 벤치마크에 따르면 테스트된 14가지 형식을 모두 지원한 유일한 도구였고 품질에서도 가장 높은 점수를 받았으며, 다음으로 빠른 도구보다 약 10배 빠른 변환 속도를 보였습니다. anydoc는 또한 호스팅된 Firecrawl Parse API를 지원하며, 이 API는 오픈소스 라이브러리가 의도적으로 시도하지 않는 스캔된 페이지에 대한 OCR을 추가합니다.

3. 기능 분류

📄 형식 지원 — 8개 문서 계열, 20개 이상의 확장자
.doc/.docx/.docm(Word), .ppt/.pptx/.pptm/.pps/.ppsx/.ppsm/.pot(PowerPoint), .xls/.xlsx/.xlsm/.xlsb(Excel), .odt/.ods/.odp(OpenDocument) 및 .rtf, .epub, .csv, .pdf를 변환합니다. 목적: 단일 형식 변환기 여러 개를 대체하는 하나의 라이브러리를 제공합니다.

🧱 문서 구조 충실도 — 완전한 충실도의 구조 요소
앵커가 있는 제목, 굵게/기울임/취소선, 인라인 코드 및 코드 블록, 링크 및 상호 참조, 중첩/번호/작업 목록, 병합된 셀이 있는 테이블, 인용구, 각주/미주, 발표자 노트를 지원합니다. 목적: Markdown 출력이 단순한 텍스트 덤프가 아니라 다운스트림 파싱에 여전히 사용할 수 있을 만큼 충분한 구조를 보존합니다.

🖼️ 포함 자산 — 이미지 및 포함 객체
Markdown에서 대체 텍스트로 이미지를 렌더링하고 원시 바이트와 미디어 유형을 기본 문서 모델에서 사용할 수 있게 유지합니다. 외부 이미지 URL은 일반 Markdown 이미지 링크가 됩니다. 목적: 호출자가 바이너리 자산을 유지, 재호스팅 또는 폐기할지 선택할 수 있게 합니다.

🔌 언어 바인딩 — 4개 런타임 대상
네이티브 Rust 크레이트, Node.js 패키지(libuv 스레드 풀을 통한 비차단), Python 패키지(GIL 해제), 브라우저용 WebAssembly 빌드를 제공합니다. 목적: 동일한 변환 로직을 백엔드 서비스, CLI, 노트북 또는 완전히 클라이언트 측에서 실행할 수 있게 합니다.

🤖 에이전트 통합 — 1개의 일급 Agent Skill
Claude Code, Codex, Cursor, OpenCode 및 기타 스킬 인식 에이전트와 호환되는 설치 가능한 Agent Skill(npx skills add firecrawl/anydoc)로 제공됩니다. 목적: 코딩 에이전트가 사용자 지정 글루 코드 없이 세션 중에 만나는 오피스 문서를 읽을 수 있게 합니다.

4. 주요 특징

• 하나의 문서 모델, 하나의 직렬화기. 모든 형식이 동일한 내부 Document 표현으로 파싱되고 단일 GFM 직렬화기를 통해 렌더링되므로 형식 버그가 파서별로가 아니라 모든 형식에 대해 한 번에 수정됩니다.
• 콘텐츠 기반 형식 감지. anydoc는 바이트 자체에서 PDF 헤더, RTF 시작 그룹, OLE 스트림 이름 또는 ZIP 패키지 mimetype을 읽으므로 잘못된 레이블이 있거나 확장자가 없는 파일도 올바르게 변환됩니다(Format::from_bytes).
• 5ms 미만의 중앙값 변환 시간. ML 모델이나 네트워크 호출이 없는 순수 Rust로, 게시된 벤치마크에 따르면 중앙값 변환 시간이 4.4ms로 LibreOffice, Pandoc 또는 Python 기반 대안보다 훨씬 빠릅니다.
• 독립적으로 벤치마크된 품질 선두주자. 14개 형식의 100개 실제 문서에 대해 6개의 다른 변환기와 비교했을 때, anydoc는 전체 형식 범위를 갖춘 유일한 도구였고 모든 평가된 형식에서 가장 높은 품질 점수를 받았습니다(페이지 렌더링된 실제 데이터를 기준으로 LLM 평가).
• 내장 PDF 지원. 텍스트 기반 PDF는 동반 pdf-inspector 크레이트를 통해 로컬에서 변환되며, 해당 경로에는 외부 OCR 서비스가 필요 없습니다.
• 형식화된 변형별 오류 처리. ConvertError 열거형(Unsupported, Malformed, Encrypted, ResourceLimit, MissingPart, Io)을 통해 호출 코드는 "이 파일 건너뛰기" 경우와 실제 실패를 구분할 수 있으며, Node/Wasm에서는 error.code로, Python에서는 형식화된 예외로 미러링됩니다.

5. 역할별 사용 사례

• 일반 개발자 — Rust, Node.js, Python 또는 브라우저/WASM의 문서 수집 파이프라인에 anydoc를 통합하여 형식별 별도 파서를 유지 관리하지 않고 혼합 형식 업로드를 Markdown으로 정규화합니다.
• 데이터/연구 과학자(및 AI/ML 엔지니어) — anydoc를 사용하여 이기종 코퍼스(보고서, 슬라이드 데크, 스프레드시트, CSV, PDF)를 임베딩, RAG 인덱싱 또는 LLM 컨텍스트 창에 적합한 깨끗하고 구조적으로 일관된 Markdown으로 변환합니다.
• 프로젝트 관리자/도구 팀 — Agent Skill을 채택하여 코딩 에이전트(Claude Code, Cursor, Codex, OpenCode)가 세션 중에 네이티브 오피스 형식으로 전달된 설계 문서, 사양 또는 회의 노트를 읽을 수 있게 합니다.

6. 시작하기

필요한 것 찾기
지원 형식 표와 바인딩별 API 참조(node/README.md, python/README.md, wasm/README.md)를 확인하여 형식과 런타임이 지원되는지 확인합니다.

설치/통합

# CLI(설치 불필요, 사전 빌드된 바이너리 실행)
npx @firecrawl/anydoc report.docx

# Node.js
npm install @firecrawl/anydoc

# Python
pip install firecrawl-anydoc

# Rust
cargo add anydoc

# 브라우저 / WebAssembly
npm install @firecrawl/anydoc-wasm

기여

git clone https://github.com/firecrawl/anydoc.git
cd anydoc
cargo test

GitHub 저장소에 직접 이슈 또는 풀 리퀘스트를 열 수 있습니다. 프로젝트는 또한 형식 지원을 추가하는 기여자를 위해 tests/ 및 fuzz/ 아래에 픽스처 기반 스냅샷 테스트, 변형 테스트 및 cargo-fuzz 대상을 유지 관리합니다.

7. 프로젝트 구조

anydoc/
├── src/            # 핵심 Rust 라이브러리: 형식 파서 + 문서 모델 + GFM 직렬화기
├── node/            # Node.js 바인딩(npm 패키지, TypeScript 타입)
├── python/           # Python 바인딩(maturin을 통한 PyPI 휠)
├── wasm/            # WebAssembly / 브라우저 바인딩
├── skills/          # Agent Skill 정의(convert-documents-to-markdown)
├── bench/            # 속도 및 품질 벤치마크 하네스
├── tests/            # 픽스처 코퍼스, 스냅샷 및 견고성 테스트
├── fuzz/             # 형식별 cargo-fuzz 대상
├── examples/          # 사용 예제
└── Cargo.toml         # 크레이트 매니페스트(게시된 버전의 소스)

src/에는 각 형식에 대한 파서가 하나씩 있으며, 모두 렌더링 전에 공유 Document 모델로 수렴됩니다. 이것이 저장소의 나머지 부분(바인딩, 벤치, 테스트)이 구축되는 아키텍처 핵심입니다.

8. 관련 생태계

• Firecrawl — 상위 플랫폼. anydoc의 변환 로직은 호스팅된 Firecrawl Parse API를 지원하며, 이 API는 스캔/이미지 전용 페이지에 OCR을 추가합니다.
• pdf-inspector — anydoc가 로컬, 비OCR PDF 텍스트 추출에 사용하는 동반 Rust 크레이트.
• Agent Skills — anydoc의 Agent Skill이 게시되는 생태계/사양으로, Claude Code, Codex, Cursor 및 OpenCode에서 검색할 수 있습니다.
• Crates.io / npm / PyPI — anydoc는 anydoc(크레이트), @firecrawl/anydoc 및 @firecrawl/anydoc-wasm(npm), firecrawl-anydoc(PyPI)로 공식 패키지를 게시합니다.

9. 라이선스

✅ 상업 및 클로즈드 소스 제품을 포함하여 자유롭게 사용, 수정 및 배포할 수 있습니다(MIT 라이선스).
✅ 자체 소스 코드를 공개하지 않고 독점 파이프라인 및 SaaS 제품에 자유롭게 포함할 수 있습니다.
❌ 보증은 제공되지 않습니다. 작성자는 사용으로 인한 손해에 대해 책임을 지지 않습니다.
ℹ️ MIT 라이선스 텍스트와 저작권 고지는 소프트웨어의 사본 또는 상당 부분에 유지되어야 합니다.

10. FAQ

Q: anydoc는 어떤 문서 형식을 지원하나요?
A: Word(.doc/.docx/.docm), PowerPoint(.ppt/.pptx/.pptm/.pps/.ppsx/.ppsm/.pot), Excel(.xls/.xlsx/.xlsm/.xlsb), OpenDocument(.odt/.ods/.odp), RTF, EPUB, CSV 및 PDF입니다.

Q: anydoc는 스캔된 PDF나 이미지에 대해 OCR을 수행하나요?
A: 아니요. anydoc는 pdf-inspector를 통해 텍스트 기반 PDF를 로컬에서 변환하지만 OCR은 포함하지 않습니다. 스캔된 문서의 경우 호스팅된 Firecrawl Parse API가 동일한 변환 엔진 위에 OCR 모델을 추가합니다.

Q: 아무것도 설치하지 않고 anydoc를 사용할 수 있나요?
A: 예, npx @firecrawl/anydoc report.docx를 실행하여 사전 빌드된 바이너리로 파일을 즉시 변환하거나 WebAssembly를 통해 완전히 클라이언트 측에서 실행되는 브라우저 데모를 사용해 볼 수 있습니다.

Q: anydoc는 파일 형식을 어떻게 감지하나요?
A: 확장자가 아닌 파일 콘텐츠에서 감지합니다. PDF 헤더, RTF 시작 그룹 마커, OLE 스트림 이름 또는 ZIP 패키지 mimetype/콘텐츠 유형을 읽습니다. CSV에는 이러한 마커가 없으므로 확장자 또는 명시적 형식 인수에 의존합니다.

Q: anydoc는 상업적 사용에 대해 어떻게 라이선스가 부여되나요?
A: MIT 라이선스이므로 상업 및 독점 소프트웨어에서 자유롭게 사용할 수 있습니다. 자세한 내용은 섹션 9를 참조하세요.

11. 빠른 링크

• 저장소: github.com/firecrawl/anydoc
• 라이브 데모 / 홈페이지: firecrawl.github.io/anydoc
• Node.js API 참조: node/README.md
• Python API 참조: python/README.md
• WebAssembly API 참조: wasm/README.md
• 벤치마크 방법론: bench/README.md
• Agent Skill 정의: skills/convert-documents-to-markdown/SKILL.md

12. 요약

anydoc는 팀에게 Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV 및 PDF 파일을 깔끔하고 구조적으로 충실한 Markdown으로 변환하는 단일하고 빠르며 의존성이 적은 방법을 제공합니다. 이는 이전에 품질이 고르지 않은 여러 형식별 도구를 연결해야 했던 작업입니다. 문서 수집 파이프라인을 구축하는 개발자, 임베딩 또는 LLM 컨텍스트를 위한 코퍼스를 준비하는 데이터/AI 팀, 그리고 즉석에서 오피스 문서를 읽어야 하는 코딩 에이전트에게 가장 적합하며, 모두 광범위한 형식 범위, 벤치마크된 출력 품질 및 밀리초 수준의 변환 속도의 조합에서 이점을 얻습니다.