AI 파이프라인에 문서를 바로 연결하세요 — Python에서 온‑프레미스로, pip install 한 번이면 됩니다.

오늘 우리는 Python용 GroupDocs.Markdown for .NET의 첫 번째 공개 릴리스를 PyPI에 배포했습니다. 이 라이브러리는 PDF, Word, Excel, EPUB 등 20가지 이상의 형식을 깔끔하고 의미론적인 Markdown으로 변환합니다 — LLM, RAG 파이프라인 및 정적 사이트 생성기가 가장 잘 활용하는 포맷입니다.

만약 여러분이 9월에 발표된 .NET 릴리스 (또는 26.3에서의 전체 API 개편)를 따라오고 있었다면, 그 이유는 동일합니다: 문서 포맷에는 의미가 담겨 있으며, 그 의미 구조를 보존하는 것이 RAG 시스템이 좋은 답변을 제공하게 하는 핵심입니다. 이전 글에서는 문제점(OCR이 구조를 평탄화하고, LLM이 Markdown을 필요로 함)과 해결책(문서를 순회하며 Markdown을 출력하는 DOM 기반 렌더러)을 깊이 있게 다루었으니 여기서는 다시 설명하지 않겠습니다.

대신, Python 개발자를 위한 새로운 기능에 집중해 보겠습니다.

What you get

  • 단일 휠, 런타임 의존성 없음. pip install groupdocs-markdown-net은 .NET 런타임과 필요한 모든 네이티브 라이브러리를 포함한 자체 포함 휠을 가져옵니다. dotnet 설치, Microsoft Office, Adobe Acrobat, 클라우드 서비스가 전혀 필요 없습니다.
  • 크로스‑플랫폼. Windows x64/x86, Linux x64, macOS x64 및 Apple Silicon (ARM64). Python 3.5부터 3.14까지 지원합니다.
  • Pythonic API. 클래스는 PascalCase, 메서드와 속성은 snake_case, 열거형 값은 UPPER_SNAKE_CASE를 사용합니다. 컨텍스트 매니저를 통해 로드된 문서를 결정적으로 해제할 수 있습니다.
  • 진정한 비동기 지원. 모든 정적 및 인스턴스 메서드에 _async 버전이 존재합니다. 파일 I/O는 비동기이며 CPU‑집약적인 변환은 워커 스레드에서 실행됩니다 — asyncio 이벤트 루프가 자유롭게 유지됩니다.
  • AI‑에이전트 친화적. 설치된 휠에는 AGENTS.md 파일이 포함되어 있어 코딩 어시스턴트(Claude Code, Cursor, GitHub Copilot, Codex)가 API 전체, 관용적인 사용 패턴, 트러블슈팅 팁을 자동으로 발견합니다. 문서는 llms.txt, 단일 파일 코퍼스(llms-full.txt), 페이지별 Markdown, 그리고 MCP 서버 형태로도 제공됩니다 — 아래 AI‑friendly by design 섹션을 참고하세요.

Get started

pip install groupdocs-markdown-net

가장 간단한 변환은 한 줄 코드입니다:

from groupdocs.markdown import MarkdownConverter

# 문자열로 변환
md = MarkdownConverter.to_markdown("business-plan.docx")

# 파일에 바로 저장
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

그게 전부입니다 — 설정도, 옵션도, 보일러플레이트도 필요 없습니다. 평가 모드에서는 처음 3페이지만 처리하고 워터마크를 추가합니다. 제한을 없애려면 라이선스를 적용하세요:

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

또는 GROUPDOCS_LIC_PATH 환경 변수를 설정하면 import 시 자동으로 적용됩니다.

지원 형식

Python 패키지는 .NET 라이브러리와 동일한 폭넓은 형식을 지원합니다:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • 스프레드시트 — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • 전자책 — .epub, .mobi
  • 텍스트 / 마크업 / 도움말 — .txt, .xml, .chm

Pythonic 예제

변환 옵션 및 이미지 전략

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # YAML 메타데이터 앞에 추가
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

변환 없이 문서 정보 조회

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

비밀번호가 걸린 파일 로드

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

스트림 및 컨텍스트 매니저

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

Async API — 다수 문서 동시 변환

파일 I/O가 비동기이기 때문에 asyncio.gather()를 사용하면 단일 워커가 여러 문서를 블로킹 없이 처리할 수 있습니다:

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

이 덕분에 FastAPI 같은 ASGI 프레임워크와도 자연스럽게 어울리며, 단일 워커가 많은 동시 변환 요청을 스레드 경쟁 없이 처리할 수 있습니다.

오류 처리

모든 변환 메서드는 실패 시 예외를 발생시키며, 일반적인 상황에 맞는 구체적인 예외 타입을 제공합니다:

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("잘못된 비밀번호이거나 비밀번호가 없습니다.")
except InvalidFormatException:
    print("파일이 손상되었거나 지원되지 않는 형식입니다.")
except GroupDocsMarkdownException as ex:
    print(f"변환 실패: {ex}")

RAG 및 LLM 파이프라인을 위해 설계됨

Markdown은 임베딩 모델과 검색 파이프라인이 가장 선호하는 입력 형식입니다 — 헤딩, 리스트, 테이블, 강조를 보존하면서도 청크와 토큰화가 용이합니다. 일반적인 RAG 인제스트 흐름은 다음과 같습니다:

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # RAG용 텍스트 전용
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# 최상위 헤딩 기준으로 분할 후 각 청크를 임베드/인덱스
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

라이브러리가 완전히 온‑프레미스로 동작하기 때문에 민감한 문서가 외부 환경으로 유출되지 않습니다 — 규제 산업, 법무팀, 내부 지식 베이스 등에서 흔히 요구되는 조건입니다.

