vlmparse 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

vlmparse/cli.py

@@ -4,13 +4,24 @@ from loguru import logger
 
 
 class DParseCLI:
-    def serve(self, model: str, port: int | None = None, gpus: str | None = None):
+    """Parsing of pdf to text using VLMs: typ in vlmparse to get the command lists, then `vlmparse <command> --help` to get help on a specific command."""
+
+    def serve(
+        self,
+        model: str,
+        port: int | None = None,
+        gpus: str | None = None,
+        vllm_kwargs: dict | None = None,
+        forget_predefined_vllm_kwargs: bool = False,
+    ):
         """Deploy a VLLM server in a Docker container.
 
         Args:
             model: Model name
             port: VLLM server port (default: 8056)
             gpus: Comma-separated GPU device IDs (e.g., "0" or "0,1,2"). If not specified, all GPUs will be used.
+            vllm_kwargs: Additional keyword arguments to pass to the VLLM server.
+            forget_predefined_vllm_kwargs: If True, the predefined VLLM kwargs from the docker config will be replaced by vllm_kwargs otherwise the predefined kwargs will be updated with vllm_kwargs with a risk of collision of argument names.
         """
         if port is None:
             port = 8056
@@ -32,6 +43,10 @@ class DParseCLI:
             docker_config.gpu_device_ids = [g.strip() for g in str(gpus).split(",")]
         server = docker_config.get_server(auto_stop=False)
 
+        if server is None:
+            logger.error(f"Model server not found for model: {model}")
+            return
+
         # Deploy server and leave it running (cleanup=False)
         logger.info(
             f"Deploying VLLM server for {docker_config.model_name} on port {port}..."
@@ -54,6 +69,8 @@ class DParseCLI:
         with_vllm_server: bool = False,
         concurrency: int = 10,
         dpi: int | None = None,
+        vllm_kwargs: dict | None = None,
+        debug: bool = False,
     ):
         """Parse PDF documents and save results.
 
@@ -67,109 +84,22 @@ class DParseCLI:
             mode: Output mode - "document" (save as JSON zip), "md" (save as markdown file), "md_page" (save as folder of markdown pages)
             with_vllm_server: If True, a local VLLM server will be deployed if the model is not found in the registry. Note that if the model is in the registry and the uri is None, the server will be anyway deployed.
             dpi: DPI to use for the conversion. If not specified, the default DPI will be used.
+            vllm_kwargs: Additional keyword arguments to pass to the VLLM server.
+            debug: If True, run in debug mode (single-threaded, no concurrency)
         """
         from vlmparse.converter_with_server import ConverterWithServer
 
