Microsoft MarkItDown es una herramienta de código abierto que convierte archivos como PDF, Word, Excel, PowerPoint, imágenes, audios y videos de YouTube a formato Markdown. Su principal ventaja es reducir el consumo de tokens en modelos de lenguaje grande (LLMs), mejorando la eficiencia y reduciendo costos. Este artículo detalla cómo instalarlo y usarlo, ya sea a través de APIs o en entornos locales, para integrarlo con cualquier LLM, incluyendo Claude, GPT-4, Llama 3, Mistral AI y otros.

¿Por qué usar MarkItDown con LLMs?

Los modelos de lenguaje grande (LLMs) procesan el texto en unidades llamadas tokens. Cada token representa una parte del texto, y el costo de usar estos modelos depende directamente de la cantidad de tokens procesados. Cuando un LLM recibe un archivo en formato PDF, Word o HTML, debe analizar no solo el texto, sino también la estructura compleja del documento, lo que aumenta el consumo de tokens y, por tanto, el costo.

MarkItDown resuelve este problema al convertir estos archivos a Markdown, un formato de texto plano que preserva la estructura semántica (encabezados, listas, enlaces) pero elimina el ruido innecesario. Esto permite:

• Reducción de tokens: hasta un 90% menos tokens en comparación con formatos como PDF o HTML.
• Mayor precisión: los LLMs entienden mejor el contenido sin distracciones.
• Ahorro de costos: menos tokens procesados significa menor gasto en APIs de IA.
• Compatibilidad: funciona con cualquier LLM que acepte texto en Markdown.

Requisitos previos

Antes de instalar MarkItDown, asegúrate de cumplir con los siguientes requisitos:

Para instalación local

• Sistema operativo: Windows 10/11, macOS o Linux.
• Python: versión 3.8 o superior. Puedes verificar tu versión con el comando python --version.
• pip: administrador de paquetes de Python (generalmente se instala con Python).
• Git: para clonar el repositorio de MarkItDown (opcional, pero recomendado).
• Entorno virtual: recomendado para evitar conflictos entre dependencias.

Para uso con APIs

• Acceso a una API de LLM: como Claude, GPT-4, Llama 3, Mistral AI, etc.
• Clave API: proporcionada por el proveedor del LLM.
• Entorno de desarrollo: puede ser local o en la nube (como Google Colab, Jupyter Notebook, etc.).

Instalación de MarkItDown

Opción 1: Instalación local usando pip

Esta es la forma más sencilla de instalar MarkItDown en tu computadora.

1. Abre una terminal:
   • En Windows: usa Command Prompt o PowerShell.
   • En macOS/Linux: usa Terminal.
2. Crea un entorno virtual (recomendado):Esto evita conflictos con otras dependencias de Python en tu sistema.

   python -m venv markitdown_env

   Activa el entorno virtual:

   Advertisement
   • Windows: markitdown_env\Scripts\activate
   • macOS/Linux: source markitdown_env/bin/activate
3. Instala MarkItDown:Ejecuta el siguiente comando en la terminal:

   pip install markitdown

   Si el paquete no está disponible directamente en PyPI, puedes instalarlo desde el repositorio de GitHub:

   pip install git+https://github.com/microsoft/markitdown.git

4. Verifica la instalación:Ejecuta el siguiente comando para confirmar que MarkItDown se instaló correctamente:

   markitdown --version

Opción 2: Instalación usando GitHub

Si prefieres clonar el repositorio y trabajar con el código fuente directamente:

1. Clona el repositorio:git clone https://github.com/microsoft/markitdown.git
2. Accede al directorio:cd markitdown
3. Instala las dependencias:pip install -r requirements.txt
4. Instala el paquete en modo editable:pip install -e .

Opción 3: Instalación usando Docker

Si prefieres usar contenedores Docker para aislar el entorno:

1. Instala Docker: Descarga e instala Docker desde docker.com.
2. Crea un contenedor con MarkItDown:Ejecuta el siguiente comando para crear y activar un contenedor con MarkItDown:

   docker run -it --rm -v "$(pwd):/app" python:3.11 bash

3. Dentro del contenedor, instala MarkItDown:pip install git+https://github.com/microsoft/markitdown.git

Configuración para uso con LLMs

Uso local con Claude Code o herramientas similares

Si usas Claude Code, Codex o Cursor, puedes instalar MarkItDown directamente desde el chat:

1. Abre Claude Code en tu terminal o editor de código.
2. Copia y pega el siguiente prompt:Instala la herramienta MarkItDown de Microsoft desde https://github.com/microsoft/markitdown en mi computadora. Después úsala cada vez que te pida convertir un archivo (PDF, Word, Excel, PowerPoint, imagen, audio o video) a Markdown antes de leerlo. Avísame cuando termines de instalarla.
3. Claude Code descargará e instalará automáticamente la herramienta.
4. Cuando te pida permiso para ejecutar comandos, acepta.

