ComfyUI-UnlimitedOCR

ComfyUI Unlimited OCR

ComfyUI custom node for running baidu/Unlimited-OCR inside the ComfyUI Python process with Hugging Face Transformers.

This node is local and in-process. It does not require a separate vLLM, SGLang, FastAPI, or OpenAI-compatible OCR server.

Features

• Runs Unlimited-OCR from a ComfyUI IMAGE input.
• Returns OCR text as STRING.
• Passes the original input image through as IMAGE.
• Can write the cleaned OCR result as a ComfyUI output .txt file for API/RunPod workflows.
• Supports single-image and multi-image batches.
• Supports local model folders, Hugging Face model IDs, and ComfyUI extra_model_paths.yaml.
• Optional cleanup removes Unlimited-OCR layout tags from the returned text.
• Optional model cache unloading frees VRAM after a run.

Node

Unlimited OCR Image

Outputs:

• text: OCR result as a STRING.
• image: original input image passthrough.

When save_results=True, the node also writes the returned OCR text to:

ComfyUI/output/FireOCR/fire_ocr_<id>.txt

and exposes that file in the ComfyUI API history so remote workers can upload it as a normal result asset.

Installation

Clone this repository into ComfyUI/custom_nodes:

cd ComfyUI/custom_nodes
git clone https://github.com/endman100/ComfyUI-UnlimitedOCR.git

Install the model-side dependencies into the same Python environment that starts ComfyUI:

pip install -r ComfyUI/custom_nodes/ComfyUI-UnlimitedOCR/requirements.txt

Restart ComfyUI after installation.

Model Setup

The recommended local model path is:

ComfyUI/models/Unlimited-OCR/baidu-Unlimited-OCR

If that folder exists, the node uses it as the default model value. Otherwise it checks configured extra model paths, then falls back to the Hugging Face model ID:

baidu/Unlimited-OCR

Download With Hugging Face Hub

From the ComfyUI Python environment:

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="baidu/Unlimited-OCR",
    local_dir="ComfyUI/models/Unlimited-OCR/baidu-Unlimited-OCR",
    allow_patterns=["*.json", "*.py", "*.safetensors", "*.md", "LICENSE"],
)

The model uses custom Transformers code, so loading it requires trust_remote_code=True. This node only loads model code from the model path or model ID selected in the model field.

extra_model_paths.yaml

The node searches these folder keys:

unlimited_ocr
llm
LLM

Example:

my_models:
  base_path: D:/ComfyUIModel
  unlimited_ocr: models/llm/
  llm: models/llm/
  LLM: models/llm/

With that config, place the model at:

D:/ComfyUIModel/models/llm/baidu-Unlimited-OCR

Then the node model field can be either:

baidu-Unlimited-OCR

or the full local path.

Parameters

• model: Hugging Face model ID, full local model path, or model folder name found through ComfyUI model paths.
• prompt: OCR instruction. <image> is added automatically if missing.
• image_mode: gundam or base.
• device: auto, cuda, cuda:0, or cpu.
• dtype: auto, bfloat16, float16, or float32.
• max_tokens: maximum generated OCR tokens.
• ngram_size: no-repeat ngram size passed to model generation.
• ngram_window: no-repeat ngram window. Use a larger value such as 1024 for multi-page workflows.
• clean_markup: removes layout/control tags from the returned text.
• save_results: asks Unlimited-OCR to write debug/layout files and writes the returned OCR text to ComfyUI/output/FireOCR/*.txt for API workers.
• unload_after_run: removes the cached model and clears CUDA cache after the run.

Markup Cleanup

When clean_markup=True, the node cleans these Unlimited-OCR tags:

| Markup | Meaning | Returned text behavior | | --- | --- | --- | | <|det|>...<|/det|> | Detection/layout metadata, often type and box coordinates | Removed | | <|ref|>...<|/ref|> | Text reference wrapper | Wrapper removed, inner text kept | | <|...|> | Other special control tags | Removed |

Set clean_markup=False if downstream nodes need coordinates or raw layout tags.

save_results

save_results does two things:

1. It passes save_results=True to Unlimited-OCR, so the model may write debug/layout files such as:

• result.md
• result_with_boxes.jpg
• result_with_boxes_0.jpg, result_with_boxes_1.jpg, ...
• images/*.jpg
• geo.jpg for geometry outputs when present

2. It writes the final returned OCR text to ComfyUI/output/FireOCR/*.txt and reports that file through the ComfyUI API history. This second file is the stable output intended for RunPod or other API workers.

Dependency Notes

Baidu's published environment notes list Python 3.12.3 + CUDA 12.9 with:

torch==2.10.0
torchvision==0.25.0
transformers==4.57.1
Pillow==12.1.1
matplotlib==3.10.8
einops==0.8.2
addict==2.4.0
easydict==1.13
pymupdf==1.27.2.2
psutil==7.2.2

This repository does not pin torch or torchvision because ComfyUI installations usually manage those packages according to local GPU and CUDA support.

Testing

Offline/unit test:

python -B tests/test_unlimited_ocr_node.py

Real model smoke test:

python -B tests/run_real_ocr_test.py

The real test expects the local model at:

ComfyUI/models/Unlimited-OCR/baidu-Unlimited-OCR

It generates local files under tests/artifacts/. Those artifacts are ignored by git.

Current Scope

This is a functional local ComfyUI node, not a ComfyUI Registry submission yet. Registry publication still needs a Comfy Registry publisher ID and any registry-specific metadata the publisher account requires.

License

MIT. See LICENSE.