-        converter_with_server = ConverterWithServer(
+        with ConverterWithServer(
             model=model,
             uri=uri,
             gpus=gpus,
             with_vllm_server=with_vllm_server,
             concurrency=concurrency,
-        )
-
-        return converter_with_server.parse(
-            inputs=inputs, out_folder=out_folder, mode=mode, dpi=dpi
-        )
-        # from vlmparse.registries import converter_config_registry
-
-        # # Infer model from URI if provided
-        # if uri is not None and model is None:
-        #     import docker
-
-        #     try:
-        #         docker_client = docker.from_env()
-        #         containers = docker_client.containers.list()
-        #         for container in containers:
-        #             # Check both exact match and match with/without trailing slash
-        #             container_uri = container.labels.get("vlmparse_uri", "")
-        #             if container_uri and (
-        #                 container_uri == uri
-        #                 or container_uri.rstrip("/") == uri.rstrip("/")
-        #             ):
-        #                 inferred_model = container.labels.get("vlmparse_model_name")
-        #                 if inferred_model:
-        #                     logger.info(
-        #                         f"Inferred model {inferred_model} from URI {uri}"
-        #                     )
-        #                     model = inferred_model
-        #                     break
-        #     except Exception:
-        #         # If Docker is not available or fails, just proceed with provided arguments
-        #         pass
-
-        # if mode not in ["document", "md", "md_page"]:
-        #     logger.error(f"Invalid mode: {mode}. Must be one of: document, md, md_page")
-        #     return
-
-        # # Expand file paths from glob patterns
-        # file_paths = []
-        # if isinstance(inputs, str):
-        #     inputs = [inputs]
-        # for pattern in inputs:
-        #     if "*" in pattern or "?" in pattern:
-        #         file_paths.extend(glob(pattern, recursive=True))
-        #     elif os.path.isdir(pattern):
-        #         file_paths.extend(glob(os.path.join(pattern, "*.pdf"), recursive=True))
-        #     elif os.path.isfile(pattern):
-        #         file_paths.append(pattern)
-        #     else:
-        #         logger.error(f"Invalid input: {pattern}")
-
-        # # Filter to only existing PDF files
-        # file_paths = [f for f in file_paths if os.path.exists(f) and f.endswith(".pdf")]
-
-        # if not file_paths:
-        #     logger.error("No PDF files found matching the inputs patterns")
-        #     return
-
-        # logger.info(f"Processing {len(file_paths)} files with {model} converter")
-
-        # gpu_device_ids = None
-        # if gpus is not None:
-        #     gpu_device_ids = [g.strip() for g in gpus.split(",")]
-
-        # if uri is None:
-        #     from vlmparse.registries import docker_config_registry
-
-        #     docker_config = docker_config_registry.get(model, default=with_vllm_server)
-
-        #     if docker_config is not None:
-        #         docker_config.gpu_device_ids = gpu_device_ids
-        #         server = docker_config.get_server(auto_stop=True)
-        #         server.start()
-
-        #         client = docker_config.get_client(
-        #             save_folder=out_folder, save_mode=mode
-        #         )
-        #     else:
-        #         client = converter_config_registry.get(model).get_client(
-        #             save_folder=out_folder, save_mode=mode
-        #         )
-
-        # else:
-        #     client_config = converter_config_registry.get(model, uri=uri)
-        #     client = client_config.get_client(save_folder=out_folder, save_mode=mode)
-        # client.num_concurrent_files = concurrency
-        # client.num_concurrent_pages = concurrency
-        # if dpi is not None:
-        #     client.config.dpi = int(dpi)
-        # documents = client.batch(file_paths)
-
-        # if documents is not None:
-        #     logger.info(f"Processed {len(documents)} documents to {out_folder}")
-        # else:
-        #     logger.info(f"Processed {len(file_paths)} documents to {out_folder}")
+            vllm_kwargs=vllm_kwargs,
+        ) as converter_with_server:
+            return converter_with_server.parse(
+                inputs=inputs, out_folder=out_folder, mode=mode, dpi=dpi, debug=debug
+            )
 
     def list(self):
         """List all containers whose name begins with vlmparse."""

vlmparse/clients/chandra.py

@@ -194,7 +194,7 @@ class ChandraConverterConfig(OpenAIConverterConfig):
     model_name: str = "datalab-to/chandra"
     prompt_type: str = "ocr"  # Default prompt type
     bbox_scale: int = 1024
