So konvertieren Sie Dokumente für KI in Python in Markdown

Viele Anwendungen, die LLMs oder KI-Agenten integrieren, müssen im Rahmen ihres Workflows Berichte, PDF-Dateien, Tabellenkalkulationen und Präsentationen verarbeiten. Diese Dateien speichern Inhalte in unterschiedlichen formatspezifischen Strukturen, sodass Anwendungen ihre Inhalte möglicherweise extrahieren und normalisieren müssen, bevor sie sie in textorientierten KI-Workflows verwenden. Die Konvertierung in Markdown bietet eine konsistente, überprüfbare Textdarstellung, die nachgelagerte Komponenten lesen, speichern und bearbeiten können, ohne sich mit formatspezifischer Parsing-Logik befassen zu müssen.

Dieses Tutorial zeigt, wie Sie Word-, PDF-, Excel- und PowerPoint-Dokumente in Python mit Spire.Office for Python in Markdown konvertieren, und zeigt anschließend, wie Sie den resultierenden Markdown-Inhalt an einen echten LLM-API-Aufruf zur Zusammenfassung übergeben. Das Ziel ist, einen praktischen Vorverarbeitungs-Workflow zu veranschaulichen – nicht zu behaupten, dass jedes KI-Modell Markdown erfordert oder dass die Konvertierung eines Dokuments seinen Inhalt automatisch für jede KI-Aufgabe geeignet macht.

1. Warum Markdown für die KI-Dokumentverarbeitung verwenden?

Markdown nimmt eine nützliche Position in einer KI-Dokumentverarbeitungspipeline ein. Es stellt die Dokumentstruktur durch eine leichtgewichtige Syntax dar: Überschriften werden zu #-Markierungen, Absätze bleiben reiner Text, Listen verwenden -- oder 1.-Präfixe, und Tabellen behalten Zeilen- und Spaltenbeziehungen mit Pipe-Zeichen bei. Diese Darstellung ist für Menschen lesbar, einfach zu speichern und unkompliziert programmatisch zu transformieren.

Wenn Sie Dokumente in Markdown konvertieren, kann der resultierende Text als Eingabe für eine Reihe von KI-Aufgaben dienen. Ein LLM kann den Inhalt zusammenfassen, wichtige Entitäten extrahieren, Fragen dazu beantworten oder eine überarbeitete Version generieren. Eine Retrieval-Pipeline kann den Text für die semantische Suche indexieren. Ein Agent kann das Markdown lesen, um zu verstehen, was ein Dokument enthält, bevor er entscheidet, welches Tool als Nächstes aufgerufen wird.

Es lohnt sich, die Markdown-Vorverarbeitung von der direkten Dateieingabe zu unterscheiden. Einige Modell-APIs akzeptieren Originaldateien – Bilder, PDFs oder Office-Dokumente – über multimodale Endpunkte oder spezialisierte Dokumentverarbeitungsfunktionen. In diesen Fällen ist eine Markdown-Konvertierung unnötig. Markdown ist eine optionale Zwischendarstellung, die gewählt wird, wenn die Anwendung von einem textbasierten Format profitiert, das sie überprüfen und kontrollieren kann, bevor sie Inhalte an ein Modell sendet. Die Entscheidung hängt von den Anforderungen der Anwendung ab, nicht von einer universellen Regel, dass alle KI-Workflows Markdown verwenden müssen.

2. Dokumente in Python in Markdown konvertieren

Spire.Office for Python ist eine Suite eigenständiger Python-Bibliotheken, die Office-Dokumente erstellen, lesen, bearbeiten und konvertieren können, ohne Microsoft Office zu installieren. Sie umfasst vier Komponenten, die jeweils auf ein bestimmtes Dokumentformat ausgerichtet sind:

Installieren Sie die benötigten Pakete:

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

Die Unterstützung für die Markdown-Konvertierung wurde in den einzelnen Komponenten in unterschiedlichen Versionen eingeführt. Die folgende Tabelle listet die Mindestversionen auf, die die in diesem Artikel verwendeten APIs bereitstellen:

Spire.Doc 12.6.0, Spire.PDF 11.6.1, Spire.XLS 16.4.0 und Spire.Presentation 10.11.1 sind die Mindestversionen mit Unterstützung für die Markdown-Konvertierung. Es wird empfohlen, die neueste Version jeder Komponente zu verwenden.

Jede Komponente stellt eine andere API für die Markdown-Konvertierung bereit. Die folgende Tabelle fasst die verifizierten Konvertierungsmethoden zusammen:

