DeepSeek-OCR en local: leer sus PDF escaneados

#Por qué DeepSeek-OCR en lugar de un OCR clásico

Un PDF escaneado no contiene texto, solo imágenes de texto. Un motor de OCR clásico como Tesseract extrae líneas sin formato: no sabe que un bloque es un título, rompe las tablas y pierde el orden de lectura de una página en dos columnas. DeepSeek-OCR aborda el problema de otra manera. Es un modelo de visión y lenguaje: observa la página completa y genera directamente Markdown con sus títulos, listas, tablas y fórmulas.

El modelo fue publicado por DeepSeek en otoño de 2025, con un artículo titulado « Contexts Optical Compression ». La idea central es representar una página mediante un pequeño número de tokens visuales, entre 64 y 400 según el modo de resolución, en lugar de los miles de tokens de texto que contendría. El editor anuncia una precisión de decodificación de aproximadamente el 97 % cuando la proporción de compresión se mantiene por debajo de diez. Es su cifra, medida con sus propios conjuntos de datos, no la nuestra: quédense sobre todo con que el modelo es ligero y rápido para lo que hace.

Para un uso local, importan tres cosas. El modelo cabe en una tarjeta gráfica de gama de entrada. Genera Markdown que se puede indexar tal cual en una cadena de RAG. Y está disponible en la biblioteca Ollama, lo que evita instalar PyTorch, Flash Attention y vLLM, como exige el repositorio oficial. Las especificaciones completas están en la ficha del modelo: https://quelllm.fr/modele/deepseek-ocr

#Requisitos previos y memoria que debes prever

La ficha del modelo en el sitio ofrece las referencias de VRAM por precisión: aproximadamente 2 GB en Q4, 4 GB en Q8 y 6 GB en FP16, para un contexto de 8 192 tokens. El peso real que hay que descargar depende de lo que Ollama haya empaquetado en la etiqueta; la página de etiquetas de la biblioteca muestra el tamaño del archivo y es la que cuenta. A eso hay que añadir la memoria del contexto: una página densa convertida a Markdown puede producir varios miles de tokens de salida.

GPU NVIDIA

Cualquier tarjeta de 8 GB o más ofrece un margen cómodo. Una RTX 3060 de 12 GB o una RTX 4070 de 12 GB ejecutan el modelo en FP16 con margen para el contexto.

Mac Apple Silicon

Ollama utiliza memoria unificada. Un Mac con 16 GB basta para el modelo solo; calcula 24 GB si quieres mantener cargado al lado un modelo de chat para el RAG.

Sin GPU

Es posible, pero la codificación de la imagen y la generación del Markdown se realizan en el procesador. Para unas pocas páginas es tolerable; para un lote de cien páginas, espera minutos por página según la máquina.

Programas

Ollama actualizado, poppler-utils para dividir los PDF y Python 3 con la biblioteca ollama si quiere automatizar el procesamiento por lotes.

#Paso 1: comprobar Ollama y obtener la etiqueta correcta

DeepSeek-OCR llegó a la biblioteca Ollama a finales de 2025, después de la publicación del modelo. Se basa en un codificador visual particular, DeepEncoder, que combina un módulo de ventanas locales y un módulo de atención global. Ollama tuvo que añadir la compatibilidad con esta arquitectura a su motor: un runtime anterior descarga los pesos, pero se niega a cargarlos, con un mensaje que indica que el modelo requiere una versión más reciente. La página de la biblioteca muestra la versión mínima requerida cuando corresponde.

# Version installée (comparez avec la version minimale affichée sur ollama.com/library/deepseek-ocr)
ollama -v

# Récupérer le modèle (le tag 3b est celui référencé par la fiche modèle)
ollama pull deepseek-ocr:3b

# Vérifier l'architecture, le contexte et la quantification empaquetée
ollama show deepseek-ocr:3b

El comando show es la única fuente fiable para saber qué acabas de descargar: indica la familia del modelo, el número de parámetros, la longitud de contexto y el nivel de cuantización. Si la etiqueta latest y la etiqueta 3b apuntan al mismo resumen, da igual cuál utilices; la guía emplea 3b para ser explícita.

