Python에서 바로, 온프레미스 환경에서, pip install 한 번으로 문서를 AI 파이프라인에 연결하세요.

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

만약 여러분이 .NET 9월 릴리스 (또는 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‑agent 친화적. 설치된 휠에는 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 시 자동으로 적용됩니다.

Supported formats

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

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Spreadsheets — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Text / Markup / Help — .txt, .xml, .chm

Pythonic examples

Conversion options and image strategies

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    # prepend YAML metadata
options.image_export_strategy = strategy

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

Document inspection without conversion

from groupdocs.markdown import MarkdownConverter

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

Loading a password‑protected file

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)

Streams and context managers

from groupdocs.markdown import MarkdownConverter

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

Async API — converting many documents concurrently

파일 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 프레임워크와도 자연스럽게 어울리며, 단일 워커가 많은 동시 변환 요청을 스레드 경쟁 없이 처리할 수 있습니다.

Error handling

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

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

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Wrong or missing password.")
except InvalidFormatException:
    print("File is corrupt or unsupported.")
except GroupDocsMarkdownException as ex:
    print(f"Conversion failed: {ex}")

Built for RAG and LLM pipelines

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, 이미지 전략, front matter, 오류 처리
  • 공통 함정 및 회피 방법 — 예를 들어 ConvertOptions 오버로드가 None을 허용하는 경우, 비밀번호 보호 파일 처리, 변환 경고 캡처 방법
  • 플랫폼별 문제에 대한 트러블슈팅( macOS의 libSkiaSharp, Linux의 ICU 등)

실제로 이는 “groupdocs-markdown-net을 사용해 PDF 폴더를 RAG 파이프라인용 Markdown으로 변환해줘” 라고 말하면 에이전트가 첫 시도부터 작동하는 코드를 작성한다는 의미이며, 잘못된 메서드 이름이나 인자 순서, 추측된 import 등은 발생하지 않습니다.

Machine‑readable documentation

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 server for live doc lookups

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

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

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

Markdown in, Markdown out

여기에는 멋진 대칭성이 있습니다: 라이브러리의 출력은 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 front matter를 사용해 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 front‑matter 블록으로 시작하고, 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을 이용해 주세요 — 기꺼이 도와드리겠습니다.