Una vez instalado, puedes usar MarkItDown con prompts como:

• Usa MarkItDown para convertir el archivo /ruta/a/tu/archivo.pdf a Markdown y resúmelo.
• Convierte /ruta/a/tu/documento.docx a Markdown y extrae los puntos clave.

Uso con APIs de LLMs

Para integrar MarkItDown con APIs de LLMs como Claude API, OpenAI API o Mistral API, sigue estos pasos:

1. Convierte el archivo a Markdown:Usa MarkItDown para convertir el archivo de entrada a Markdown. Puedes hacerlo desde la línea de comandos:

   markitdown /ruta/a/tu/archivo.pdf -o salida.md

   Esto generará un archivo salida.md con el contenido en Markdown.

2. Envía el Markdown a la API del LLM:Usa el cliente de la API de tu LLM para enviar el contenido del archivo Markdown. Aquí tienes ejemplos para diferentes APIs:
   

   Ejemplo con Claude API (Anthropic):

   import anthropic

   client = anthropic.Anthropic(api_key="TU_CLAVE_API")

   with open("salida.md", "r") as file:

   markdown_content = file.read()

   message = client.messages.create(

   Advertisement

   model="claude-3-sonnet-20240229",

   max_tokens=1024,

   messages=[{"role": "user", "content": markdown_content}]

   )

   print(message.content)

   Advertisement

   Ejemplo con OpenAI API (GPT-4):

   import openai

   openai.api_key = "TU_CLAVE_API"

   with open("salida.md", "r") as file:

   markdown_content = file.read()

   response = openai.ChatCompletion.create(

   Advertisement

   model="gpt-4",

   messages=[{"role": "user", "content": markdown_content}]

   )

   print(response.choices[0].message.content)

   Ejemplo con Mistral API:

   import requests

   Advertisement

   api_key = "TU_CLAVE_API"

   url = "https://api.mistral.ai/v1/chat/completions"

   headers = {"Authorization": f"Bearer {api_key}"}

   with open("salida.md", "r") as file:

   markdown_content = file.read()

   Advertisement

   data = {

   "model": "mistral-tiny",

   "messages": [{"role": "user", "content": markdown_content}]

   }

   response = requests.post(url, headers=headers, json=data)

   Advertisement

   print(response.json()["choices"][0]["message"]["content"])

3. Procesa la respuesta:La API del LLM devolverá una respuesta en texto plano o Markdown, que puedes procesar según tus necesidades.

Uso con LLMs locales

Si estás ejecutando un LLM localmente (como Llama 3 o Mistral AI en tu computadora), puedes integrar MarkItDown de la siguiente manera:

1. Instala el LLM local:Por ejemplo, para ejecutar Llama 3 localmente, puedes usar Text Generation WebUI o LM Studio.
2. Convierte el archivo a Markdown:Usa MarkItDown para convertir el archivo de entrada:

   markitdown /ruta/a/tu/archivo.pdf -o salida.md

3. Carga el archivo Markdown en el LLM local:En la interfaz de tu LLM local (como Text Generation WebUI), carga el archivo salida.md y envía un prompt como:

   Resume el siguiente texto en español: [pegar contenido de salida.md]

4. Automatiza el proceso:Puedes crear un script en Python para automatizar la conversión y el envío al LLM local. Ejemplo:

   import subprocess

   # Convierte el archivo a Markdown

   subprocess.run(["markitdown", "/ruta/a/tu/archivo.pdf", "-o", "salida.md"])

   # Lee el archivo Markdown

   with open("salida.md", "r") as file:

   markdown_content = file.read()

   Advertisement

   # Envía el contenido al LLM local (ejemplo con requests a una API local)

   response = requests.post("http://localhost:5000/api/v1/chat", json={"content": markdown_content})

   print(response.json()["response"])

Ejemplos prácticos de uso

Ejemplo 1: Procesar un PDF con Claude API

Supongamos que tienes un PDF con un informe financiero y quieres que Claude lo analice:

1. Convierte el PDF a Markdown:markitdown informe_financiero.pdf -o informe.md
2. Envía el Markdown a Claude API:Usa el siguiente código en Python:

   import anthropic

   client = anthropic.Anthropic(api_key="TU_CLAVE_API")

   with open("informe.md", "r") as file:

   Advertisement

   markdown_content = file.read()

   message = client.messages.create(

   model="claude-3-sonnet-20240229",

   max_tokens=2048,

   messages=[{"role": "user", "content": f"Analiza el siguiente informe financiero y extrae las tendencias principales:\n{markdown_content}"}]

   Advertisement

   )

   print(message.content)

Ejemplo 2: Procesar un video de YouTube con Llama 3 local

Si tienes un video de YouTube y quieres extraer su transcripción para analizarla con Llama 3:

