Python에서 AI를 위한 문서를 Markdown으로 변환하는 방법

LLM이나 AI 에이전트를 포함하는 많은 애플리케이션은 워크플로의 일부로 보고서, PDF 파일, 스프레드시트 및 프레젠테이션을 처리해야 합니다. 이러한 파일은 서로 다른 형식별 구조로 콘텐츠를 저장하므로, 애플리케이션은 텍스트 지향 AI 워크플로에서 사용하기 전에 콘텐츠를 추출하고 정규화해야 할 수 있습니다. 이를 Markdown으로 변환하면 다운스트림 구성 요소가 형식별 구문 분석 로직을 다루지 않고도 읽고, 저장하고, 조작할 수 있는 일관되고 검사 가능한 텍스트 표현을 제공합니다.

이 자습서에서는 Spire.Office for Python을 사용하여 Python에서 Word, PDF, Excel 및 PowerPoint 문서를 Markdown으로 변환하는 방법을 보여 주고, 그런 다음 결과 Markdown 콘텐츠를 요약을 위해 실제 LLM API 호출에 전달하는 방법을 보여 줍니다. 목표는 실용적인 전처리 워크플로를 설명하는 것이지, 모든 AI 모델에 Markdown이 필요하거나 문서를 변환한다고 해서 해당 콘텐츠가 모든 AI 작업에 자동으로 적합해진다고 주장하는 것이 아닙니다.

1. AI 문서 처리를 위해 Markdown을 사용하는 이유

Markdown은 AI 문서 처리 파이프라인에서 유용한 위치를 차지합니다. 경량 구문을 통해 문서 구조를 나타냅니다. 제목은 # 마커가 되고, 단락은 일반 텍스트로 유지되며, 목록은 - 또는 1. 접두사를 사용하고, 표는 파이프 문자로 행과 열 관계를 유지합니다. 이 표현은 사람이 읽기 쉽고, 저장하기 쉬우며, 프로그래밍 방식으로 변환하기 간단합니다.

문서를 Markdown으로 변환하면 결과 텍스트가 다양한 AI 작업의 입력으로 사용될 수 있습니다. LLM은 콘텐츠를 요약하고, 주요 개체를 추출하고, 콘텐츠에 대한 질문에 답변하거나, 수정된 버전을 생성할 수 있습니다. 검색 파이프라인은 텍스트를 시맨틱 검색을 위해 색인화할 수 있습니다. 에이전트는 다음에 호출할 도구를 결정하기 전에 문서에 무엇이 포함되어 있는지 이해하기 위해 Markdown을 읽을 수 있습니다.

Markdown 전처리와 직접 파일 입력을 구분할 가치가 있습니다. 일부 모델 API는 멀티모달 엔드포인트 또는 특수 문서 처리 기능을 통해 원본 파일(이미지, PDF 또는 Office 문서)을 받습니다. 이러한 경우 Markdown 변환은 불필요합니다. Markdown은 애플리케이션이 모델에 콘텐츠를 보내기 전에 검사하고 제어할 수 있는 텍스트 기반 형식의 이점을 얻을 때 선택되는 선택적 중간 표현입니다. 결정은 애플리케이션의 요구 사항에 따라 달라지며, 모든 AI 워크플로가 Markdown을 사용해야 한다는 보편적인 규칙에 따르지 않습니다.

2. Python에서 문서를 Markdown으로 변환

Spire.Office for Python은 Microsoft Office를 설치하지 않고도 Office 문서를 만들고, 읽고, 편집하고, 변환할 수 있는 독립 실행형 Python 라이브러리 모음입니다. 여기에는 특정 문서 형식을 대상으로 하는 네 가지 구성 요소가 포함되어 있습니다:

필요한 패키지를 설치합니다:

pip install spire.doc spire.pdf spire.xls spire.presentation

Markdown 변환 지원은 구성 요소마다 다른 버전에서 도입되었습니다. 아래 표에는 이 문서에서 사용된 API를 제공하는 최소 버전이 나와 있습니다:

Spire.Doc 12.6.0, Spire.PDF 11.6.1, Spire.XLS 16.4.0, Spire.Presentation 10.11.1은 Markdown 변환을 지원하는 최소 버전입니다. 각 구성 요소의 최신 버전을 사용하는 것이 좋습니다.