AI‑friendly by design

대부분의 Python SDK는 AI 코딩 어시스턴트를 사후 고려 사항으로 다룹니다 — 개발자가 직접 문서를 가리키거나 예제를 붙여넣고, 시행착오를 겪어야 합니다. GroupDocs.Markdown for Python via .NET은 이 패러다임을 뒤집습니다: 라이브러리가 Claude Code, Cursor, GitHub Copilot, Codex 같은 에이전트가 별도 설정 없이 바로 활용할 수 있도록 설계되었습니다.

AGENTS.md가 휠에 포함됨

이 패키지는 AGENTS.md 파일을 설치된 휠 내부에 직접 포함한 최초의 GroupDocs 패키지입니다. 이 파일은 AI 코딩 어시스턴트를 위해 특별히 작성된 일반 Markdown README인 AGENTS.md 컨벤션을 따릅니다.

pip install groupdocs-markdown-net을 실행하면 다음 경로에 파일이 배치됩니다:

site-packages/groupdocs/markdown/AGENTS.md

AI 어시스턴트가 프로젝트를 열면 즉시 다음을 학습합니다:

  • 전체 공개 API(클래스, 메서드, 열거형, 예외)와 그 관계
  • 가장 흔한 시나리오에 대한 관용적인 사용 패턴 — 정적 vs 인스턴스 API, sync vs async, 이미지 전략, 프론트 매터, 오류 처리
  • 공통 함정 및 회피 방법 — 예를 들어 ConvertOptions 오버로드가 None을 허용하는 경우, 비밀번호가 걸린 파일 처리, 변환 경고 캡처 방법
  • 플랫폼별 트러블슈팅(macOS의 libSkiaSharp, Linux의 ICU 등)

실제로는 “groupdocs-markdown-net을 사용해 PDF 폴더를 RAG 파이프라인용 Markdown으로 변환해줘” 라고 요청하면 에이전트가 첫 시도부터 동작하는 코드를 생성합니다 — 메서드 이름을 헛갈리거나 인자 순서를 틀리거나, 임의의 import를 추측할 필요가 없습니다.

기계가 읽을 수 있는 문서

AGENTS.md에 없는 정보를 찾는 에이전트를 위해 전체 제품 문서는 기계가 읽을 수 있는 형태로도 제공됩니다:

  • 단일 파일 코퍼스 — 전체 문서를 하나의 연결된 Markdown 파일로 제공, 에이전트 컨텍스트에 바로 삽입 가능:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • 페이지별 Markdown — 문서 URL 뒤에 .md를 붙이면 원본 소스를 가져올 수 있음:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt 인덱스 — 에이전트가 필요한 페이지를 찾도록 돕는 llms.txt 스타일 목차:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP 서버를 통한 실시간 문서 조회

Model Context Protocol을 지원하는 에이전트를 위해 문서를 MCP 서버로도 제공합니다. Claude Code 또는 Cursor 설정에 다음을 추가하세요:

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

이후 에이전트는 최신 문서를 실시간으로 조회할 수 있어, 오래된 학습 데이터에 의존하지 않게 됩니다.

Markdown 입력, Markdown 출력

라이브러리의 출력이 Markdown이며, 이는 LLM이 RAG에 가장 잘 파싱하는 포맷입니다. 동시에 문서 자체도 Markdown으로 제공되어, 에이전트가 컨텍스트 윈도우에 쉽게 삽입할 수 있습니다. 즉, 에이전트가 라이브러리를 사용하도록 코드를 작성하든, 라이브러리를 통해 문서를 이해하도록 하든, 공통 매체는 Markdown입니다.

Export Example

위 스니펫은 라이브러리로 작성할 수 있는 가장 짧은 실용 프로그램에 가깝습니다. 아래는 동일한 아이디어를 실행 가능한 프로젝트 형태로 패키징한 예시입니다 — 원본 문서, Python 스크립트, 사전 생성된 출력, requirements.txt, Dockerfile을 모두 포함해 처음부터 아무것도 작성하지 않고도 끝까지 체험할 수 있습니다.

Source DOCX

원본 파일 business-plan.docx는 헤딩, 표, 이미지, 메타데이터가 풍부하게 포함된 짧은 사업계획서입니다.

Python script

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """GitHub flavor와 YAML 프론트 매터를 사용해 Word 문서를 Markdown으로 변환합니다."""

    # 한 줄 — Markdown 문자열 반환
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # 옵션 사용 — 파일에 기록
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

Output Markdown

quick-example.md 출력 파일은 문서 메타데이터에서 자동 추출된 YAML 프론트 매터 블록으로 시작하고, GitHub Flavored 테이블과 헤딩 계층이 한 단계 올려진 변환된 콘텐츠가 이어집니다 (큰 문서에 삽입하기에 적합).

Runnable sample app

모두 묶인 파일: sample-app.zip. 압축을 푼 뒤:

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

또는 Docker에서 실행 — 포함된 Dockerfile은 Linux에서 번들된 .NET 런타임이 필요로 하는 ICU 의존성을 설정합니다:

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

Summary

GroupDocs.Markdown for Python via .NET은 외부 런타임, 클라우드, 예상치 못한 의존성 없이 자체 포함 휠 형태로 전체 문서‑to‑Markdown 변환 엔진을 Python에 제공합니다. Pythonic API, async 지원, 그리고 AI 툴링과의 일등급 통합 덕분에 RAG 시스템, 정적 사이트 생성기, 문서 처리 파이프라인을 구축하는 Python 팀에게 실용적인 선택이 됩니다.

Learn more

Support & feedback

질문이나 기술 지원이 필요하시면 Free Support Forum을 이용해 주세요 — 언제든지 도와드리겠습니다.