Come convertire documenti in Markdown per l'IA in Python

Molte applicazioni che integrano LLM o agenti IA devono elaborare report, file PDF, fogli di calcolo e presentazioni come parte del proprio flusso di lavoro. Questi file memorizzano i contenuti in strutture diverse, specifiche per ciascun formato, per cui le applicazioni potrebbero dover estrarre e normalizzare i loro contenuti prima di utilizzarli in flussi di lavoro IA orientati al testo. Convertirli in Markdown offre una rappresentazione testuale coerente e ispezionabile che i componenti a valle possono leggere, memorizzare e manipolare senza dover gestire logiche di analisi specifiche per formato.

Questo tutorial mostra come convertire documenti Word, PDF, Excel e PowerPoint in Markdown in Python utilizzando Spire.Office for Python, e poi mostra come passare il contenuto Markdown risultante a una vera chiamata API di un LLM per la sintesi. L'obiettivo è illustrare un flusso di lavoro pratico di pre-elaborazione, non affermare che ogni modello IA richieda Markdown o che convertire un documento renda automaticamente i suoi contenuti adatti a ogni attività IA.

1. Perché usare Markdown per l'elaborazione di documenti con l'IA?

Markdown occupa una posizione utile in una pipeline di elaborazione documenti con l'IA. Rappresenta la struttura del documento tramite una sintassi leggera: i titoli diventano marcatori #, i paragrafi restano testo normale, gli elenchi usano i prefissi - o 1., e le tabelle mantengono le relazioni tra righe e colonne tramite il carattere pipe. Questa rappresentazione è leggibile dall'uomo, facile da memorizzare e semplice da trasformare a livello di programmazione.

Quando si convertono documenti in Markdown, il testo risultante può fungere da input per una serie di attività IA. Un LLM può riassumere il contenuto, estrarre entità chiave, rispondere a domande in merito o generare una versione rivista. Una pipeline di recupero può indicizzare il testo per la ricerca semantica. Un agente può leggere il Markdown per capire cosa contiene un documento prima di decidere quale strumento chiamare successivamente.

Vale la pena distinguere la pre-elaborazione in Markdown dall'invio diretto dei file. Alcune API dei modelli accettano file originali — immagini, PDF o documenti Office — tramite endpoint multimodali o funzionalità specializzate di elaborazione documenti. In questi casi, la conversione in Markdown non è necessaria. Markdown è una rappresentazione intermedia opzionale, scelta quando l'applicazione trae vantaggio da un formato testuale che può ispezionare e controllare prima di inviare il contenuto a un modello. La decisione dipende dai requisiti dell'applicazione, non da una regola universale secondo cui tutti i flussi di lavoro IA devono usare Markdown.

2. Convertire documenti in Markdown in Python

Spire.Office for Python è una suite di librerie Python standalone in grado di creare, leggere, modificare e convertire documenti Office senza installare Microsoft Office. Comprende quattro componenti, ciascuno dedicato a un formato di documento specifico:

Installare i pacchetti necessari:

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

Il supporto alla conversione in Markdown è stato introdotto in versioni diverse tra i vari componenti. La tabella seguente elenca le versioni minime che forniscono le API utilizzate in questo articolo:

Spire.Doc 12.6.0, Spire.PDF 11.6.1, Spire.XLS 16.4.0 e Spire.Presentation 10.11.1 sono le versioni minime con supporto alla conversione in Markdown. Si consiglia di utilizzare l'ultima versione di ciascun componente.

Ogni componente espone un'API diversa per la conversione in Markdown. La tabella seguente riassume i metodi di conversione verificati:

L'esempio seguente implementa un'unica funzione di dispatch che rileva l'estensione del file e indirizza il documento alla logica di conversione appropriata. Convalida il file di input, genera il percorso di output, esegue la conversione e gestisce gli errori con messaggi descrittivi.

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

Output Markdown dalla conversione di un documento Word:

Per dettagli specifici di ciascun formato, consultare i tutorial dei singoli componenti:

• Convertire Word in Markdown con Spire.Doc for Python
• Convertire PDF in Markdown con Spire.PDF for Python
• Convertire Excel in Markdown con Spire.XLS for Python

3. Inviare contenuti Markdown a un LLM

Una volta convertito un documento in Markdown, il testo può fungere da input per un LLM in attività come la sintesi, l'estrazione di informazioni o la risposta a domande. L'esempio seguente converte un report aziendale in Markdown, legge il file risultante e invia il contenuto all'API OpenAI con un'istruzione specifica per l'attività.

Per eseguire questo esempio, installare l'SDK Python di OpenAI e impostare la chiave API come variabile d'ambiente:

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

Il codice seguente presuppone che la funzione convert_to_markdown della sezione precedente sia salvata in un file denominato convert_to_markdown.py nella stessa directory, oppure che entrambi i blocchi di codice siano combinati in un unico script.

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 questo flusso di lavoro, Spire.Office for Python gestisce la conversione dei documenti e l'API OpenAI gestisce l'analisi IA. Spire.Office è una libreria di elaborazione documenti, non un framework per agenti IA: produce il testo Markdown che un LLM o una pipeline di agenti utilizza. Per un agente completo di elaborazione documenti, si consideri Spire.Agent.Office.