각 구성 요소는 Markdown 변환을 위해 서로 다른 API를 제공합니다. 다음 표에는 확인된 변환 방법이 요약되어 있습니다:

아래 예제는 파일 확장자를 감지하고 문서를 적절한 변환 논리로 라우팅하는 단일 디스패치 함수를 구현합니다. 입력 파일을 확인하고, 출력 경로를 생성하고, 변환을 수행하고, 설명 메시지와 함께 오류를 처리합니다.

import os
from spire.doc import Document, FileFormat as DocFileFormat
from spire.pdf import PdfToMarkdownConverter
from spire.xls import Workbook, MarkdownOptions as XlsMarkdownOptions
from spire.presentation import Presentation, FileFormat as PresentationFileFormat


def convert_to_markdown(input_path: str, output_path: str = None) -> str:
    """Convert a Word, PDF, Excel, or PowerPoint file to Markdown.

    Args:
        input_path: Path to the source document.
        output_path: Path for the output .md file. If None, uses the
            input filename with a .md extension in the same directory.

    Returns:
        The path to the generated Markdown file.
    """
    if not os.path.isfile(input_path):
        raise FileNotFoundError(f"Input file not found: {input_path}")

    ext = os.path.splitext(input_path)[1].lower()

    if output_path is None:
        output_path = os.path.splitext(input_path)[0] + ".md"

    if ext in (".doc", ".docx"):
        # Spire.Doc for Python: load and save as Markdown
        doc = Document()
        try:
            doc.LoadFromFile(input_path)
            doc.SaveToFile(output_path, DocFileFormat.Markdown)
        finally:
            doc.Close()

    elif ext == ".pdf":
        # Spire.PDF for Python: use PdfToMarkdownConverter
        # IgnoreImage=True skips images in the PDF; set to False if
        # charts or screenshots contain important information.
        converter = PdfToMarkdownConverter(input_path)
        try:
            converter.MarkdownOptions.IgnoreImage = True
            converter.ConvertToMarkdown(output_path)
        finally:
            converter.Dispose()

    elif ext in (".xls", ".xlsx"):
        # Spire.XLS for Python: use SaveToMarkdown with MarkdownOptions
        workbook = Workbook()
        try:
            workbook.LoadFromFile(input_path)
            options = XlsMarkdownOptions()
            options.SavePicInRelativePath = True
            options.SaveHyperlinkAsRef = False
            workbook.SaveToMarkdown(output_path, options)
        finally:
            workbook.Dispose()

    elif ext in (".ppt", ".pptx"):
        # Spire.Presentation for Python: load and save as Markdown
        presentation = Presentation()
        try:
            presentation.LoadFromFile(input_path)
            presentation.SaveToFile(output_path, PresentationFileFormat.Markdown)
        finally:
            presentation.Dispose()

    else:
        raise ValueError(
            f"Unsupported file extension: {ext}. "
            f"Supported formats: .doc, .docx, .pdf, .xls, .xlsx, .ppt, .pptx"
        )

    return output_path


# Example usage
if __name__ == "__main__":
    result = convert_to_markdown("quarterly_report.docx")
    print(f"Markdown saved to: {result}")

    with open(result, "r", encoding="utf-8") as f:
        content = f.read()
    print(content[:500])  # Preview the first 500 characters

Word 문서를 변환한 Markdown 출력:

형식별 세부 정보는 개별 구성 요소 자습서를 참조하세요:

• Spire.Doc for Python으로 Word를 Markdown으로 변환
• Spire.PDF for Python으로 PDF를 Markdown으로 변환
• Spire.XLS for Python으로 Excel을 Markdown으로 변환

3. Markdown 콘텐츠를 LLM에 전송

문서가 Markdown으로 변환되면 해당 텍스트는 요약, 정보 추출 또는 질문 답변과 같은 작업을 위해 LLM의 입력으로 사용될 수 있습니다. 다음 예제는 비즈니스 보고서를 Markdown으로 변환하고, 결과 파일을 읽고, 작업별 지침과 함께 콘텐츠를 OpenAI API에 제출합니다.