#Paso 2: preparar las páginas del PDF

Ollama no abre archivos PDF. Acepta imágenes PNG o JPEG, una por solicitud. Por tanto, la primera operación consiste en rasterizar el documento, página por página. La herramienta más sencilla es pdftoppm, incluida en poppler-utils, disponible en todas las distribuciones de Linux y mediante Homebrew en macOS.

# Debian/Ubuntu : sudo apt install poppler-utils
# macOS : brew install poppler
# Arch : sudo pacman -S poppler

mkdir -p pages
pdftoppm -r 200 -png scan.pdf pages/page
ls pages
# pages/page-1.png  pages/page-2.png  ...  (numérotation complétée par des zéros selon le nombre de pages)

La resolución merece un minuto de reflexión. DeepSeek-OCR trabaja con resoluciones fijas: 512, 640, 1024 o 1280 píxeles por lado según el modo, además de un modo dinámico llamado Gundam que divide la página en teselas de 640 píxeles alrededor de una vista global de 1024. Una página A4 rasterizada a 200 puntos por pulgada mide aproximadamente 1 650 por 2 340 píxeles; Ollama la redimensiona antes de enviarla al codificador. Subir a 300 puntos por pulgada no aporta nada al modelo y aumenta innecesariamente el tamaño de los archivos. Bajar a 100 hace que se pierdan los caracteres pequeños de las notas al pie antes incluso de que el modelo los vea.

Si el escaneo está torcido o presenta mucho contraste, el modelo suele desenvolverse mejor que un OCR línea por línea, pero sigue siendo beneficioso enderezarlo previamente. La guía de Tesseract del sitio detalla los preprocesamientos útiles, que también se aplican aquí: https://quelllm.fr/guide/tesseract-ocr-guide-local

#Paso 3: obtener Markdown con deepseek ocr

El repositorio oficial documenta varias instrucciones, cada una de las cuales desencadena un comportamiento diferente del modelo. Las dos principales son «Convert the document to markdown.» para una conversión estructurada y «Free OCR.» para una transcripción sin formato. Las instrucciones están en inglés en el entrenamiento; manténgalas tal cual, ya que el texto reconocido se genera en el idioma del documento. Con el cliente de línea de comandos, la ruta de la imagen se coloca directamente en el prompt.

# Conversion structurée (titres, listes, tableaux)
ollama run deepseek-ocr:3b "Convert the document to markdown. ./pages/page-1.png"

# Transcription brute, sans structure
ollama run deepseek-ocr:3b "Free OCR. ./pages/page-1.png"

La misma operación mediante la API local, que escucha de forma predeterminada en http://localhost:11434, codifica la imagen en base64 en el campo images. Es la vía que conviene priorizar en cuanto encadenas páginas o llamas al modelo desde otro programa.

# Linux (GNU coreutils). Sur macOS, remplacez base64 -w0 par base64 -i pages/page-1.png
curl http://localhost:11434/api/generate -d "{
  \"model\": \"deepseek-ocr:3b\",
  \"prompt\": \"Convert the document to markdown.\",
  \"images\": [\"$(base64 -w0 pages/page-1.png)\"],
  \"stream\": false,
  \"options\": { \"num_ctx\": 8192, \"temperature\": 0 }
}"

Dos opciones merecen quedar fijadas. La temperatura a cero hace que la salida sea reproducible, que es lo que se espera de un OCR. El contexto de 8 192 tokens corresponde al límite del modelo; por debajo, una página densa puede truncarse en plena celda de una tabla. El repositorio oficial también menciona instrucciones específicas para describir una figura o localizar texto mediante coordenadas; sirven de poco para un simple PDF que indexar.

#Paso 4: procesar un PDF entero

Para un documento de varias decenas de páginas, basta un script de Python de unas pocas líneas. Recorre las imágenes en orden numérico, llama a Ollama página por página, elimina las etiquetas de localización que el modelo puede insertar y concatena todo en un único archivo Markdown con un marcador por página. El marcador resulta útil después para encontrar la página de origen de un pasaje citado por tu RAG.