Una considerazione importante è la dimensione dell'input. Gli LLM hanno limiti di finestra di contesto, e un documento lungo può produrre Markdown che supera la lunghezza massima di input del modello. In questo caso, l'applicazione deve suddividere il Markdown in blocchi più piccoli o recuperare selettivamente le sezioni rilevanti prima di inviarle al modello. Librerie come langchain-text-splitters o una logica di suddivisione personalizzata possono gestire questo passaggio.

4. Usare Markdown per agenti IA e flussi di lavoro RAG

Il Markdown prodotto dalla fase di conversione può diventare input per flussi di lavoro IA più ampi. Due modelli comuni sono gli agenti IA e la generazione aumentata dal recupero (RAG).

Per gli agenti IA, un'applicazione può esporre il Markdown convertito come contesto che un agente legge prima di decidere quali azioni intraprendere. Ad esempio, un agente di assistenza potrebbe ricevere il Markdown di un contratto cliente e rispondere a domande su condizioni di rinnovo, piani di pagamento o clausole di risoluzione. L'agente tratta il Markdown come contesto leggibile, non come una query strutturata a un database.

Per il RAG, il contenuto Markdown viene suddiviso in blocchi, ogni blocco viene trasformato in una rappresentazione vettoriale tramite embedding e i vettori vengono memorizzati in un indice. Quando un utente pone una domanda, il sistema recupera i blocchi più pertinenti e li passa a un LLM insieme alla query. La struttura per sezioni del Markdown — titoli, paragrafi e tabelle — può fornire confini significativi per la suddivisione dei documenti. Una suddivisione consapevole dei titoli può aiutare a preservare il contesto, sebbene la qualità del recupero dipenda dal documento e dalla configurazione complessiva del sistema di recupero.

Convertire documenti in Markdown non implementa di per sé un sistema completo di agenti o RAG. Database vettoriali, modelli di embedding, framework di orchestrazione, protocolli di chiamata degli strumenti e ranking del recupero sono componenti separati che operano a valle. La fase di conversione produce il testo di input; il resto della pipeline determina come quel testo viene utilizzato.

5. Convalidare il Markdown prima dell'elaborazione IA

La qualità del Markdown convertito influisce direttamente sulla qualità dei risultati IA a valle. Se la conversione perde la struttura, rappresenta in modo errato i dati o omette contenuti, l'LLM o l'agente lavorerà con un contesto errato o incompleto. Prima di basarsi sul Markdown convertito per attività importanti, verificare l'output rispetto alle aree problematiche più comuni:

• Gerarchia dei titoli e ordine dei paragrafi. Assicurarsi che i livelli delle sezioni (#, ##, ###) riflettano la struttura del documento originale e che i paragrafi appaiano nella sequenza corretta.
• Righe, colonne e valori numerici delle tabelle. Verificare che le relazioni tra righe e colonne siano preservate e che numeri, date e valori di valuta corrispondano alla fonte. Se una tabella finanziaria perde il suo allineamento, un LLM potrebbe produrre un riepilogo basato su associazioni errate — ad esempio, attribuendo una cifra di ricavi alla regione sbagliata.
• Immagini, link e layout complessi. Markdown non può rappresentare ogni elemento visivo. Le immagini possono essere omesse o sostituite con riferimenti al percorso del file. Layout a più colonne, caselle di testo e oggetti incorporati potrebbero non sopravvivere alla conversione nella loro forma originale.
• PDF scansionati. Se il PDF di origine contiene immagini scansionate anziché testo incorporato, la conversione può produrre un output vuoto o quasi vuoto. In tali casi, è necessario un passaggio di OCR prima della conversione in Markdown o al suo posto.
• Documenti lunghi. Verificare che sia stato convertito l'intero documento, non solo la prima sezione. Per i documenti che superano la finestra di contesto di un modello, confermare che il Markdown possa essere suddiviso in blocchi significativi senza spezzare le tabelle o separare i titoli dal loro contenuto.

La conversione non garantisce la perfetta conservazione di ogni caratteristica visiva o semantica. L'output Markdown è una rappresentazione intermedia, non un clone fedele del documento originale. Rivedere il testo convertito prima di passarlo a un modello IA è un passo pratico che evita che gli errori si propaghino in riepiloghi, estrazioni o decisioni degli agenti.

6. Conclusione

Questo articolo ha illustrato un flusso di lavoro di pre-elaborazione da documento a Markdown per applicazioni IA in Python. Il processo ha tre fasi: convertire i formati di documento supportati (Word, PDF, Excel, PowerPoint) in Markdown usando Spire.Office for Python, verificare l'accuratezza strutturale dell'output convertito e passare il contenuto Markdown al componente di elaborazione IA appropriato — che si tratti di una chiamata API a un LLM, di un contesto per un agente o di una pipeline di suddivisione per RAG.

Markdown è un modo utile per preparare il contenuto dei documenti alle applicazioni IA, non un formato di input obbligatorio per ogni modello. La scelta di convertire i documenti in Markdown dipende dal fatto che l'applicazione tragga vantaggio da una rappresentazione intermedia testuale che può ispezionare, memorizzare e controllare. Per maggiori dettagli, visitare la pagina del prodotto Spire.Office for Python o la documentazione sulla conversione.

Vedi anche

• Come convertire HTML in Markdown in Python: guida passo passo
• Come convertire Markdown in HTML in Python: guida passo passo
• Python: convertire Markdown in PDF
• Convertire PDF in HTML usando Python: guida completa per sviluppatori