Una lista curada de problemas comunes de Docling con solución rápida, solución recomendada y fuente oficial. Solo se incluyen problemas reproducibles.
La instalación falla en Windows
Instalación
error: Microsoft Visual C++ 14.0 or greater is required / Failed building wheel for docling-parse
Por qué ocurre: Algunas dependencias opcionales compilan extensiones nativas de C++ o Rust y necesitan un compilador que no está por defecto.
Solución rápida: Instala con Astral uv en lugar de pip para usar ruedas precompiladas: uv add docling.
Solución recomendada: Si necesitas pip, instala las Microsoft Visual C++ Build Tools (14.0+) y un Python de 64 bits y vuelve a intentarlo. En un sistema o Python no compatibles, usa una combinación admitida (Python 3.10-3.12) o un contenedor.
uv add docling
Cuándo no aplica: Si no existe una rueda para tu sistema y Python, puede seguir siendo necesario el compilador.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Microsoft Visual C++ 14.0 is required. Get it with Microsoft C++ Build Tools
Por qué ocurre: pip intenta compilar una extensión nativa desde el código fuente y no encuentra la cadena de herramientas de MSVC.
Solución rápida: Prefiere uv, que resuelve ruedas precompiladas y evita el compilador por completo.
Solución recomendada: Si no, instala las Build Tools con la carga de trabajo Desarrollo de escritorio con C++: winget install Microsoft.VisualStudio.2022.BuildTools.
Failed building wheel for docling-parse / ERROR: Failed to build installable wheels for some pyproject.toml based projects
Por qué ocurre: No hay una rueda precompilada para tu plataforma o Python (por ejemplo macOS anterior a 13, Alpine/Termux, arquitecturas raras o un Python muy nuevo), así que pip intenta compilar desde el código fuente.
Solución rápida: Usa una plataforma y un Python admitidos (3.10-3.12) e instala con uv para obtener ruedas.
Solución recomendada: En macOS usa macOS 13+ (Apple Silicon); en Linux prefiere una distribución x86_64/arm64 común o el contenedor oficial. Fija una versión de docling con ruedas para tu plataforma o compila con una cadena de herramientas C++ completa.
uv venv --python 3.12 && uv add docling
Cuándo no aplica: Las arquitecturas de 32 bits, musl/Alpine sin dependencias de compilación y algunos sistemas ARM no son compatibles oficialmente.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
ImportError: libGL.so.1: cannot open shared object file: No such file or directory / ModuleNotFoundError: No module named 'cv2'
Por qué ocurre: opencv-python (con interfaz OpenGL) está instalado en un entorno sin pantalla como Docker o una máquina remota, o falta OpenCV por completo en un entorno nuevo.
Solución rápida: Fuerza la compilación headless de OpenCV.
Solución recomendada: pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless. Como alternativa, instala la biblioteca del sistema: apt-get install libgl1 (Debian) o dnf install mesa-libGL (RHEL).
version solving failed ... depends on numpy (>=2.0.2,<3.0.0) and docling requires numpy (>=1.26.4,<2.0.0)
Por qué ocurre: En Python 3.13 Docling necesita numpy 2.x, pero pins antiguos de LangChain u otros fuerzan numpy 1.x; el resolutor no puede satisfacer ambos.
Solución rápida: Excluye Python 3.13 del rango de Python de tu proyecto.
Solución recomendada: Define python = ">=3.10,<3.13" en pyproject.toml, o actualiza docling-ibm-models>=2.0.7 y deepsearch-glm>=0.26.2. Para necesidades mixtas, usa marcadores de numpy según la versión de Python.
python = ">=3.10,<3.13"
Cuándo no aplica: Algunos paquetes de terceros aún no tienen ruedas para Python 3.13.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate>
Por qué ocurre: La lista de certificados de confianza del entorno de Python está desactualizada al descargar pesos desde Hugging Face.
Solución rápida: Actualiza certifi.
Solución recomendada: pip install --upgrade certifi. Si persiste, apunta SSL_CERT_FILE y REQUESTS_CA_BUNDLE a `python -m certifi`, o instala pip-system-certs.
pip install --upgrade certifi
Cuándo no aplica: Detrás de un proxy corporativo, configura también HTTPS_PROXY y tu CA raíz interna.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
No se encuentra el comando docling tras actualizar
Instalación
docling: command not found / Docling version: unknown
Por qué ocurre: Actualizar una instalación antigua puede dejar sin registrar el script de consola docling, porque el proyecto se dividió en docling y docling-slim.
Solución rápida: Reinstala el paquete que proporciona el comando.
Solución recomendada: pip install --force-reinstall docling (o pip install -U docling docling-slim), luego docling --version. En un entorno virtual, asegúrate de que bin/Scripts esté en el PATH.
pip install --force-reinstall docling
Cuándo no aplica: uv tool install docling puede fallar por lo mismo; usa docling-slim[standard].
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
OSError / ConnectionError while downloading ds4sd/docling-models / a partial cache blocks later runs
Por qué ocurre: La primera conversión PDF descarga modelos de diseño, tablas y OCR; una descarga fallida o parcial deja una caché rota.
Solución rápida: Vuelve a ejecutar una vez con conexión o descarga los modelos por adelantado.
Solución recomendada: Descarga todos los modelos por adelantado con docling-tools models download --all y apunta DOCLING_CACHE_DIR a una ubicación escribible.
docling-tools models download --all
Cuándo no aplica: Las máquinas aisladas necesitan copiar antes la caché desde un equipo conectado.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Se ignoran los modelos offline (sigue contactando con Hugging Face)
Modelos y caché
Still tries to reach huggingface.co / FileNotFoundError: Missing .../model.safetensors
Por qué ocurre: La ruta de artefactos apunta al directorio equivocado o la estructura de carpetas no coincide con lo que espera Docling.
Solución rápida: Apunta Docling a la carpeta superior que contiene las subcarpetas de modelos.
Solución recomendada: Ejecuta docling-tools models download -o ./models y define artifacts_path="./models" (ruta absoluta en contenedores). La carpeta debe contener subcarpetas como ds4sd--docling-models con model.safetensors, config.json y preprocessor_config.json directamente dentro.
docling-tools models download -o ./models
Cuándo no aplica: Las variables de entorno no bastan para la API de Python; pasa artifacts_path explícitamente.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
403 Client Error / rate limit exceeded / HTTPError while downloading model weights
Por qué ocurre: Repositorios con acceso restringido, límites de tasa o un proxy corporativo bloquean las descargas anónimas de Hugging Face.
Solución rápida: Autentícate con un token de Hugging Face.
Solución recomendada: export HF_TOKEN=your_token (o huggingface-cli login) y sube los tiempos de espera con HF_HUB_ETAG_TIMEOUT y HF_HUB_DOWNLOAD_TIMEOUT. Detrás de un proxy, define HTTPS_PROXY.
export HF_TOKEN=your_token
Cuándo no aplica: Algunos modelos exigen aceptar una licencia en Hugging Face antes de descargar.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Por qué ocurre: Hugging Face intenta crear entradas de caché o symlinks en un montaje de solo lectura al cargar modelos locales.
Solución rápida: Apunta la caché a una ruta escribible.
Solución recomendada: Define HF_HOME y HF_HUB_CACHE en un directorio escribible y HF_HUB_OFFLINE=1 una vez que todos los modelos estén presentes; monta el directorio de modelos como datos, no como caché de Hugging Face.
export HF_HUB_CACHE=/tmp/hf-cache
Cuándo no aplica: HF_HUB_OFFLINE=1 desactiva todo acceso de red; asegúrate de tener todos los modelos antes.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
ModuleNotFoundError: No module named 'tesserocr' / OCR engine import fails
Por qué ocurre: Algunos motores OCR necesitan binarios del sistema (por ejemplo Tesseract) que pip no puede instalar.
Solución rápida: Usa RapidOCR o EasyOCR, que son solo Python y más fáciles de instalar.
Solución recomendada: pip install "docling[rapidocr]" o "docling[easyocr]". Para Tesseract, instala primero el binario del sistema (brew/apt/dnf) y luego el extra.
pip install "docling[rapidocr]"
Cuándo no aplica: Tesseract también necesita datos de idioma; define TESSDATA_PREFIX si faltan idiomas.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Error: Failed loading language 'deu' / TESSDATA_PREFIX is not set
Por qué ocurre: Tesseract necesita los archivos .traineddata y un TESSDATA_PREFIX correcto que apunte a la carpeta tessdata.
Solución rápida: Instala los paquetes de idioma y define TESSDATA_PREFIX (debe terminar en barra).
Solución recomendada: apt-get install tesseract-ocr-eng tesseract-ocr-deu (Debian) y luego export TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata/. Define ocr_options.lang con los idiomas instalados.
Por qué ocurre: Las imágenes de página renderizadas sin metadatos de DPI pueden hacer fallar a Tesseract, sobre todo en contenedores.
Solución rápida: Prueba otro motor OCR o renderiza las páginas a imagen con un DPI explícito.
Solución recomendada: Cambia a RapidOCR o EasyOCR, o pre-renderiza con una densidad fija (ImageMagick: convert -density 216 input.pdf page.png) y haz OCR sobre la imagen.
convert -density 216 input.pdf page.png
Cuándo no aplica: Es una peculiaridad de Tesseract; otros motores no se ven afectados.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Non-English text comes out garbled or empty / wrong characters
Por qué ocurre: El motor OCR usa por defecto un conjunto limitado de idiomas.
Solución rápida: Define los idiomas de OCR en las opciones del pipeline.
Solución recomendada: pipeline_options.ocr_options.lang = ["fr", "de", "en"] — el motor elegido debe admitir esos idiomas y, para Tesseract, los datos deben estar instalados.
torch.cuda.is_available() is False / processing stays on the CPU
Por qué ocurre: PyTorch se instaló sin soporte CUDA, o no hay una GPU y un controlador compatibles.
Solución rápida: Comprueba que torch.cuda.is_available() devuelve True.
Solución recomendada: Desinstala las ruedas de CPU e instala PyTorch con CUDA para tu versión, luego selecciona el dispositivo con --device cuda. Verifica con nvidia-smi.
torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate ...
Por qué ocurre: Los tamaños de lote superan la VRAM disponible, o otro proceso retiene memoria de GPU.
Solución rápida: Reduce los tamaños de lote y vacía la caché.
Solución recomendada: Baja layout_batch_size, ocr_batch_size y table_batch_size, define queue_max_size, llama a torch.cuda.empty_cache() entre documentos y procesa menos archivos en paralelo.
import torch
torch.cuda.empty_cache()
pipeline_options.ocr_batch_size = 2
Cuándo no aplica: Las páginas muy grandes pueden seguir superando la VRAM; usa la CPU para esos archivos.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
CUDA error: no kernel image is available for execution on the device
Por qué ocurre: La compilación CUDA de PyTorch no incluye kernels para la capacidad de cómputo de tu GPU, algo común en GPU muy nuevas o con controladores antiguos.
Solución rápida: Usa una compilación de PyTorch o un contenedor que coincida con tu GPU y controlador.
Solución recomendada: Comprueba la compatibilidad de controlador/CUDA, actualiza el controlador NVIDIA y usa la rueda CUDA adecuada (cu128/cu130) o la imagen CUDA de docling-serve correspondiente. En Docker, expón la GPU con el NVIDIA Container Toolkit.
nvidia-smi
Cuándo no aplica: Las GPU muy nuevas pueden necesitar una compilación CUDA más reciente que la imagen actual.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Por qué ocurre: Los modelos de OCR y enriquecimiento son costosos, sobre todo en CPU.
Solución rápida: Desactiva el OCR en PDF digitales y apaga el enriquecimiento que no necesites.
Solución recomendada: Usa --no-ocr para PDF de texto, --table-mode fast si la precisión lo permite, generate_page_images=False y una GPU cuando sea posible. Ajusta --num-threads a tus núcleos.
docling convert report.pdf --no-ocr --to md
Cuándo no aplica: Los documentos escaneados realmente necesitan OCR y no pueden evitarlo.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Killed / std::bad_alloc / the process is OOM-killed
Por qué ocurre: Los PDF grandes, con muchas imágenes o fórmulas, pueden agotar la RAM, y el backend docling-parse puede acumular memoria entre páginas.
Solución rápida: Procesa el PDF por rangos de páginas o divídelo en archivos más pequeños.
Solución recomendada: converter.convert("large.pdf", page_range=[1, 100]); cambia a los backends PyPdfium para archivos muy grandes; desactiva el enriquecimiento; mantén generate_parsed_pages=False; ejecuta en un subproceso y reinícialo entre archivos.
docling convert large.pdf --page-range 1-100
Cuándo no aplica: Dividir puede romper títulos y tablas de varias páginas que cruzan el límite.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
RAM rises steadily when processing a batch / DoclingLoader leaks memory
Por qué ocurre: El backend de PDF conserva cachés y referencias a documentos tras cada conversión.
Solución rápida: Libera el backend explícitamente después de cada archivo.
Solución recomendada: Llama a result.input._backend.unload() tras la conversión, recrea el DocumentConverter cada pocos archivos o usa un subproceso por archivo. Mantén docling, docling-core y docling-parse actualizados.
result.input._backend.unload()
Cuándo no aplica: El enriquecimiento de fórmulas tiene su propia fuga conocida; aíslalo en un proceso aparte.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
ConversionError: Input document file.pdf is not valid / status FAILURE
Por qué ocurre: El archivo puede estar cifrado, dañado, protegido con contraseña o ser una variante no admitida.
Solución rápida: Prueba con otro archivo de ejemplo para saber si el problema es el documento o la configuración.
Solución recomendada: Quita la protección con contraseña o pasa --pdf-password; repara o reexporta el archivo; consulta la lista de formatos admitidos y abre un issue con un ejemplo.
docling convert report.pdf --to md
Cuándo no aplica: Los PDF cifrados no se descifran en silencio; proporciona una copia sin proteger o la contraseña.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Por qué ocurre: Los PDF con fuentes incrustadas personalizadas sin mapa ToUnicode no pueden traducirse a caracteres reales.
Solución rápida: Fuerza OCR de página completa.
Solución recomendada: Define pipeline_options.ocr_options.force_full_page_ocr = True (o --ocr-mode full_page). Como alternativa, cambia al backend PyPdfium2, que a veces decodifica mejor estas fuentes.
docling convert broken.pdf --ocr-mode full_page
Cuándo no aplica: El OCR aún puede dejar GLYPH en tablas en algunas versiones; actualiza Docling.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
"fi" / "fl" / "ffi" appear with spaces, e.g. "e ffi cient"
Por qué ocurre: Algunas fuentes PDF asignan los glifos de ligadura a caracteres separados con espacios espurios.
Solución rápida: Actualiza Docling, que normaliza las ligaduras comunes.
Solución recomendada: El Docling moderno sanea las ligaduras en la etapa de ensamblado de página. Si tu PDF sigue fallando, usa OCR o preprocesa la fuente.
pip install -U docling
Cuándo no aplica: Las ligaduras basadas en nombres de glifo pueden seguir pasando si el backend no las decodifica.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Images are missing from DOCX or PPTX output on macOS or Linux
Por qué ocurre: El manejo de imágenes WMF/EMF solo funciona en Windows con la biblioteca de imágenes predeterminada.
Solución rápida: Convierte las imágenes o ejecuta la conversión en Windows.
Solución recomendada: Convierte los recursos WMF/EMF a PNG/SVG antes de la conversión (por ejemplo con LibreOffice headless) o ejecuta ese paso en Windows.
HTTPError 403/404 or a timeout when converting an URL
Por qué ocurre: El servidor bloquea solicitudes anónimas, la URL es una página de aterrizaje o la conexión agota el tiempo.
Solución rápida: Descarga el archivo primero y pasa la ruta local.
Solución recomendada: En Python pasa cabeceras propias: converter.convert(url, headers={"User-Agent": "..."}). Comprueba que la URL apunte a un PDF/DOCX y no a una página HTML.
docling convert ./downloaded.pdf --to md
Cuándo no aplica: Algunos sitios requieren cookies o autenticación que Docling no gestiona.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Wrong table structure / cells merged or columns shifted
Por qué ocurre: Las celdas combinadas complejas y las tablas sin bordes son difíciles, y el modo rápido cambia precisión por velocidad.
Solución rápida: Usa el modo de tablas preciso.
Solución recomendada: Ejecuta con --table-mode accurate. Para problemas de celdas combinadas en TableFormer V2, prueba do_cell_matching=False o vuelve a V1 y mantén Docling actualizado.
docling convert report.pdf --table-mode accurate
Cuándo no aplica: Ningún analizador es perfecto en todas las tablas; puede hacer falta revisión manual.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Las tablas sin bordes se convierten en texto corrido
Tablas y diseño
A whitespace-aligned table is extracted as prose / the table is missed
Por qué ocurre: El modelo de diseño puede pasar por alto tablas sin bordes visibles, tratando columnas alineadas como texto normal.
Solución rápida: Prueba OCR forzado o un backend distinto.
Solución recomendada: Fuerza OCR, que puede revelar la cuadrícula, cambia al backend PyPdfium2 o aumenta images_scale. Revisa manualmente los documentos críticos.
docling convert report.pdf --ocr-mode full_page
Cuándo no aplica: Si el modelo de diseño nunca marca la región, el código posterior no puede recuperarla.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
Por qué ocurre: El modelo de diseño necesita margen entre la tabla y el límite de página para distinguirlos.
Solución rápida: Añade un pequeño margen blanco alrededor de la página antes de convertir.
Solución recomendada: Añade unos 40pt de padding izquierda/derecha al PDF antes de convertir (por ejemplo con pypdf); se discute una opción nativa page_padding.
python add_padding.py input.pdf
Cuándo no aplica: El padding externo puede alterar el diseño de algunos documentos.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
docling-serve does not start / connection refused on port 5001
Por qué ocurre: Un conflicto de puertos, un extra de UI ausente o un contenedor que necesita otro entrypoint.
Solución rápida: Ejecuta el servidor con el extra de UI y comprueba que el puerto esté libre.
Solución recomendada: pip install "docling-serve[ui]" && docling-serve run --enable-ui, o usa la imagen oficial. Cambia la dirección o el puerto con UVICORN_HOST/UVICORN_PORT.
docling-serve run --enable-ui
Cuándo no aplica: El despliegue avanzado (escalado, auth) queda fuera de alcance; consulta los docs oficiales.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
docling-serve devuelve 503 o agota el tiempo al arrancar
Servidor, API y MCP
GET /ready returns 503 / requests time out while models load
Por qué ocurre: El endpoint /ready sigue en 503 hasta que los modelos se cargan, y con el motor RQ hasta que Redis es accesible.
Solución rápida: Espera a la preparación antes de enviar tráfico.
Solución recomendada: Configura startupProbe y readinessProbe en /ready y una livenessProbe en /health, y precarga modelos con DOCLING_SERVE_ARTIFACTS_PATH para acortar el arranque.
curl -i http://localhost:5001/ready
Cuándo no aplica: Con el motor RQ, /ready también requiere conectividad con Redis.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
CUDA error: no kernel image is available / the container runs on CPU despite --gpus
Por qué ocurre: El contenedor no tiene acceso a la GPU, o la etiqueta de imagen CUDA y el controlador del host no coinciden.
Solución rápida: Expón la GPU con el NVIDIA Container Toolkit.
Solución recomendada: Instala y actualiza nvidia-container-toolkit, configura el runtime nvidia y solicita la GPU (docker run --gpus all, o devices count: all en Compose). Usa la etiqueta CUDA que coincida con tu controlador.
docker run --gpus all -p 5001:5001 quay.io/docling-project/docling-serve-cu128
Cuándo no aplica: Algunas GPU muy nuevas requieren una imagen CUDA más reciente que la publicada.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
The MCP server is not listed in the client / no tools appear / the server exits immediately
Por qué ocurre: La configuración del cliente apunta al comando equivocado, el paquete no está disponible o el transporte es incorrecto.
Solución rápida: Lanza el servidor una vez a mano para confirmar que funciona.
Solución recomendada: uvx --from=docling-mcp docling-mcp-server y añade el JSON correspondiente a claude_desktop_config.json (o mcp.json). Reinicia el cliente y añade --transport stdio si hace falta.
uvx --from=docling-mcp docling-mcp-server
Cuándo no aplica: La ubicación de los archivos de configuración varía según el cliente; consulta su documentación.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
MCP no puede acceder a los archivos o agota el tiempo
Servidor, API y MCP
[Errno 2] No such file or directory / the MCP client times out on a cold start
Por qué ocurre: El servidor MCP no ve el sistema de archivos del cliente, o la primera conversión es lenta mientras cargan los modelos.
Solución rápida: Usa un directorio compartido o cambia al modo remoto mediante docling-serve.
Solución recomendada: Define DOCLING_MCP_CONVERSION_MODE=remote con DOCLING_MCP_SERVICE_URL, o monta una carpeta compartida que ambos procesos puedan leer. Precalienta la caché de modelos para evitar tiempos de espera en arranque en frío.
export DOCLING_MCP_CONVERSION_MODE=remote
Cuándo no aplica: Los clientes web no comparten sistema de archivos con un servidor MCP local.
Verificado con Docling v2.129.0 · Última comprobación 2026-09-22
La mayoría de los problemas de Docling se deben a una versión desactualizada, un extra opcional ausente o un único documento difícil. Repasa estos pasos antes que nada.
Busca el texto del error. Usa la búsqueda de las tarjetas de arriba; el mensaje exacto suele aparecer como síntoma.
Actualiza primero. Muchos problemas ya están corregidos: pip install -U docling docling-core docling-parse.
Reproduce con un archivo simple. Si un PDF o DOCX pequeño y sencillo funciona, el problema suele estar en el documento, no en la instalación.
Cambia una sola cosa. Prueba --pdf-backend pypdfium2, --ocr-mode full_page o --table-mode fast.
Reduce el alcance. Usa --page-range, desactiva el enriquecimiento y convierte un solo archivo.
Reúne los detalles antes de reportarlo (siguiente tarjeta).
2
Paso 2
Reúne tu entorno
Copia estos comandos para tener a mano las versiones y la información del dispositivo cuando algo falle.
Incluye el comando exacto y el traceback completo.
Adjunta o describe un documento de ejemplo mínimo cuando puedas.
Indica tu sistema operativo, versión de Python y si usas Docker.
Las conversiones lentas o interrumpidas suelen ser presión de memoria o ejecución solo en CPU.
Verifica CUDA/MPS, reduce los lotes y llama a torch.cuda.empty_cache().
Procesa PDF enormes con --page-range o cambia al backend PyPdfium.
Libera memoria con result.input._backend.unload() entre archivos.
Desactiva el OCR y el enriquecimiento que no necesites; ajusta --num-threads.
7
Paso 7
Conversión, tablas y formatos
Los problemas de salida suelen remontarse al documento, al backend o al modo de tablas.
PDF con contraseña: pasa --pdf-password.
GLYPH o texto ilegible: fuerza OCR de página completa o cambia de backend.
Tablas: usa --table-mode accurate; para celdas combinadas de V2 prueba do_cell_matching=False o V1.
Lotes: define raises_on_error=False y revisa cada resultado.
8
Paso 8
Servidor, API y MCP
El servicio y las integraciones de agentes fallan por tres motivos: puertos, preparación o acceso a la GPU.
Arranca la API con docling-serve run --enable-ui (o la imagen del contenedor).
/ready sigue en 503 hasta que cargan los modelos; úsalo para startup/readiness.
En Docker, expón la GPU (--gpus all) e instala el NVIDIA Container Toolkit.
Para MCP, ejecuta uvx --from=docling-mcp docling-mcp-server; usa el modo remoto para clientes web.
9
Paso 9
RAG, audio y vídeo
Los avisos de fragmentación suelen ser inofensivos; audio y vídeo necesitan dependencias extra.
El aviso de longitud de tokens de HybridChunker es una falsa alarma; verifica los tamaños reales.
Instala docling-core[chunking] para el chunker consciente de tokens.
Audio y vídeo necesitan pip install "docling[asr]" y ffmpeg en el PATH.
Consulta la guía de RAG para el pipeline completo.
10
Paso 10
Reportar un error
Un buen informe consigue una corrección rápida. Incluye todo lo necesario para reproducirlo.
Busca primero en los issues existentes para evitar duplicados.
Indica las versiones de Docling, docling-core y Python.
Pega el comando exacto y el traceback completo.
Adjunta un documento de ejemplo mínimo si no es confidencial.
Haz las preguntas de uso en las discussions, no en el tracker.
11
Paso 11
Preguntas frecuentes
¿Qué error debería corregir primero?
Empieza por los errores de instalación y de modelos. Nada más funciona hasta que Docling está instalado y puede cargar sus modelos.
Actualicé y algo se rompió. ¿Qué hago?
Fija la versión anterior con pip install docling==<version> para desbloquearte y reporta la regresión con un ejemplo.
¿Se envía mi documento a algún sitio?
No. Docling se ejecuta en local y no envía datos de documentos. El único acceso de red es la descarga de pesos de modelos.
¿Debo dividir los PDF grandes?
Solo si alcanzas límites de memoria. Prueba primero --page-range, luego dividir, y asume cierta pérdida de estructura entre páginas.
¿Por qué mis tablas se extraen mal?
Las celdas combinadas complejas y las tablas sin bordes son difíciles. Usa el modo preciso, prueba do_cell_matching=False o TableFormer V1 y revisa las tablas críticas.
La CLI funciona pero Python no. ¿Por qué?
Usa el mismo entorno virtual para ambos y pasa las opciones por PdfFormatOption para que lleguen al pipeline.
¿Dónde puedo obtener más ayuda?
Busca en los issues y discussions oficiales de GitHub e incluye tus versiones, el comando y el traceback.