diff --git a/CHANGELOG.md b/CHANGELOG.md index f88ae7d8..5b046edb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ ### Documentation +- New "External image fetching" subsection in `docs/configuration/processing.md` documenting `fetch_remote_images`, the SSRF / size / timeout guards inherited from docling, and a per-format table of which conversion options actually apply (PDF, IMAGE, HTML, MD, DOCX/PPTX, others). +- New "HTML Image Fetching" section in `docs/remote-processing.md` calling out that docling-serve cannot fetch external `` URLs and recommending docling-local for HTML ingest when picture bytes matter. - New "S3 / Object Storage Monitoring" section in `docs/server.md` and `docs/configuration/processing.md` covering the `[s3]` extra, polling cadence, ETag semantics, credentials, and CLI usage. - New "Deployment Pattern: One Writer, Many Readers" subsection in `docs/configuration/storage.md` documenting the recommended IAM split (one ingestion process + N read-only consumers). diff --git a/docs/configuration/processing.md b/docs/configuration/processing.md index e48279c5..53c09a15 100644 --- a/docs/configuration/processing.md +++ b/docs/configuration/processing.md @@ -99,10 +99,36 @@ conversion_options: conversion_options: images_scale: 2.0 # Image resolution scale factor generate_page_images: true # Include rendered page images + fetch_remote_images: true # Fetch external URLs in HTML/MD ``` - **images_scale**: Scale factor for extracted images. Higher values = better quality but larger size. Typical range: 1.0-3.0. - **generate_page_images**: When `true` (default), rendered images of each PDF page are included in the document. Required for `visualize_chunk()` to show visual grounding. When `false`, page images are excluded to reduce document size. +- **fetch_remote_images**: When `true` (default), HTML and Markdown inputs have their external `` URLs fetched and stored as picture bytes. Set `false` for air-gapped ingest. Applies only to docling-local; see [Remote processing](../remote-processing.md#html-image-fetching) for the docling-serve limitation. + +#### External image fetching + +For HTML and Markdown inputs, docling fetches images referenced by URL when `fetch_remote_images: true`. Pictures end up in `document_items.picture_data` alongside the ones extracted from PDF/DOCX/PPTX. Inherited from docling: + +- **SSRF guard**: hostnames must resolve to a global IP. Loopback, private (RFC1918), link-local, reserved, multicast, and unspecified addresses are rejected. +- **Size cap**: 20 MB per image (sent as a `Range` header), enforced again when streaming the response body. +- **Timeouts**: 5 s connect, 30 s read. +- **SVGs are skipped** (PIL cannot rasterize them). +- **`data:` URIs** are decoded inline (no network). +- **`file://` URIs** are *not* fetched — `enable_local_fetch` stays off to keep the SSRF surface narrow for arbitrary HTML/MD content. + +Per-image failures (404, timeout, oversized, unreadable) leave that picture as a placeholder with `picture_data=NULL` — the rest of the document still ingests. + +**Scope of conversion options across formats:** + +| Input | OCR / table options | `images_scale` / `generate_page_images` | `picture_description` | `fetch_remote_images` | +|---|---|---|---|---| +| `.pdf` | ✅ | ✅ | ✅ | n/a | +| `.png` / `.jpg` / `.jpeg` / `.bmp` / `.tiff` / `.webp` | ✅ | ✅ | ✅ | n/a | +| `.html` / `.xhtml` | n/a (markup-based) | n/a | ✅ on embedded pictures | ✅ | +| `.md` / `.qmd` / `.rmd` | n/a | n/a | ✅ on embedded pictures | ✅ (only `` HTML blocks; native `![alt](url)` syntax is not fetched by docling) | +| `.docx` / `.pptx` | n/a | n/a | ✅ on embedded pictures | n/a | +| Other (`.csv`, `.xlsx`, `.adoc`, `.tex`, `.xml`) | n/a | n/a | n/a | n/a | #### Picture Handling diff --git a/docs/remote-processing.md b/docs/remote-processing.md index 9b180209..07b78f3b 100644 --- a/docs/remote-processing.md +++ b/docs/remote-processing.md @@ -134,6 +134,14 @@ processing: - `false` (default): Tables as narrative text - `true`: Tables as markdown format +## HTML Image Fetching + +docling-serve does **not** fetch external `` URLs in HTML inputs. The `ConvertDocumentsOptions` API exposes no equivalent of docling-local's `HTMLBackendOptions.fetch_images` / `enable_remote_fetch`, and the server-side `DoclingConverterManager` registers `format_options` only for PDF and IMAGE — HTML falls through to docling's defaults (`fetch_images=False`). + +Consequence: ingesting HTML with external image references through docling-serve produces picture items with `picture_data=NULL`. The same input through docling-local fetches the bytes (subject to the SSRF / size / timeout guards documented in [Configuration → External image fetching](configuration/processing.md#external-image-fetching)). + +To preserve image bytes when ingesting HTML or Markdown that references remote images, use `converter: docling-local`. The `processing.conversion_options.fetch_remote_images` flag has no effect on docling-serve and the `source_uri` kwarg on `HaikuRAG.convert()` is accepted but ignored on this path. + ## VLM Picture Description with docling-serve When using VLM picture description with docling-serve, the VLM API calls are made by the docling-serve container, not by haiku.rag. This requires additional configuration.