Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: change picture description model (#1882)

Lucas Oliveirac79c1cda4931
diff --git a/src/config/settings.py b/src/config/settings.py
index e5cf6df6e..9b0c5c49b 100644
--- a/src/config/settings.py
+++ b/src/config/settings.py
@@ -530,6 +530,7 @@ DOCLING_POLL_MAX_SECONDS = get_env_int("DOCLING_POLL_MAX_SECONDS", 1800)
DOCLING_POLL_MAX_INTERVAL_SECONDS = get_env_float("DOCLING_POLL_MAX_INTERVAL_SECONDS", 30.0)
DOCLING_POLL_BACKOFF_FACTOR = get_env_float("DOCLING_POLL_BACKOFF_FACTOR", 1.5)
DOCLING_POLL_TRANSIENT_RETRIES = get_env_int("DOCLING_POLL_TRANSIENT_RETRIES", 5)
+DOCLING_ERROR_DETAIL_MAX_LENGTH = get_env_int("DOCLING_ERROR_DETAIL_MAX_LENGTH", 500)
def is_no_auth_mode():
diff --git a/src/services/docling_service.py b/src/services/docling_service.py
index b7d569cbf..a641bd793 100644
--- a/src/services/docling_service.py
+++ b/src/services/docling_service.py
@@ -10,6 +10,7 @@ import httpx
from pydantic import BaseModel
from config.settings import (
+ DOCLING_ERROR_DETAIL_MAX_LENGTH,
DOCLING_SERVE_URL,
DOCLING_SERVE_VERIFY_SSL,
IBM_AUTH_ENABLED,
@@ -26,7 +27,6 @@ class DoclingConfig(BaseModel):
do_table_structure: bool
do_picture_classification: bool
do_picture_description: bool
- picture_description_local: dict | None = None
class DoclingServeError(Exception):
@@ -68,15 +68,56 @@ def get_docling_preset_configs(
"do_table_structure": table_structure,
"do_picture_classification": picture_descriptions,
"do_picture_description": picture_descriptions,
- "picture_description_local": {
- "repo_id": "HuggingFaceTB/SmolVLM-256M-Instruct",
- "prompt": "Describe this image in a few sentences.",
- },
}
return config
+def _stringify_docling_error_value(value: Any) -> str | None:
+ if isinstance(value, str):
+ return value
+ if isinstance(value, dict):
+ for key in ("error_message", "message", "detail", "error"):
+ nested = _stringify_docling_error_value(value.get(key))
+ if nested:
+ return nested
+ return json.dumps(value, default=str)
+ if value:
+ return str(value)
+ return None
+
+
+def _format_docling_error(payload: dict[str, Any]) -> str:
+ messages = []
+ errors = payload.get("errors")
+ if isinstance(errors, list):
+ for error in errors:
+ message = _stringify_docling_error_value(error)
+ if message:
+ messages.append(message)
+ else:
+ message = _stringify_docling_error_value(errors)
+ if message:
+ messages.append(message)
+
+ for key in ("error_message", "message", "detail", "error"):
+ message = _stringify_docling_error_value(payload.get(key))
+ if message:
+ messages.append(message)
+
+ if messages:
+ result = "; ".join(dict.fromkeys(messages))
+ else:
+ result = json.dumps(payload, default=str)
+
+ if not result:
+ return "Unknown Docling processing error"
+
+ if len(result) > DOCLING_ERROR_DETAIL_MAX_LENGTH:
+ return f"{result[:DOCLING_ERROR_DETAIL_MAX_LENGTH]}..."
+ return result
+
+
class DoclingService:
_default_client: httpx.AsyncClient | None = None
@@ -268,21 +309,7 @@ class DoclingService:
if status == "success":
return DoclingStatusSnapshot(state=DoclingTaskState.SUCCESS, raw=payload)
if status == "failure" or payload.get("errors") or payload.get("error"):
- errors = payload.get("errors", [])
- err_msg_list = []
- for err in errors:
- if isinstance(err, dict) and "error_message" in err:
- err_msg_list.append(err["error_message"])
- elif isinstance(err, str):
- err_msg_list.append(err)
-
- single_err = payload.get("error")
- if isinstance(single_err, str):
- err_msg_list.append(single_err)
-
- err_details = (
- "; ".join(err_msg_list) if err_msg_list else "Unknown Docling processing error"
- )
+ err_details = _format_docling_error(payload)
return DoclingStatusSnapshot(
state=DoclingTaskState.FAILED,
detail=f"Docling processing failed: {err_details}",
@@ -333,17 +360,7 @@ class DoclingService:
raise DoclingServeError(f"Malformed docling result payload: {str(e)}") from e
if payload.get("status") == "failure" or payload.get("errors"):
- errors = payload.get("errors", [])
- err_msg_list = []
- for err in errors:
- if isinstance(err, dict) and "error_message" in err:
- err_msg_list.append(err["error_message"])
- elif isinstance(err, str):
- err_msg_list.append(err)
- err_details = (
- "; ".join(err_msg_list) if err_msg_list else "Unknown Docling processing error"
- )
- raise DoclingServeError(f"Docling processing failed: {err_details}")
+ raise DoclingServeError(f"Docling processing failed: {_format_docling_error(payload)}")
doc_content = payload.get("document", {}).get("json_content")
if doc_content is None:
@@ -389,17 +406,9 @@ class DoclingService:
return doc_content
elif status == "failure" or status_data.get("errors"):
- errors = status_data.get("errors", [])
- err_msg_list = []
- for err in errors:
- if isinstance(err, dict) and "error_message" in err:
- err_msg_list.append(err["error_message"])
- elif isinstance(err, str):
- err_msg_list.append(err)
- err_details = (
- "; ".join(err_msg_list) if err_msg_list else "Unknown Docling processing error"
+ raise DoclingServeError(
+ f"Docling processing failed: {_format_docling_error(status_data)}"
)
- raise DoclingServeError(f"Docling processing failed: {err_details}")
await asyncio.sleep(poll_interval)
elapsed += poll_interval
diff --git a/tests/unit/test_docling_service.py b/tests/unit/test_docling_service.py
index e23823771..c474aebd0 100644
--- a/tests/unit/test_docling_service.py
+++ b/tests/unit/test_docling_service.py
@@ -3,27 +3,33 @@ Unit tests for services/docling_service.py
Validates async conversion logic, polling behavior, and error handling.
"""
-import pytest
from unittest.mock import AsyncMock, MagicMock, patch
+
import httpx
-from services.docling_service import DoclingService, DoclingServeError
+import pytest
+
+from services.docling_service import DoclingServeError, DoclingService
+
def _make_response(status_code: int, json_data: dict = None) -> MagicMock:
"""Create a mock HTTP response."""
resp = MagicMock(spec=httpx.Response)
resp.status_code = status_code
resp.json.return_value = json_data or {}
-
+
# Mock raise_for_status to raise if status_code >= 400
if status_code >= 400:
+
def raise_status():
raise httpx.HTTPStatusError("Error", request=MagicMock(), response=resp)
+
resp.raise_for_status.side_effect = raise_status
else:
resp.raise_for_status.return_value = None
-
+
return resp
+
@pytest.fixture
def mock_httpx_client():
"""Provide a mocked httpx AsyncClient."""
@@ -32,19 +38,23 @@ def mock_httpx_client():
client.__aenter__.return_value = client
return client
+
@pytest.fixture
def docling_service(mock_httpx_client):
"""Provide a DoclingService instance with a mocked client."""
return DoclingService(docling_url="http://docling:8000", httpx_client=mock_httpx_client)
+
@pytest.fixture(autouse=True)
def no_sleep():
"""Patch asyncio.sleep so tests run instantly."""
with patch("services.docling_service.asyncio.sleep", new_callable=AsyncMock) as mock_sleep:
yield mock_sleep
+
# ── Polling Logic ───────────────────────────────────────────────────
+
@pytest.mark.asyncio
async def test_poll_result_success(docling_service, mock_httpx_client):
"""Returns json_content when Docling returns 'success'."""
@@ -52,9 +62,9 @@ async def test_poll_result_success(docling_service, mock_httpx_client):
# Second call: get result -> document data
mock_httpx_client.get.side_effect = [
_make_response(200, {"task_status": "success"}),
- _make_response(200, {"document": {"json_content": {"key": "value"}}})
+ _make_response(200, {"document": {"json_content": {"key": "value"}}}),
]
-
+
result = await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
assert result == {"key": "value"}
assert mock_httpx_client.get.call_count == 2
@@ -63,6 +73,7 @@ async def test_poll_result_success(docling_service, mock_httpx_client):
assert calls[0].args[0].endswith("/v1/status/poll/task123")
assert calls[1].args[0].endswith("/v1/result/task123")
+
@pytest.mark.asyncio
async def test_poll_result_waits_for_pending(docling_service, mock_httpx_client, no_sleep):
"""Polls multiple times if status is 'pending' before succeeding."""
@@ -70,60 +81,66 @@ async def test_poll_result_waits_for_pending(docling_service, mock_httpx_client,
_make_response(200, {"task_status": "pending"}),
_make_response(200, {"task_status": "pending"}),
_make_response(200, {"task_status": "success"}),
- _make_response(200, {"document": {"json_content": {"key": "value"}}})
+ _make_response(200, {"document": {"json_content": {"key": "value"}}}),
]
-
+
result = await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
assert result == {"key": "value"}
assert mock_httpx_client.get.call_count == 4
assert no_sleep.call_count == 2
+
@pytest.mark.asyncio
async def test_poll_result_failure_status(docling_service, mock_httpx_client):
"""Raises DoclingServeError when status is 'failure'."""
mock_httpx_client.get.return_value = _make_response(200, {"task_status": "failure"})
-
- with pytest.raises(DoclingServeError, match="Docling conversion failed"):
+
+ with pytest.raises(DoclingServeError, match="Docling processing failed"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
+
@pytest.mark.asyncio
async def test_poll_result_timeout(docling_service, mock_httpx_client, no_sleep):
"""Raises TimeoutError when task stays pending beyond timeout."""
mock_httpx_client.get.return_value = _make_response(200, {"task_status": "pending"})
-
+
# timeout=2.0, interval=1.0 -> loop runs at T=0, T=1, exits at T=2
with pytest.raises(TimeoutError, match="did not complete within"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 2.0)
-
+
assert mock_httpx_client.get.call_count == 2
assert no_sleep.call_count == 2
+
@pytest.mark.asyncio
async def test_poll_result_missing_content(docling_service, mock_httpx_client):
"""Raises DoclingServeError if result response is missing json_content."""
mock_httpx_client.get.side_effect = [
_make_response(200, {"task_status": "success"}),
- _make_response(200, {"document": {}}) # No json_content
+ _make_response(200, {"document": {}}), # No json_content
]
-
+
with pytest.raises(DoclingServeError, match="missing document.json_content"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
+
@pytest.mark.asyncio
async def test_poll_result_http_error(docling_service, mock_httpx_client):
"""Propagates HTTP errors during polling as DoclingServeError."""
mock_httpx_client.get.return_value = _make_response(500)
-
+
with pytest.raises(DoclingServeError, match="Error polling docling status"):
await docling_service._poll_result(mock_httpx_client, "task123", 1.0, 10.0)
+
# ── Upload Logic ────────────────────────────────────────────────────
+
@pytest.mark.asyncio
async def test_upload_success(docling_service, mock_httpx_client):
"""Returns task_id on successful upload."""
mock_httpx_client.post.return_value = _make_response(200, {"task_id": "new-task-id"})
-
+
# Mock config to avoid missing attribute errors during _build_docling_options
with patch("services.docling_service.get_openrag_config") as mock_get_config:
mock_config = MagicMock()
@@ -131,59 +148,67 @@ async def test_upload_success(docling_service, mock_httpx_client):
mock_config.knowledge.ocr = False
mock_config.knowledge.picture_descriptions = False
mock_get_config.return_value = mock_config
-
+
task_id = await docling_service.upload_to_docling_direct_async("test.pdf", b"data")
-
+
assert task_id == "new-task-id"
assert mock_httpx_client.post.call_count == 1
-
+
# Verify boolean serialization (bool -> "true"/"false")
_, kwargs = mock_httpx_client.post.call_args
data = kwargs.get("data", {})
assert data["do_ocr"] == "false"
+
@pytest.mark.asyncio
async def test_upload_http_error(docling_service, mock_httpx_client):
"""Raises exception if upload returns non-200."""
mock_httpx_client.post.return_value = _make_response(400)
-
+
with patch("services.docling_service.get_openrag_config"):
with pytest.raises(httpx.HTTPStatusError):
await docling_service.upload_to_docling_direct_async("test.pdf", b"data")
+
# ── Configuration Logic ─────────────────────────────────────────────
+
def test_build_docling_options_toggles(docling_service):
"""Correctly maps OpenRAG config to Docling options."""
mock_config = MagicMock()
mock_config.knowledge.table_structure = True
mock_config.knowledge.ocr = True
mock_config.knowledge.picture_descriptions = False
-
+
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
options = docling_service._build_docling_options()
-
+
assert options["do_table_structure"] is True
assert options["do_ocr"] is True
assert options["do_picture_description"] is False
assert options["to_formats"] == "json"
+
def test_preset_configs_macos():
"""Uses ocrmac engine on macOS."""
from services.docling_service import get_docling_preset_configs
+
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True)
assert preset["ocr_engine"] == "ocrmac"
+
def test_preset_configs_linux():
"""Uses easyocr engine on non-macOS."""
from services.docling_service import get_docling_preset_configs
+
with patch("services.docling_service.platform.system", return_value="Linux"):
preset = get_docling_preset_configs(ocr=True)
assert preset["ocr_engine"] == "easyocr"
+
def test_init_default_url():
- """Uses DOCLING_SERVICE_URL from api.docling if not provided."""
- with patch("api.docling.DOCLING_SERVICE_URL", "http://default:5001"):
+ """Uses DOCLING_SERVE_URL from config.settings if not provided."""
+ with patch("services.docling_service.DOCLING_SERVE_URL", "http://default:5001"):
service = DoclingService()
assert service.docling_url == "http://default:5001"