-    max_retries: int = 6
+    max_retries: int = 0
     max_failure_retries: int = None
     completion_kwargs: dict = Field(
         default_factory=lambda: {

vlmparse/clients/deepseekocr.py

@@ -15,6 +15,57 @@ from vlmparse.servers.docker_server import VLLMDockerServerConfig
 from vlmparse.utils import to_base64
 
 
+class DeepSeekOCRDockerServerConfig(VLLMDockerServerConfig):
+    """Configuration for DeepSeekOCR model."""
+
+    model_name: str = "deepseek-ai/DeepSeek-OCR"
+    command_args: list[str] = Field(
+        default_factory=lambda: [
+            "--limit-mm-per-prompt",
+            '{"image": 1}',
+            "--async-scheduling",
+            "--logits_processors",
+            "vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor",
+            "--no-enable-prefix-caching",
+            "--mm-processor-cache-gb",
+            "0",
+        ]
+    )
+    aliases: list[str] = Field(default_factory=lambda: ["deepseekocr"])
+
+    @property
+    def client_config(self):
+        return DeepSeekOCRConverterConfig(llm_params=self.llm_params)
+
+
+class DeepSeekOCRConverterConfig(OpenAIConverterConfig):
+    """DeepSeekOCR converter - backward compatibility alias."""
+
+    model_name: str = "deepseek-ai/DeepSeek-OCR"
+    aliases: list[str] = Field(default_factory=lambda: ["deepseekocr"])
+
+    prompt_mode: Literal["layout", "ocr"] = "ocr"
+    completion_kwargs: dict | None = {
+        "temperature": 0.0,
+        "max_tokens": 8181,
+        "extra_body": {
+            "skip_special_tokens": False,
+            # args used to control custom logits processor
+            "vllm_xargs": {
+                "ngram_size": 30,
+                "window_size": 90,
+                # whitelist: <td>, </td>
+                "whitelist_token_ids": [128821, 128822],
+            },
+        },
+    }
+    dpi: int = 200
+    aliases: list[str] = Field(default_factory=lambda: ["deepseekocr"])
+
+    def get_client(self, **kwargs) -> "DeepSeekOCRConverterClient":
+        return DeepSeekOCRConverterClient(config=self, **kwargs)
+
+
 def re_match(text):
     pattern = r"(<\|ref\|>(.*?)<\|/ref\|><\|det\|>(.*?)<\|/det\|>)"
     matches = re.findall(pattern, text, re.DOTALL)
@@ -150,54 +201,3 @@ class DeepSeekOCRConverterClient(OpenAIConverterClient):
         logger.debug(page.text)
 
         return page
-
-
-class DeepSeekOCRDockerServerConfig(VLLMDockerServerConfig):
-    """Configuration for DeepSeekOCR model."""
-
-    model_name: str = "deepseek-ai/DeepSeek-OCR"
-    command_args: list[str] = Field(
-        default_factory=lambda: [
-            "--limit-mm-per-prompt",
-            '{"image": 1}',
-            "--async-scheduling",
-            "--logits_processors",
-            "vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor",
-            "--no-enable-prefix-caching",
-            "--mm-processor-cache-gb",
-            "0",
-        ]
-    )
-    aliases: list[str] = Field(default_factory=lambda: ["deepseekocr"])
-
-    @property
-    def client_config(self):
-        return DeepSeekOCRConverterConfig(llm_params=self.llm_params)
-
-
-class DeepSeekOCRConverterConfig(OpenAIConverterConfig):
-    """DeepSeekOCR converter - backward compatibility alias."""
-
-    model_name: str = "deepseek-ai/DeepSeek-OCR"
-    aliases: list[str] = Field(default_factory=lambda: ["deepseekocr"])
-
-    prompt_mode: Literal["layout", "ocr"] = "ocr"
-    completion_kwargs: dict | None = {
-        "temperature": 0.0,
-        "max_tokens": 8181,
-        "extra_body": {
-            "skip_special_tokens": False,
-            # args used to control custom logits processor
-            "vllm_xargs": {
-                "ngram_size": 30,
-                "window_size": 90,
-                # whitelist: <td>, </td>
-                "whitelist_token_ids": [128821, 128822],
-            },
-        },
-    }
-    dpi: int = 200
-    aliases: list[str] = Field(default_factory=lambda: ["deepseekocr"])
-
-    def get_client(self, **kwargs) -> "DeepSeekOCRConverterClient":
-        return DeepSeekOCRConverterClient(config=self, **kwargs)

vlmparse/clients/docling.py

@@ -34,7 +34,7 @@ class DoclingDockerServerConfig(DockerServerConfig):
             "LOG_LEVEL": "DEBUG",  # Enable verbose logging
             # Performance Tuning
             # "UVICORN_WORKERS": "4",  # Increase web server workers (Default: 1)
-            # "DOCLING_SERVE_ENG_LOC_NUM_WORKERS": "4",  # Increase processing workers (Default: 2)
+            "DOCLING_SERVE_ENG_LOC_NUM_WORKERS": "16",  # Increase processing workers (Default: 2)
             "DOCLING_NUM_THREADS": "32",  # Increase torch threads (Default: 4)
         }
     )
@@ -62,8 +62,8 @@ class DoclingDockerServerConfig(DockerServerConfig):
 class DoclingConverterConfig(ConverterConfig):
     """Configuration for Docling converter client."""
 
+    base_url: str
     model_name: str = "docling"
-    base_url: str = "http://localhost:5001"
     timeout: int = 300
     api_kwargs: dict = {"output_format": "markdown", "image_export_mode": "referenced"}
 

