How zai-org/glm-ocr works
Project Type and Purpose
• This is primarily an open-source OCR SDK and CLI tool (“glmocr” Python package) that also includes a full-stack demo application (a React frontend + Python backend).
• The SDK provides a modular OCR pipeline (dataloader, layout detection, OCR client, post-processing, result formatting), a CLI (glmocr), and a server mode (python -m glmocr.server).
• The “apps” folder contains a standalone backend REST API (FastAPI‐style) and a React/Vite frontend for file upload and OCR result display.
File-Structure Analysis
• Top level:
• glmocr/ – core SDK modules (dataloader, pipeline, clients, server, utils, tests).
• apps/backend/ – Python web app: REST endpoints under app/api/, core business logic under app/core/, DB layer (app/db/, app/models/, app/repository/), Pydantic schemas (app/schemas/), config/logging, Dockerfile.
• apps/frontend/ – React/Vite web client: components (OCR UI, markdown preview), hooks, API client, routes, state store, Dockerfile, nginx config.
• examples/ – CLI and SDK usage samples.
• CI/CD config (.github/workflows), Docker startup scripts (start-docker.sh, start-local.sh).
Key README Insights
• Modular pipeline: PageLoader → OCRClient → PP-DocLayout detector → parallel OCR → ResultFormatter.
• Two deployment modes: MaaS cloud API or self-hosted model server (vLLM/SGLang).
• CLI usage and Python API usage.
• Flask service example (glmocr.server).
Main Components
a. Clients
• CLI / Python SDK (CLI tool, script calls into glmocr library)
• React Web App (in apps/frontend)
b. Web Backend (apps/backend)
• API layer (app/api/): HTTP endpoints for task submission, system health
• Core pipeline orchestrator (app/core/): flows, steps, task manager, worker, retry/recovery, lock manager
• DB layer (app/db/, app/models/, app/repository/): persistence of tasks and results
c. OCR Pipeline (inside SDK or backend)
• PageLoader (from glmocr/dataloader)
• Layout Detector (PP-DocLayout via OCRClient)
• OCRClient (MaaS or self-hosted vLLM/SGLang)
• ResultFormatter (JSON/Markdown)
d. External Services
• Zhipu MaaS API (cloud) or vLLM / SGLang model server
• (Optionally) Docker / Nginx reverse proxy
Relationships and Data Flows
• User (CLI or browser) → HTTP/gRPC → Backend API → enqueues Task → Core pipeline orchestrator → PageLoader → Layout detection → Parallel OCR calls to external service → Postprocess & format → persist in DB → API returns JSON/Markdown → Client/Frontend renders result.
• In self-hosted mode, backend also contacts local vLLM/SGLang container.
Architectural Patterns & Principles
• Modular Pipeline Pattern (each stage is a pluggable step)
• MVC/Hexagonal style in backend (API / core logic / repository)
• Component-based UI (React + Vite)
• Containerized microservices (frontend, backend, model server) orchestrated via Docker scripts
• Configuration via YAML (config.yaml) and environment files
Technologies & Frameworks
• Python 3.12, FastAPI (or Flask), SQLAlchemy/Pydantic, uvicorn
• React, TypeScript, Vite, pnpm, Sonner UI components
• Docker, Nginx
• vLLM / SGLang for model serving
• PP-DocLayout-V3 for layout analysis