How poppanda/llm_pdf_translator works
Project Type and Purpose
• This is a full-stack Python application (“LLM PDF Translator”) that exposes a web GUI and REST API for translating PDF files while preserving layout.
• Key subsystems: PDF ingestion (upload or URL download), layout analysis (UniLM DiT or VGT), OCR (PaddleOCR), LLM translation (OpenAI, Ollama, QWEN, Google), PDF rendering (ReportLab), plus CLI/batch utilities.
File Structure Analysis
• Top-level scripts:
• server.py – launches FastAPI/uvicorn server and defines TranslateApi class
• cli.py / batch.py – command-line and batch translation scripts
• Makefile / Dockerfile – build, model download, docker run targets
• Directories:
• models/ – prebuilt ONNX models for OCR and configuration files for layout models
• modules/ – pluggable engines (layout, ocr, render, translate) implementing common interfaces
• pdf_operation/ – basic PDF utilities (merge, add blank page)
• utils/ – low-level helpers: database logging, Ditod/VGT model loading & training helpers, PaddleOCR ONNX integration, GUI support
• Config and assets:
• config.yaml – runtime settings for translation provider, fonts, threading
• assets/ – screenshots and GUI assets
README Insights
• Single-process separation of OCR/layout and translation to conserve VRAM
• Multi-threaded translation engine for LLM calls
• Supported translation providers: Ollama, OpenAI GPT, QWEN, Google Translate
• Layout engine: UniLM DiT (future VGT support)
• OCR engine: PaddleOCR ONNX
• Renderer: ReportLab
Main Components
a. Client Layer
• Web GUI (browser) – built into server, serves upload/download pages
• CLI/Batch clients – command-line scripts invoking TranslateApi
b. API / Orchestrator
• FastAPI server (server.py) hosting endpoints and orchestrating workflow
• Configuration loader (config.yaml)
c. Worker Processes
• OCR/Layout Worker – standalone process that loads layout and OCR models from models/; invoked by orchestrator; killed before translation to free VRAM
• Translation Engine Pool – multi-threaded clients invoking external APIs or local LLMs (OpenAI, Ollama, QWEN, Google) via modules/translate
d. Core Workflow Modules
• PDF Operation (pdf_operation/) – splitting, merging, page handling
• Layout Detection (modules/layout) – DiT or VGT detector
• OCR (modules/ocr) – PaddleOCR inference via ONNX
• Text Extraction & Post-processing (utils/ocr_model/ppocr_onnx)
• LLM Translation (modules/translate) – abstraction over API clients
• Reference Checking (LLM-based skip logic)
• Rendering (modules/render) – ReportLab-based PDF recreation with translated text, embedded fonts
e. Data Stores & Temp
• Temporary file directory – intermediate page images, JSON layout/OCR outputs
• models/ folder – local ONNX weights and config files
• utils/database – local SQLite (or similar) for request logging, file status
f. External Services
• OpenAI API
• Ollama local LLM
• QWEN API
• Google Translate API
Interactions and Data Flow
1. Client → Server API (upload PDF or URL)
2. Server API → PDF Operation: split source PDF into pages/images
3. Server API spawns OCR/Layout Worker:
• OCR → raw text + positional metadata
4. Worker returns layout+OCR JSON to orchestrator
5. Orchestrator kills OCR/Layout process → frees VRAM
6. Orchestrator → Translation Engine Pool (multi-threaded):
• For each text block, invoke selected translation provider
• Perform LLM-based reference detection and skip logic
7. Translated text + layout metadata → Renderer → output PDF
8. Orchestrator → persists logs to utils/database
9. Server → returns translated PDF (download)
Architectural Patterns and Design Principles
• Modular “strategy” pattern: interchangeable modules under modules/layout, modules/ocr, modules/translate, modules/render
• Process isolation: OCR/Layout decoupled from translation to reduce GPU memory footprint
• Thread pool for I/O-bound translation calls
• Configuration-driven design (config.yaml)
• CLI & GUI share the same TranslateApi core
• Threading boundary around Translation Engine Pool