Das folgende Beispiel implementiert eine einzelne Dispatch-Funktion, die die Dateiendung erkennt und das Dokument an die entsprechende Konvertierungslogik weiterleitet. Sie validiert die Eingabedatei, generiert den Ausgabepfad, führt die Konvertierung durch und behandelt Fehler mit aussagekräftigen Meldungen.

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

Markdown-Ausgabe aus der Konvertierung eines Word-Dokuments:

Einzelheiten zu den Formaten finden Sie in den Tutorials der einzelnen Komponenten:

• Word mit Spire.Doc for Python in Markdown konvertieren
• PDF mit Spire.PDF for Python in Markdown konvertieren
• Excel mit Spire.XLS for Python in Markdown konvertieren

3. Markdown-Inhalt an ein LLM senden

Sobald ein Dokument in Markdown konvertiert wurde, kann der Text als Eingabe für ein LLM für Aufgaben wie Zusammenfassung, Informationsextraktion oder Fragebeantwortung dienen. Das folgende Beispiel konvertiert einen Geschäftsbericht in Markdown, liest die resultierende Datei und übermittelt den Inhalt mit einer aufgabenspezifischen Anweisung an die OpenAI-API.

Um dieses Beispiel auszuführen, installieren Sie das OpenAI Python SDK und legen Sie Ihren API-Schlüssel als Umgebungsvariable fest:

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

Der folgende Code geht davon aus, dass die convert_to_markdown-Funktion aus dem vorherigen Abschnitt in einer Datei namens convert_to_markdown.py im selben Verzeichnis gespeichert ist oder dass beide Codeblöcke zu einem einzigen Skript kombiniert werden.

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)

In diesem Workflow übernimmt Spire.Office for Python die Dokumentkonvertierung und die OpenAI-API die KI-Analyse. Spire.Office ist eine Dokumentverarbeitungsbibliothek, kein KI-Agent-Framework – sie erzeugt den Markdown-Text, den eine LLM- oder Agent-Pipeline konsumiert. Für einen vollständigen Dokumentverarbeitungsagenten sollten Sie Spire.Agent.Office in Betracht ziehen.

Ein wichtiger Aspekt ist die Eingabegröße. LLMs haben Grenzen für das Kontextfenster, und ein langes Dokument kann Markdown erzeugen, das die maximale Eingabelänge des Modells überschreitet. In diesem Fall muss die Anwendung das Markdown in kleinere Blöcke aufteilen oder relevante Abschnitte selektiv abrufen, bevor sie sie an das Modell sendet. Bibliotheken wie langchain-text-splitters oder benutzerdefinierte Aufteilungslogik können diesen Schritt übernehmen.

4. Markdown für KI-Agenten und RAG-Workflows verwenden

Das im Konvertierungsschritt erzeugte Markdown kann zu einer Eingabe für größere KI-Workflows werden. Zwei gängige Muster sind KI-Agenten und retrieval-augmentierte Generierung (RAG).

Für KI-Agenten kann eine Anwendung das konvertierte Markdown als Kontext bereitstellen, den ein Agent liest, bevor er entscheidet, welche Aktionen ausgeführt werden. Beispielsweise könnte ein Support-Agent das Markdown eines Kundenvertrags erhalten und Fragen zu Verlängerungsbedingungen, Zahlungsplänen oder Kündigungsklauseln beantworten. Der Agent behandelt das Markdown als lesbaren Kontext, nicht als strukturierte Datenbankabfrage.

Für RAG wird der Markdown-Inhalt in Blöcke aufgeteilt, jeder Block in eine Vektordarstellung eingebettet und die Vektoren in einem Index gespeichert. Wenn ein Benutzer eine Frage stellt, ruft das System die relevantesten Blöcke ab und übergibt sie zusammen mit der Anfrage an ein LLM. Die abschnittsbasierte Struktur von Markdown – Überschriften, Absätze und Tabellen – kann aussagekräftige Grenzen für die Dokumentaufteilung bieten. Überschriftenbewusstes Chunking kann helfen, den Kontext zu bewahren, obwohl die Retrieval-Qualität vom Dokument und vom gesamten Retrieval-Setup abhängt.

Die Konvertierung von Dokumenten in Markdown implementiert nicht selbst ein vollständiges Agenten- oder RAG-System. Vektordatenbanken, Embedding-Modelle, Orchestrierungsframeworks, Tool-Calling-Protokolle und Retrieval-Ranking sind separate Komponenten, die nachgelagert arbeiten. Der Konvertierungsschritt erzeugt die Texteingabe; der Rest der Pipeline bestimmt, wie dieser Text verwendet wird.