1. Convierte el video a Markdown:markitdown https://www.youtube.com/watch?v=XXXX -o transcripcion.md
2. Carga el Markdown en Llama 3:En la interfaz de Text Generation WebUI o LM Studio, carga el archivo transcripcion.md y envía un prompt como:

   Resume la siguiente transcripción en 5 puntos clave: [pegar contenido de transcripcion.md]

Ejemplo 3: Automatizar el procesamiento de múltiples archivos

Si necesitas procesar varios archivos (ej: PDFs de contratos) y extraer información específica:

1. Crea un script en Python:import os

   import subprocess

   import anthropic

   client = anthropic.Anthropic(api_key="TU_CLAVE_API")

2. Define una función para procesar cada archivo:def procesar_archivo(ruta_archivo):

   # Convierte el archivo a Markdown

   nombre_salida = os.path.splitext(ruta_archivo)[0] + ".md"

   subprocess.run(["markitdown", ruta_archivo, "-o", nombre_salida])

   Advertisement

   # Lee el archivo Markdown

   with open(nombre_salida, "r") as file:

   markdown_content = file.read()

   # Envía el contenido a Claude API

   message = client.messages.create(

   Advertisement

   model="claude-3-sonnet-20240229",

   max_tokens=1024,

   messages=[{"role": "user", "content": f"Extrae las cláusulas de confidencialidad del siguiente contrato:\n{markdown_content}"}]

   )

   return message.content

3. Procesa todos los archivos en una carpeta:carpeta = "/ruta/a/tus/archivos/"

   for archivo in os.listdir(carpeta):

   if archivo.endswith(".pdf"):

   Advertisement

   resultado = procesar_archivo(os.path.join(carpeta, archivo))

   print(f"Resultado para {archivo}: {resultado}")

Solución de problemas comunes

MarkItDown no se instala correctamente

• • Error: pip no encontrado: Asegúrate de que Python y pip estén instalados. Ejecuta python --version y pip --version para verificarlo.
  • Error de dependencias: Si hay conflictos entre dependencias, usa un entorno virtual:

python -m venv markitdown_env

source markitdown_env/bin/activate # macOS/Linux

markitdown_env\Scripts\activate # Windows

pip install markitdown

• Error al clonar el repositorio: Asegúrate de tener Git instalado y usa el comando git clone https://github.com/microsoft/markitdown.git.

MarkItDown no convierte correctamente el archivo

• • Archivo corrupto: Verifica que el archivo de entrada no esté dañado.
  • Formato no soportado: Asegúrate de que el archivo sea de un tipo soportado (PDF, Word, Excel, etc.).
  • Problemas de permisos: En Linux/macOS, asegúrate de tener permisos de lectura para el archivo:

chmod +r /ruta/a/tu/archivo.pdf

Errores al usar APIs de LLMs

• Clave API inválida: Verifica que tu clave API sea correcta y esté activa.
• Límite de tokens excedido: Reduce el tamaño del archivo Markdown o divide el contenido en partes más pequeñas.
• Error de conexión: Asegúrate de tener conexión a internet y de que la URL de la API sea correcta.

Buenas prácticas

Optimización del proceso

• Usa archivos pequeños: Si el archivo es muy grande, divídelo en partes más pequeñas antes de convertirlo a Markdown.
• Limpia el Markdown: Revisa el archivo Markdown generado para asegurarte de que no contenga errores o formato incorrecto.
• Prueba con archivos de ejemplo: Antes de procesar archivos importantes, prueba con archivos de ejemplo para asegurarte de que todo funcione correctamente.

Seguridad

• No compartas claves API: Nunca compartas tu clave API en código público o repositorios.
• Usa entornos virtuales: Para evitar conflictos entre proyectos, usa entornos virtuales de Python.
• Actualiza regularmente: Mantén MarkItDown y tus dependencias actualizadas para evitar vulnerabilidades de seguridad.

Conclusión

Microsoft MarkItDown es una herramienta poderosa para optimizar el uso de LLMs, ya sea a través de APIs o en entornos locales. Su capacidad para convertir archivos complejos a Markdown permite reducir el consumo de tokens, mejorar la precisión de las respuestas y ahorrar costos.

La instalación es sencilla y su integración con LLMs es flexible, lo que la hace ideal para desarrolladores, empresas y cualquier persona que trabaje con IA generativa. Ya sea que uses Claude, GPT, Llama o cualquier otro modelo, MarkItDown puede ayudarte a sacarle el máximo provecho.

Glosario rápido:

• LLM: modelo de lenguaje grande, como Claude o GPT-4.
• Token: unidad mínima de texto que procesan los modelos de IA.
• API: interfaz de programación de aplicaciones, permite la comunicación entre sistemas.
• Markdown: lenguaje de marcado ligero para formatear texto.
• Entorno virtual: espacio aislado para instalar dependencias de Python sin afectar el sistema global.
• Docker: plataforma para desarrollar, enviar y ejecutar aplicaciones en contenedores.
• Git: sistema de control de versiones para rastrear cambios en el código.