Tareas comunes de Docling y el comando exacto. Busca, filtra por categoría y copia. Los comandos usan la sintaxis actual docling convert; verifícalos en la documentación oficial.
Convertir PDF a Markdown
BasicStarter
Convierte un PDF local en Markdown estructurado.
docling convert report.pdf --to md
Opciones, salida y consejos
Opciones usadas
--to md Formato de salida. Repita la opción para exportar varios formatos a la vez.
En Docling v2 la conversión vive en el subcomando explícito convert. Todos los comandos tienen la misma forma:
source puede ser un archivo local, un directorio o una URL HTTP(S).
Las salidas se escriben al lado de forma predeterminada: elija una carpeta con --output y un formato con --to.
La ayuda es la fuente autorizada.docling convert --help siempre lista exactamente lo que admite su versión instalada.
docling convert <source> [options]
docling convert report.pdf --to md --output ./out
!La mayoría de los tutoriales antiguos escriben docling report.pdf: eso es sintaxis v1 y no funcionará hoy. Vea Migrar desde v1.
iComandos complementarios: docling-tools models predescarga modelos, docling convert-remote habla con un servicio en ejecución y docling-serve expone una API HTTP.
2
Pipeline
Elegir un pipeline
El pipeline es la mayor decisión estructural: determina qué modelos se ejecutan sobre su PDF o imagen.
Predeterminado para PDF e imágenes: diseño, OCR, tablas.
Equilibrado y bien conocido.
native
Quiere el analizador nativo con hilos para PDF grandes.
Análisis rápido; ajuste con --parser-threads.
vlm
Diseños complejos y visualmente ricos que un solo modelo maneja mejor.
Carga un modelo de visión; más lento y pesado.
asr
Archivos de audio y vídeo (familia Whisper).
Solo voz; las opciones de OCR/tablas no aplican.
legacy
Reproducir el comportamiento anterior.
No recomendado para trabajos nuevos.
iPara PDF digitales normales el pipeline standard es más rápido y barato que un VLM: empiece por ahí.
3
Formatos
Entradas y salidas
Docling lee PDF, la familia Office, HTML, EPUB, CSV, imágenes, audio/vídeo y más. Consulte la referencia de formatos compatibles para la lista completa y notas por formato.
La opción --to es repetible, así que una ejecución puede emitir varios formatos. Salidas comunes:
!¿Salida vacía de un PDF escaneado? Fuerce --ocr-mode full_page. El OCR no se ejecutará sobre texto programático aunque la fuente esté dañada.
Elija un motor con --ocr-engine y dele un idioma con --ocr-lang. Compare motores en la referencia de OCR.
5
Rendimiento
Velocidad y hardware
El coste de la conversión está dominado por qué modelos se ejecutan y dónde se ejecutan.
docling convert report.pdf --device cuda --num-threads 8 --to md
Palanca
Efecto
--no-ocr
La mayor ganancia en PDF digitales.
--no-tables, omitir el enriquecimiento
Evita pasadas neuronales que no necesita.
--device cuda|mps|xpu
Traslada la inferencia a una GPU (CUDA, Apple Silicon, Intel).
--num-threads
Paralelismo de CPU para la inferencia (predeterminado 4).
--page-batch-size
Más páginas por lote: aumente hasta que la memoria se ajuste.
--profiling
Muestra el tiempo por etapa para que optimice el cuello de botella real.
iProteja los lotes largos con --document-timeout 120. Para aceleradores air-gapped vea --artifacts-path.
6
Automatización
Lotes y automatización
Pase un directorio y Docling lo recorre por usted, o use un bucle en su shell para control total sobre nombres, paralelismo y ejecuciones incrementales.
Conversión de carpeta integrada
Docling recorre un directorio por usted: la ruta por lotes más sencilla.
docling convert ./inbox --output ./out
Bucle de carpeta en PowerShell
Control total sobre qué archivos se recogen en Windows.
!Las ejecuciones paralelas comparten una pipeline de modelo por proceso: vigile la CPU y la RAM, y baje -P o --page-batch-size si la máquina hace swap.
7
RAG
Chunks para RAG
Docling divide el árbol del documento, no una cadena plana, así que los encabezados y las tablas sobreviven en los chunks.
--chunks-type hybrid (predeterminado) o hierarchical.
--chunks-max-tokens coincide con el límite de su modelo de embeddings.
--chunks-tokenizer elige el tokenizer de HuggingFace usado para contar tokens.
iconvert-remote omite intencionadamente opciones solo locales como --device: el servidor controla la ejecución. Para clientes de IA, vea la guía del servidor MCP.
10
Depuración
Depurar una conversión
Cuando la salida parece incorrecta, aumente primero el registro y luego visualice lo que detectó cada etapa.
-v registro de información, -vv registro de depuración completo, -q silencioso para scripts.
--debug-visualize-layout, --debug-visualize-tables, --debug-visualize-ocr muestran lo que encontró cada etapa.
--show-layout superpone cuadros delimitadores en las imágenes de página exportadas.
--pdf-backend pypdfium2 ayuda con PDF que usan codificaciones de fuente dañadas.
docling convert report.pdf -vv --to md
11
Migración
Migrar desde la sintaxis v1
Docling v2 reorganizó la superficie de comandos. Si un tutorial, script o trabajo de CI usa la forma antigua, mapéelo con esta tabla.
Sintaxis antigua
Sintaxis actual
Por qué
docling report.pdf
docling convert report.pdf --to md
v1 convertía directamente; v2 movió la conversión bajo el subcomando convert.
docling report.pdf --format json
docling convert report.pdf --to json
--format pasó a ser --to.
docling report.pdf -o out.md
docling convert report.pdf --to md --output ./out
-o/--output ahora es un directorio, no un archivo de destino.
--force-ocr
--ocr-mode full_page
--force-ocr está obsoleto; use el modo OCR explícito.
--ocr-engine tesseract_cli
--ocr-engine tesseract
Los valores de motor se renombraron; tesserocr sigue siendo válido para el motor de enlace C.
--table-mode fast (no engine choice)
--table-mode fast --table-structure-engine docling_tableformer_v2
Ahora puede elegir el modo de velocidad/precisión y el motor de tablas subyacente por separado.
Genera descripciones de imágenes con un modelo de visión.
--enrich-chart-extraction
flag
false
Extrae datos de gráficos de barras, circulares y de líneas.
--chunks-type
hybrid, hierarchical
hybrid
Tipo de chunker usado con --to chunks.
--chunks-max-tokens
integer
tokenizer limit
Máximo de tokens por chunk.
--chunks-tokenizer
HuggingFace model id
sentence-transformers/all-MiniLM-L6-v2
Tokenizer usado para el chunking híbrido.
--device
auto, cpu, cuda, mps, xpu
auto
Acelerador de hardware para la inferencia del modelo.
--num-threads
integer
4
Hilos usados para la inferencia del modelo.
--page-batch-size
integer
4
Páginas procesadas en un lote.
--document-timeout
float (seconds)
none
Tiempo de espera para procesar cada documento.
--abort-on-error
flag
false
Detiene toda la ejecución cuando falla el primer archivo.
--profiling
flag
false
Resume el tiempo dedicado a cada etapa de conversión.
--artifacts-path
path
HF cache
Ubicación de los artefactos de modelo predescargados.
--enable-remote-services
flag
false
Requerido cuando un modelo se conecta a un servicio remoto.
--allow-external-plugins
flag
false
Activa la carga de motores de plugin de terceros.
-v / --verbose
repeatable
0
-v para registros de información, -vv para registros de depuración.
-q / --quiet
flag
false
Suprime los registros de progreso por archivo.
--show-layout
flag
false
Superpone los cuadros delimitadores de los elementos en las imágenes de página.
--debug-visualize-layout
flag
false
Visualiza los clústeres de diseño.
--debug-visualize-tables
flag
false
Visualiza las celdas de tabla.
--debug-visualize-ocr
flag
false
Visualiza las celdas OCR.
--version
flag
-
Muestra la versión instalada de Docling.
14
Paso 14
Preguntas sobre la CLI de Docling
¿Cuál es la diferencia entre `docling` y `docling convert`?
En Docling v1 podía ejecutar `docling file.pdf` directamente. En v2 la conversión vive en el subcomando explícito `docling convert`. Los tutoriales antiguos que omiten `convert` están escritos para v1 y no funcionarán en las versiones actuales: use `docling convert file.pdf --to md`.
¿Por qué mi PDF escaneado se convierte en una salida vacía?
Un PDF escaneado no tiene capa de texto, por lo que debe forzarse el OCR. Ejecute `docling convert scan.pdf --ocr-mode full_page`. Si las páginas son imágenes dentro de un PDF mayor, asegúrese también de que el OCR esté activado (lo está por defecto) y de que haya un motor OCR instalado.
¿Cómo hago la conversión más rápida?
Para PDF digitales añada `--no-ocr` (a menudo varias veces más rápido) y omita las funciones que no necesite, por ejemplo `--no-tables`. Use `--device cuda` o `--device mps` si tiene GPU, y ajuste `--num-threads` y `--page-batch-size`. Use `--profiling` para ver a dónde va realmente el tiempo.
¿Qué motor OCR debería elegir?
Empiece con `auto`. RapidOCR es un buen valor predeterminado multiplataforma y eficiente en CPU. Use `tesseract`/`tesserocr` para muchos idiomas, `ocrmac` en macOS y `nemotron-ocr` solo en un entorno CUDA. Compárelos con sus propios documentos en la guía de OCR.
¿Necesito una GPU?
No. Docling funciona en CPU. Una GPU acelera principalmente los modelos de OCR y enriquecimiento en documentos grandes. En Apple Silicon puede usar `--device mps`; en NVIDIA, `--device cuda`.
¿Dónde se escriben los archivos convertidos?
Por defecto en el directorio actual, junto a donde ejecuta el comando. Use `--output ./alguna/carpeta` para elegir un directorio. Tenga en cuenta que `--output` es un directorio, no un nombre de archivo.
¿Cómo convierto muchos archivos o una carpeta entera?
Pase un directorio (`docling convert ./inbox --output ./out`), pase varias rutas a la vez o use un bucle de shell para tener control total. Los comandos básicos y las recetas por lotes de arriba cubren bash, PowerShell y ejecuciones paralelas.
¿Cómo obtengo chunks para un sistema RAG?
Use `docling convert report.pdf --to chunks --chunks-type hybrid`. Los chunks conservan los encabezados y la estructura de tablas. Puede limitar su tamaño con `--chunks-max-tokens` y elegir el tokenizer con `--chunks-tokenizer`.
¿Puedo ejecutar Docling completamente sin conexión?
Sí. Predescargue los modelos con `docling-tools models download --all` en una máquina conectada y, en el host aislado, establezca `DOCLING_ARTIFACTS_PATH` (y `HF_HUB_OFFLINE=1`) y apunte a la caché copiada con `--artifacts-path`.
¿Cuándo debo usar el pipeline VLM en lugar del estándar?
Use `--pipeline vlm` para páginas complejas y visualmente ricas donde el análisis de diseño clásico tiene dificultades, o cuando quiera un único modelo de extremo a extremo. Para PDF digitales normales el pipeline estándar es más rápido y barato, así que empiece por ahí.
¿Docling sube mis documentos?
No. Docling procesa los documentos localmente por defecto y no envía telemetría. Los modelos remotos solo se usan cuando los habilita explícitamente con `--enable-remote-services` o apunta un pipeline a un servicio externo.
¿Sigue siendo compatible `--force-ocr`?
Está obsoleto. Use `--ocr-mode full_page`, que es la forma admitida de aplicar OCR a todas las páginas y reemplazar cualquier texto existente.