5. Markdown vor der KI-Verarbeitung validieren

Die Qualität des konvertierten Markdowns wirkt sich direkt auf die Qualität nachgelagerter KI-Ergebnisse aus. Wenn die Konvertierung Struktur verliert, Daten falsch darstellt oder Inhalte auslässt, arbeitet das LLM oder der Agent mit einem falschen oder unvollständigen Kontext. Bevor Sie sich bei wichtigen Aufgaben auf konvertiertes Markdown verlassen, prüfen Sie die Ausgabe auf die häufigsten Problembereiche:

• Überschriftenhierarchie und Absatzreihenfolge. Stellen Sie sicher, dass Abschnittsebenen (#, ##, ###) die Struktur des Originaldokuments widerspiegeln und dass Absätze in der richtigen Reihenfolge erscheinen.
• Tabellenzeilen, -spalten und numerische Werte. Überprüfen Sie, dass Zeilen-zu-Spalten-Beziehungen erhalten bleiben und dass Zahlen, Datumsangaben und Währungswerte mit der Quelle übereinstimmen. Wenn eine Finanztabelle ihre Ausrichtung verliert, kann ein LLM eine Zusammenfassung auf der Grundlage falscher Zuordnungen erstellen – zum Beispiel eine Umsatzzahl der falschen Region zuordnen.
• Bilder, Links und komplexe Layouts. Markdown kann nicht jedes visuelle Element darstellen. Bilder werden möglicherweise weggelassen oder durch Dateipfadverweise ersetzt. Mehrspaltige Layouts, Textfelder und eingebettete Objekte bleiben bei der Konvertierung möglicherweise nicht in ihrer ursprünglichen Form erhalten.
• Gescannte PDFs. Wenn das Quell-PDF gescannte Bilder statt eingebetteten Text enthält, kann die Konvertierung eine leere oder nahezu leere Ausgabe erzeugen. In solchen Fällen ist ein OCR-Schritt vor oder anstelle der Markdown-Konvertierung erforderlich.
• Lange Dokumente. Überprüfen Sie, dass das gesamte Dokument konvertiert wurde, nicht nur der erste Abschnitt. Bei Dokumenten, die das Kontextfenster eines Modells überschreiten, bestätigen Sie, dass das Markdown in sinnvolle Blöcke aufgeteilt werden kann, ohne Tabellen zu zerstören oder Überschriften von ihrem Inhalt zu trennen.

Die Konvertierung garantiert nicht die perfekte Bewahrung jedes visuellen oder semantischen Merkmals. Die Markdown-Ausgabe ist eine Zwischendarstellung, kein originalgetreuer Klon des ursprünglichen Dokuments. Die Überprüfung des konvertierten Textes vor der Übergabe an ein KI-Modell ist ein praktischer Schritt, der verhindert, dass sich Fehler in Zusammenfassungen, Extraktionen oder Agentenentscheidungen fortpflanzen.

6. Fazit

Dieser Artikel hat einen Dokument-zu-Markdown-Vorverarbeitungs-Workflow für KI-Anwendungen in Python durchlaufen. Der Prozess hat drei Phasen: Unterstützte Dokumentformate (Word, PDF, Excel, PowerPoint) mit Spire.Office for Python in Markdown konvertieren, die konvertierte Ausgabe auf strukturelle Genauigkeit überprüfen und den Markdown-Inhalt an die entsprechende KI-Verarbeitungskomponente übergeben – sei es ein LLM-API-Aufruf, ein Agentenkontext oder eine RAG-Chunking-Pipeline.

Markdown ist eine nützliche Möglichkeit, Dokumentinhalte für KI-Anwendungen vorzubereiten, aber kein vorgeschriebenes Eingabeformat für jedes Modell. Die Entscheidung, Dokumente in Markdown zu konvertieren, hängt davon ab, ob die Anwendung von einer textbasierten Zwischendarstellung profitiert, die sie überprüfen, speichern und kontrollieren kann. Weitere Details finden Sie auf der Produktseite Spire.Office for Python oder in der Konvertierungsdokumentation.

Siehe auch

• HTML in Python in Markdown konvertieren: Schritt-für-Schritt-Anleitung
• Markdown in Python in HTML konvertieren: Schritt-für-Schritt-Anleitung
• Python: Markdown in PDF konvertieren
• PDF mit Python in HTML konvertieren: Vollständiger Entwicklerleitfaden