pip install ollama

import pathlib
import re
import ollama

MODEL = "deepseek-ocr:3b"
PROMPT = "Convert the document to markdown."

# Tri numérique : page-2 avant page-10
pages = sorted(
    pathlib.Path("pages").glob("page-*.png"),
    key=lambda p: int(re.search(r"(\d+)", p.stem).group(1)),
)

parts = []
for page in pages:
    r = ollama.generate(
        model=MODEL,
        prompt=PROMPT,
        images=[str(page)],
        options={"num_ctx": 8192, "temperature": 0},
    )
    md = r["response"]
    # Balises de localisation éventuelles : on garde le texte, on jette les coordonnées
    md = re.sub(r"<\|ref\|>(.*?)<\|/ref\|><\|det\|>.*?<\|/det\|>", r"\1", md, flags=re.S)
    parts.append(f"<!-- {page.name} -->\n{md.strip()}\n")
    print(f"{page.name} : {len(md)} caractères")

pathlib.Path("scan.md").write_text("\n\n".join(parts), encoding="utf-8")

Cada llamada es independiente: el modelo no conserva ninguna memoria de la página anterior. Es una limitación para las tablas que se extienden por dos páginas, y una ventaja para la robustez, ya que una página fallida no contamina otra. Ollama carga el modelo una vez y lo mantiene en memoria entre llamadas, según el valor de la variable OLLAMA_KEEP_ALIVE; solo pagas el tiempo de carga al principio del lote.

Si dispone de una tarjeta con margen, la opción OLLAMA_NUM_PARALLEL permite procesar varias páginas al mismo tiempo, a costa de VRAM adicional para cada contexto. En una tarjeta de 12 GB, dos solicitudes paralelas siguen siendo razonables con un modelo de este tamaño; compruebe con nvidia-smi que no se desborde la memoria del sistema, porque el ralentizamiento es entonces drástico.

#Paso 5: limpiar y comprobar la salida

El Markdown generado se lee bien, pero no necesariamente se indexa bien tal cual. Antes de enviarlo a una base de datos vectorial, revise tres puntos.

1. 01
   Las etiquetas residuales

   Con la instrucción de conversión, el modelo se entrena con un token de localización y puede devolver coordenadas entre las etiquetas ref y det. El script anterior las elimina. Comprueba que tampoco queden etiquetas de imagen ni fragmentos de instrucciones al principio del archivo.
2. 02
   Las cifras y las tablas

   Un modelo de visión-lenguaje genera texto; por tanto, puede inventar un valor plausible en una celda ilegible, mientras que un OCR clásico habría dejado un carácter anómalo. Abre las tablas financieras o técnicas junto al escaneo y compara una de cada diez filas. Para las facturas, la guía específica del sitio explica cómo contrastarlas con totales: https://quelllm.fr/guide/extraction-factures-ocr-llm
3. 03
   Los encabezados y pies de página

   Números de página, nombre del documento, avisos legales repetidos: aparecen en cada página y contaminan la división en segmentos. Por lo general, basta una expresión regular en las líneas idénticas presentes en más de la mitad de las páginas para eliminarlos.
4. 04
   Los acentos y la tipografía francesa

   El editor anuncia un entrenamiento en un centenar de idiomas. Aun así, controla las letras acentuadas, las comillas francesas y los espacios inseparables antes de los signos dobles en una muestra: ahí se esconden los errores discretos que después distorsionan una búsqueda léxica.

Una vez limpio, el archivo entra en una cadena RAG como cualquier Markdown: división por títulos, embeddings y base de datos vectorial. La introducción al RAG local del sitio retoma estos pasos: https://quelllm.fr/guide/rag-local-introduction

#Límites y solución de problemas

El modelo responde sin mirar la imagen

O bien Ollama es demasiado antiguo para esta arquitectura, o bien no se ha transmitido la imagen. En la línea de comandos, la ruta debe ser absoluta o relativa al directorio actual, sin comillas alrededor de la propia ruta. Mediante la API, compruebe que el campo images contiene realmente base64 sin saltos de línea.