이 예제를 실행하려면 OpenAI Python SDK를 설치하고 API 키를 환경 변수로 설정하세요:

pip install openai
export OPENAI_API_KEY="your-api-key"

아래 코드는 이전 섹션의 convert_to_markdown 함수가 같은 디렉터리의 convert_to_markdown.py 파일에 저장되어 있거나 두 코드 블록이 단일 스크립트로 결합되어 있다고 가정합니다.

import os
from openai import OpenAI

# Step 1: Convert the document to Markdown
from convert_to_markdown import convert_to_markdown
md_path = convert_to_markdown("business_report.pdf")

# Step 2: Read the Markdown content
with open(md_path, "r", encoding="utf-8") as f:
    markdown_content = f.read()

# Step 3: Construct a task-specific instruction and call the LLM
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

response = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[
        {
            "role": "system",
            "content": "You are a financial analyst. Read the document "
                       "and extract the three most important findings."
        },
        {
            "role": "user",
            "content": f"Here is the document content in Markdown:\n\n"
                       f"{markdown_content}\n\n"
                       f"Provide a concise summary of the key findings."
        }
    ],
    max_completion_tokens=1000
)

# Step 4: Read and display the response
summary = response.choices[0].message.content
print("=== LLM Summary ===")
print(summary)

이 워크플로에서 Spire.Office for Python은 문서 변환을 처리하고 OpenAI API는 AI 분석을 처리합니다. Spire.Office는 문서 처리 라이브러리이지 AI 에이전트 프레임워크가 아닙니다. 즉, LLM 또는 에이전트 파이프라인이 소비하는 Markdown 텍스트를 생성합니다. 완전한 문서 처리 에이전트를 원한다면 Spire.Agent.Office를 고려하세요.

한 가지 중요한 고려 사항은 입력 크기입니다. LLM에는 컨텍스트 창 제한이 있으며, 긴 문서는 모델의 최대 입력 길이를 초과하는 Markdown을 생성할 수 있습니다. 이 경우 애플리케이션은 모델에 보내기 전에 Markdown을 더 작은 청크로 분할하거나 관련 섹션을 선택적으로 검색해야 합니다. langchain-text-splitters와 같은 라이브러리 또는 사용자 지정 분할 로직이 이 단계를 처리할 수 있습니다.

4. AI 에이전트 및 RAG 워크플로에 Markdown 사용

변환 단계에서 생성된 Markdown은 더 큰 AI 워크플로의 입력이 될 수 있습니다. 두 가지 일반적인 패턴은 AI 에이전트와 검색 증강 생성(RAG)입니다.

AI 에이전트의 경우, 애플리케이션은 에이전트가 수행할 작업을 결정하기 전에 읽는 컨텍스트로 변환된 Markdown을 노출할 수 있습니다. 예를 들어, 지원 에이전트는 고객 계약서의 Markdown을 받고 갱신 조건, 지불 일정 또는 해지 조항에 대한 질문에 답변할 수 있습니다. 에이전트는 Markdown을 구조화된 데이터베이스 쿼리가 아니라 읽을 수 있는 컨텍스트로 취급합니다.

RAG의 경우, Markdown 콘텐츠는 청크로 분할되고, 각 청크는 벡터 표현으로 임베딩되며, 벡터는 인덱스에 저장됩니다. 사용자가 질문을 하면 시스템은 가장 관련성 높은 청크를 검색하여 쿼리와 함께 LLM에 전달합니다. Markdown의 섹션 기반 구조(제목, 단락 및 표)는 문서 청킹에 의미 있는 경계를 제공할 수 있습니다. 제목 인식 청킹은 컨텍스트를 보존하는 데 도움이 될 수 있지만, 검색 품질은 문서와 전체 검색 설정에 따라 달라집니다.

문서를 Markdown으로 변환하는 것만으로는 완전한 에이전트나 RAG 시스템을 구현할 수 없습니다. 벡터 데이터베이스, 임베딩 모델, 오케스트레이션 프레임워크, 도구 호출 프로토콜 및 검색 순위는 다운스트림에서 작동하는 별도의 구성 요소입니다. 변환 단계는 텍스트 입력을 생성하고, 파이프라인의 나머지는 해당 텍스트가 어떻게 사용되는지를 결정합니다.