vlmparse/clients/dotsocr.py

@@ -8,6 +8,7 @@ from PIL import Image
 from pydantic import Field
 
 from vlmparse.clients.openai_converter import (
+    LLMParams,
     OpenAIConverterClient,
     OpenAIConverterConfig,
 )
@@ -28,6 +29,7 @@ class DotsOCRDockerServerConfig(DockerServerConfig):
     dockerfile_dir: str = str(DOCKERFILE_DIR / "dotsocr")
     command_args: list[str] = Field(
         default_factory=lambda: [
+            "/workspace/weights/DotsOCR",
             "--tensor-parallel-size",
             "1",
             "--gpu-memory-utilization",
@@ -44,12 +46,19 @@ class DotsOCRDockerServerConfig(DockerServerConfig):
             # "16384",
         ]
     )
-    add_model_key_to_server: bool = False
+    add_model_key_to_server: bool = True
     aliases: list[str] = Field(default_factory=lambda: ["dotsocr"])
 
     @property
     def client_config(self):
-        return DotsOCRConverterConfig(llm_params=self.llm_params)
+        return DotsOCRConverterConfig(
+            llm_params=LLMParams(
+                base_url=f"http://localhost:{self.docker_port}{self.get_base_url_suffix()}",
+            )
+        )
+
+    def get_base_url_suffix(self) -> str:
+        return "/v1"
 
 
 class DotsOCRConverterConfig(OpenAIConverterConfig):
@@ -228,7 +237,7 @@ class DotsOCRConverter(OpenAIConverterClient):
         )
         prompt = self.PROMPTS[prompt_mode]
 
-        response = await self._async_inference_with_vllm(image, prompt)
+        response, usage = await self._async_inference_with_vllm(image, prompt)
 
         if prompt_mode in ["prompt_layout_all_en"]:
             try:
@@ -239,17 +248,17 @@ class DotsOCRConverter(OpenAIConverterClient):
                     image.width,
                     image.height,
                 )
-                return {}, cells, False
+                return {}, cells, False, usage
             except Exception as e:
                 logger.warning(f"cells post process error: {e}, returning raw response")
-                return {}, response, True
+                return {}, response, True, usage
         else:
-            return {}, response, None
+            return {}, response, None, usage
 
     async def async_call_inside_page(self, page: Page) -> Page:
         image = page.image
 