Salida cortada a mitad de una tabla

El contexto es demasiado corto para la página. Asigna 8192 a num_ctx si no lo has hecho. Si la página sigue excediendo el límite, divídela en dos imágenes, superior e inferior, con una superposición de unas líneas.

Página leída en el orden incorrecto

En una maquetación de tres columnas o un formulario con casillas, el modelo puede mezclar los bloques. Prueba la instrucción Free OCR, que sigue el orden espacial de forma más sencilla, o utiliza Docling, cuyo análisis de maquetación es explícito.

Lentitud anormal

Comprueba con ollama ps que el modelo esté bien cargado en la GPU y no parcialmente en el procesador. Un contexto demasiado grande o un segundo modelo cargado pueden hacer que se desborde en la memoria del sistema.

Texto manuscrito

DeepSeek-OCR se ha entrenado con documentos impresos y representaciones de páginas. Con escritura manuscrita, los resultados varían mucho; no dependas de él sin hacer una prueba previa.

Documentos largos y contexto entre páginas

Cada página se procesa de forma aislada. Una tabla que continúa en la página siguiente pierde sus encabezados; hay que volver a inyectarlos manualmente o mediante una regla de posprocesamiento.

#Cuándo bastan PaddleOCR, Docling o Tesseract

DeepSeek-OCR no es la respuesta para todos los escaneos. Brilla cuando la página tiene una estructura que conservar y quieres Markdown sin montar un pipeline. En muchos casos habituales, una herramienta más sencilla o especializada funciona igual de bien, con menos recursos y menos riesgo de invención.

Tesseract

Texto limpio e impreso sobre fondo blanco, en grandes cantidades, y solo necesitas el texto. Se ejecuta en el procesador, no genera nada y, por tanto, no inventa nada. Guía: https://quelllm.fr/guide/tesseract-ocr-guide-local

PaddleOCR

Texto colocado en cualquier parte de la página, escaneos inclinados y tablas que deben reconstruirse con una etapa de detección explícita antes de la lectura. Su variante VL también es un modelo de visión, más pequeño que DeepSeek-OCR. Guía: https://quelllm.fr/guide/paddleocr-vl-ocr-local

Docling

PDF nativos, DOCX y presentaciones: documentos que ya contienen texto y de los que sobre todo hay que recuperar la maquetación y las tablas. Docling puede llamar a un motor de OCR para las páginas con imágenes, pero su núcleo es el análisis de estructura. Guía: https://quelllm.fr/guide/docling-conversion-documents-ia

DeepSeek-OCR

Escaneos o fotos de páginas con títulos, listas, tablas o fórmulas, y la necesidad de obtener Markdown listo para indexar en una sola pasada, en una tarjeta gráfica modesta.

Un criterio suele ser decisivo: si un error en una cifra tiene consecuencias, prefiere una herramienta que reconozca sin generar, o duplica la lectura con un segundo motor y compara los resultados. Si la prioridad es hacer legible y consultable un fondo de documentos heterogéneos, el Markdown de DeepSeek-OCR ahorra tiempo en cada etapa posterior.

#Para ir más allá

Ficha del modelo DeepSeek-OCR

Parámetros, VRAM por precisión, licencia y comando de instalación. https://quelllm.fr/modele/deepseek-ocr

Instalar Ollama

La instalación en Windows, macOS y Linux, los comandos básicos y la resolución de problemas. https://quelllm.fr/guide/installer-ollama

RAG local sin programar

Conecte el Markdown obtenido a Open WebUI o AnythingLLM para consultar sus documentos. https://quelllm.fr/guide/rag-local-ollama-sans-coder

Fuentes oficiales

Repositorio de GitHub deepseek-ai/DeepSeek-OCR (código, instrucciones y scripts de vLLM para PDF), página de Hugging Face deepseek-ai/DeepSeek-OCR (pesos y licencia MIT), página Ollama ollama.com/library/deepseek-ocr (etiquetas, tamaño y versión mínima).