5. AI 처리 전에 Markdown 유효성 검사

변환된 Markdown의 품질은 다운스트림 AI 결과의 품질에 직접적인 영향을 미칩니다. 변환에서 구조가 손실되거나, 데이터가 잘못 표현되거나, 콘텐츠가 누락되면 LLM 또는 에이전트는 부정확하거나 불완전한 컨텍스트로 작업하게 됩니다. 중요한 작업에 변환된 Markdown을 사용하기 전에 가장 일반적인 문제 영역에 대해 출력을 확인하세요:

• 제목 계층 및 단락 순서. 섹션 수준(#, ##, ###)이 원본 문서의 구조를 반영하고 단락이 올바른 순서로 나타나는지 확인합니다.
• 표 행, 열 및 숫자 값. 행과 열 관계가 유지되고 숫자, 날짜 및 통화 값이 원본과 일치하는지 확인합니다. 재무 표가 정렬을 잃으면 LLM이 잘못된 연결을 기반으로 요약을 생성할 수 있습니다. 예를 들어 수익 수치를 잘못된 지역에 귀속시키는 경우입니다.
• 이미지, 링크 및 복잡한 레이아웃. Markdown은 모든 시각적 요소를 표현할 수 없습니다. 이미지는 생략되거나 파일 경로 참조로 대체될 수 있습니다. 다단 레이아웃, 텍스트 상자 및 포함된 개체는 변환 후 원래 형태로 유지되지 않을 수 있습니다.
• 스캔한 PDF. 원본 PDF에 포함된 텍스트가 아니라 스캔한 이미지가 포함된 경우 변환 결과가 비어 있거나 거의 비어 있을 수 있습니다. 이러한 경우 Markdown 변환 전에 또는 대신 OCR 단계가 필요합니다.
• 긴 문서. 첫 번째 섹션뿐만 아니라 전체 문서가 변환되었는지 확인합니다. 모델의 컨텍스트 창을 초과하는 문서의 경우 표를 깨뜨리거나 제목을 콘텐츠와 분리하지 않고 Markdown을 의미 있는 청크로 분할할 수 있는지 확인합니다.

변환은 모든 시각적 또는 의미적 특징을 완벽하게 보존한다고 보장하지 않습니다. Markdown 출력은 원본 문서의 충실한 복제본이 아니라 중간 표현입니다. AI 모델에 전달하기 전에 변환된 텍스트를 검토하는 것은 오류가 요약, 추출 또는 에이전트 결정으로 전파되는 것을 방지하는 실용적인 단계입니다.

6. 결론

이 문서에서는 Python에서 AI 애플리케이션을 위한 문서-대-Markdown 전처리 워크플로를 살펴보았습니다. 프로세스에는 세 단계가 있습니다. Spire.Office for Python을 사용하여 지원되는 문서 형식(Word, PDF, Excel, PowerPoint)을 Markdown으로 변환하고, 변환된 출력의 구조적 정확성을 확인하고, Markdown 콘텐츠를 적절한 AI 처리 구성 요소(LLM API 호출, 에이전트 컨텍스트 또는 RAG 청킹 파이프라인)에 전달합니다.

Markdown은 AI 애플리케이션을 위해 문서 콘텐츠를 준비하는 한 가지 유용한 방법이지, 모든 모델에 필수적인 입력 형식은 아닙니다. 문서를 Markdown으로 변환할지 여부는 애플리케이션이 검사, 저장 및 제어할 수 있는 텍스트 기반 중간 표현의 이점을 얻을 수 있는지에 따라 달라집니다. 자세한 내용은 Spire.Office for Python 제품 페이지 또는 변환 설명서를 방문하세요.

참고 항목

• Python에서 HTML을 Markdown으로 변환하는 방법: 단계별 가이드
• Python에서 Markdown을 HTML로 변환하는 방법: 단계별 가이드
• Python: Markdown을 PDF로 변환
• Python을 사용하여 PDF를 HTML로 변환: 완전한 개발자 가이드