-        _, response, _ = await self._parse_image_vllm(
+        _, response, _, usage = await self._parse_image_vllm(
             image, prompt_mode=self.config.prompt_mode
         )
         logger.info("Response: " + str(response))
@@ -274,4 +283,8 @@ class DotsOCRConverter(OpenAIConverterClient):
         text = clean_response(response)
         text = html_to_md_keep_tables(text)
         page.text = text
+
+        page.completion_tokens = usage.completion_tokens
+        page.prompt_tokens = usage.prompt_tokens
+        page.reasoning_tokens = usage.reasoning_tokens
         return page

vlmparse/clients/hunyuanocr.py

@@ -39,7 +39,8 @@ class HunyuanOCRConverterConfig(OpenAIConverterConfig):
     completion_kwargs: dict | None = {
         "temperature": 0.0,
         "extra_body": {"top_k": 1, "repetition_penalty": 1.0},
+        "max_completion_tokens": 16384,  # max token len used in training according to the technical report is 32000, but in practice the model breaks earlier
     }
-    max_image_size: int | None = 1540
     dpi: int = 200
     aliases: list[str] = Field(default_factory=lambda: ["hunyuanocr"])
+    stream: bool = True

vlmparse/clients/mineru.py

@@ -1,6 +1,5 @@
 import asyncio
 import io
-import os
 
 import orjson
 from loguru import logger
@@ -20,18 +19,21 @@ class MinerUDockerServerConfig(DockerServerConfig):
     docker_image: str = "pulsia/mineru25apipulsia:latest"
     docker_port: int = 4299
     container_port: int = 8000
+    server_ready_indicators: list[str] = Field(
+        default_factory=lambda: ["Uvicorn running"]
+    )
 
     @property
     def client_config(self):
-        return MinerUConverterConfig(api_url=f"http://localhost:{self.docker_port}")
+        return MinerUConverterConfig(base_url=f"http://localhost:{self.docker_port}")
 
 
 class MinerUConverterConfig(ConverterConfig):
     """Configuration for MinerU API converter."""
 
-    base_url: str = Field(
-        default_factory=lambda: os.getenv("MINERU_API_URL", "http://localhost:4299")
-    )
+    base_url: str
+    model_name: str = "opendatalab/MinerU2.5-2509-1.2B"
+    aliases: list[str] = Field(default_factory=lambda: ["mineru25"])
     timeout: int = 600
 
     def get_client(self, **kwargs) -> "MinerUConverter":
@@ -50,25 +52,22 @@ class MinerUConverter(BaseConverter):
 
     config: MinerUConverterConfig
 
-    def __init__(self, config: MinerUConverterConfig, **kwargs):
-        super().__init__(config=config, **kwargs)
-        from httpx import AsyncClient
-
-        self.client = AsyncClient(base_url=config.api_url, timeout=config.timeout)
-
     async def _async_inference_with_api(self, image) -> list:
         """Run async inference with MinerU API."""
+        from httpx import AsyncClient
 
-        img_byte_arr = await asyncio.to_thread(to_bytes_io, image)
-
-        response = await self.client.post(
-            "process-image",
-            files={"image": ("image.png", img_byte_arr, "image/png")},
-        )
+        async with AsyncClient(
+            base_url=self.config.base_url, timeout=self.config.timeout
+        ) as client:
+            img_byte_arr = await asyncio.to_thread(to_bytes_io, image)
+            response = await client.post(
+                "process-image",
+                files={"image": ("image.png", img_byte_arr, "image/png")},
+            )
 
-        response.raise_for_status()
+            response.raise_for_status()
 
-        res = orjson.loads(response.content)
+            res = orjson.loads(response.content)
 
         return res
 

vlmparse/clients/olmocr.py

@@ -41,6 +41,6 @@ class OlmOCRConverterConfig(OpenAIConverterConfig):
         "temperature": 0.1,
         "max_tokens": 8000,
     }
-    max_image_size: int | None = 1288
+    # max_image_size: int | None = 1288
     dpi: int = 200
     aliases: list[str] = Field(default_factory=lambda: ["olmocr-2-fp8"])

vlmparse/clients/openai_converter.py

@@ -40,6 +40,8 @@ def get_llm_params(model_name: str, uri: str | None = None):
     ]:
         base_url = None
         api_key = os.getenv("OPENAI_API_KEY")
+        if api_key is None:
+            raise ValueError("OPENAI_API_KEY environment variable not set")
     else:
         if model_name in [
             "gemini-2.5-flash-lite",
@@ -48,6 +50,8 @@ def get_llm_params(model_name: str, uri: str | None = None):
         ]:
             base_url = GOOGLE_API_BASE_URL
             api_key = os.getenv("GOOGLE_API_KEY")
+            if api_key is None:
+                raise ValueError("GOOGLE_API_KEY environment variable not set")
         else:
             return None
     return LLMParams(base_url=base_url, model_name=model_name, api_key=api_key)
@@ -92,11 +96,12 @@ class OpenAIConverterClient(BaseConverter):
             base_url=self.config.llm_params.base_url,
             api_key=self.config.llm_params.api_key,
             timeout=self.config.llm_params.timeout,
+            max_retries=self.config.llm_params.max_retries,
         )
 
     async def _get_chat_completion(
         self, messages: list[dict], completion_kwargs: dict | None = None
-    ) -> str:
+    ) -> tuple[str, "CompletionUsage"]:  # noqa: F821
         """Helper to handle chat completion with optional streaming."""
         if completion_kwargs is None:
             completion_kwargs = self.config.completion_kwargs
@@ -125,7 +130,8 @@ class OpenAIConverterClient(BaseConverter):
                     "Response is None, finish reason: "
                     + response_obj.choices[0].finish_reason
                 )
-            return response_obj.choices[0].message.content
+
+            return response_obj.choices[0].message.content, response_obj.usage
 
     async def async_call_inside_page(self, page: Page) -> Page:
         """Process a single page using OpenAI-compatible API."""
@@ -162,12 +168,16 @@ class OpenAIConverterClient(BaseConverter):
             },
         ]
 
