GLM-OCR Documentation

Deploy the model locally using SGLang.

Note: You may need to adjust --context-len and --mem-fraction-static based on your hardware to handle large images or PDFs.

To prepare the application for production, use the following commands to build the project and preview the resulting build locally:

1. Build the production version: pnpm build
2. Preview the production build: pnpm preview

To self-host the model using vLLM, ensure you have installed the selfhosted dependencies and a compatible version of vLLM. You can use the --speculative-config flag to enable Multi-Token Prediction (MTP) for better performance.

# Install dependencies
pip install -U "vllm>=0.19.0"
pip install "transformers>=5.3.0"

# Start vLLM service
vllm serve zai-org/GLM-OCR  --port 8080 --speculative-config '{"method": "mtp", "num_speculative_tokens": 3}' --served-model-name glm-ocr

You can deploy the backend using Docker.

1. Build the image

docker build -t glm-ocr:latest .

2. Run the container

docker run -d \
  --name glm-ocr \
  -p 8000:8000 \
  -v $(pwd)/data:/backend/data \
  -e WORKER_COUNT=5 \
  glm-ocr:latest

Deploy the model locally using vLLM for full control over the pipeline (layout detection, OCR, and formatting).

Note: You may need to adjust --max-model-len and --gpu-memory-utilization based on your hardware to handle large images or PDFs.

# Install vLLM
pip install -U "vllm>=0.19.0"

# Launch the service
pip install "transformers>=5.3.0"

vllm serve zai-org/GLM-OCR  --port 8080 --speculative-config '{"method": "mtp", "num_speculative_tokens": 3}' --served-model-name glm-ocr

To use GLM-OCR, you must first obtain a ZHIPU_API_KEY from the Zhipu AI platform. Once obtained, configure the environment using the provided setup script.

python scripts/config_setup.py setup --api-key YOUR_KEY

The easiest way to use GLM-OCR without a GPU is via the Zhipu cloud API. The SDK acts as a thin wrapper that forwards documents to the cloud and returns Markdown and JSON layout details.

1. Obtain an API key from https://open.bigmodel.cn.
2. Configure your config.yaml to enable MaaS mode.

pipeline:
  maas:
    enabled: true # Enable MaaS mode
    api_key: your-api-key # Required

The glmocr-handwriting skill requires a ZHIPU_API_KEY environment variable to access the ZhiPu GLM-OCR layout parsing API. You can configure this in three ways:

1. Global config (Recommended): Set it in openclaw.json under env.vars to share it across all Zhipu skills.
2. Skill-level config: Set it specifically for this skill in openclaw.json under skills.entries.glmocr-handwriting.env.
3. Shell environment variable: Add export ZHIPU_API_KEY="your_key" to your shell profile (e.g., ~/.zshrc).

Obtain your key from the Zhipu Open Platform.

{
  "env": {
    "vars": {
      "ZHIPU_API_KEY": "你的密钥"
    }
  }
}

To add a new processing flow, create a new class in backend/core/flows/ that inherits from TaskProcessingFlow and implement the process() method. Finally, register it with the FlowFactory.

from backend.core.flows.base import TaskProcessingFlow, FlowFactory

class MyCustomFlow(TaskProcessingFlow):
    async def process(self) -> Dict[str, Any]:
        # Implement processing logic
        pass

# Register the flow
FlowFactory.register_flow("custom", MyCustomFlow)

To add new UI components from the Shadcn library to the project, use the pnpm dlx shadcn@latest add command followed by the component name.

pnpm dlx shadcn@latest add [component-name]
# Example:
pnpm dlx shadcn@latest add button

The GLM OCR backend is an asynchronous document processing system built with FastAPI. It requires Python 3.12+ and SQLite (or another supported database).

1. Install uv package manager

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install dependencies

uv sync

3. Configure Environment

Create a .env file to configure the system:

APP_NAME=OCR Task System
DEBUG=False
HOST=0.0.0.0
PORT=8000
DATABASE_URL=sqlite+aiosqlite:///./tasks.db
OUTPUT_DIR=./data
WORKER_COUNT=5
TASK_TIMEOUT=3600

4. Start the service

uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Access the interactive Swagger/OpenAPI documentation at http://localhost:8000/docs.