-        response = await self._get_chat_completion(messages)
-        logger.info("Response: " + str(response))
+        response, usage = await self._get_chat_completion(messages)
+        logger.debug("Response: " + str(response))
         page.raw_response = response
         text = clean_response(response)
 
         text = html_to_md_keep_tables(text)
         page.text = text
+        page.prompt_tokens = usage.prompt_tokens
+        page.completion_tokens = usage.completion_tokens
+        if hasattr(usage, "reasoning_tokens"):
+            page.reasoning_tokens = usage.reasoning_tokens
 
         return page

vlmparse/clients/paddleocrvl.py

@@ -42,7 +42,8 @@ class PaddleOCRVLConverterConfig(OpenAIConverterConfig):
     postprompt: str | None = TASKS["ocr"]
     completion_kwargs: dict | None = {
         "temperature": 0.0,
+        "max_completion_tokens": 16384,
     }
-    max_image_size: int | None = 1540
     dpi: int = 200
     aliases: list[str] = Field(default_factory=lambda: ["paddleocrvl"])
+    stream: bool = True

vlmparse/converter_with_server.py

@@ -12,28 +12,35 @@ from vlmparse.utils import get_file_paths
 class ConverterWithServer:
     def __init__(
         self,
-        model: str,
+        model: str | None = None,
         uri: str | None = None,
         gpus: str | None = None,
         port: int | None = None,
         with_vllm_server: bool = False,
         concurrency: int = 10,
+        vllm_kwargs: dict | None = None,
+        forget_predefined_vllm_kwargs: bool = False,
     ):
-        from vlmparse.registries import (
-            converter_config_registry,
-            docker_config_registry,
-        )
-
         self.model = model
         self.uri = uri
         self.port = port
         self.gpus = gpus
         self.with_vllm_server = with_vllm_server
         self.concurrency = concurrency
+        self.vllm_kwargs = vllm_kwargs
+        self.forget_predefined_vllm_kwargs = forget_predefined_vllm_kwargs
+        self.server = None
+        self.client = None
 
         if self.uri is not None and self.model is None:
             self.model = get_model_from_uri(self.uri)
 
+    def start_server_and_client(self):
+        from vlmparse.registries import (
+            converter_config_registry,
+            docker_config_registry,
+        )
+
         gpu_device_ids = None
         if self.gpus is not None:
             gpu_device_ids = [g.strip() for g in self.gpus.split(",")]
@@ -42,13 +49,18 @@ class ConverterWithServer:
             docker_config = docker_config_registry.get(
                 self.model, default=self.with_vllm_server
             )
-            if self.port is not None:
-                docker_config.docker_port = self.port
 
             if docker_config is not None:
+                if self.port is not None:
+                    docker_config.docker_port = self.port
                 docker_config.gpu_device_ids = gpu_device_ids
-                server = docker_config.get_server(auto_stop=True)
-                server.start()
+                docker_config.update_command_args(
+                    self.vllm_kwargs,
+                    forget_predefined_vllm_kwargs=self.forget_predefined_vllm_kwargs,
+                )
+                self.server = docker_config.get_server(auto_stop=True)
+
+                self.server.start()
 
                 self.client = docker_config.get_client()
             else:
@@ -56,8 +68,20 @@ class ConverterWithServer:
 
         else:
             client_config = converter_config_registry.get(self.model, uri=self.uri)
+
             self.client = client_config.get_client()
 
+    def stop_server(self):
+        if self.server is not None and self.server.auto_stop:
+            self.server.stop()
+
+    def __enter__(self):
+        self.start_server_and_client()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.stop_server()
+
     def parse(
         self,
         inputs: str | list[str],
@@ -67,6 +91,9 @@ class ConverterWithServer:
         debug: bool = False,
         retrylast: bool = False,
     ):
+        assert (
+            self.client is not None
+        ), "Client not initialized. Call start_server_and_client() first."
         file_paths = get_file_paths(inputs)
         assert (
             out_folder is not None
@@ -118,5 +145,5 @@ class ConverterWithServer:
 
         return documents
 
-    def get_out_folder(self) -> Path:
+    def get_out_folder(self) -> str | None:
         return self.client.save_folder