typhoon-ocr2

Read Thai and English documents (PDFs and images) with Typhoon OCR. For every page you get:

• the page as Markdown (tables as HTML, formulas as LaTeX), and
• with Typhoon OCR V2, the layout elements in reading order: each one has a category (title, text, table, …), a bounding box and its text.

Links: Typhoon OCR V2 2B · Typhoon OCR V2 0.8B · Playground · Typhoon API docs

This package continues scb-10x/typhoon-ocr (pip install typhoon-ocr) with the Typhoon team's permission. It has a new name, so code that uses typhoon-ocr keeps working.

Install

pip install typhoon-ocr2

PDF support is included; you do not need to install Poppler.

Quick start: Typhoon API (no GPU needed)

import os
from typhoon_ocr2 import TyphoonOCR

os.environ["TYPHOON_API_KEY"] = "YOUR_KEY"       # your Typhoon API key (or pass api_key="YOUR_KEY" below)

ocr = TyphoonOCR(
    base_url="https://api.opentyphoon.ai/v1",    # the Typhoon API
    version="v2",                                # Typhoon OCR V2 ("v1.5" for Typhoon OCR 1.5)
    upscale=True,                                # enlarge images under 1,600 px (recommended; see Settings)
)

pages = ocr.parse("report.pdf", pages="1-3")     # a PDF or an image; pages: "1-3", 2, [1, 4] or None for all
for page in pages:
    print(f"--- page {page.page}")
    print(page.markdown)

Typhoon OCR V2 or 1.5

Switch with version; the rest of the code stays the same.

ocr_v15 = TyphoonOCR(
    base_url="https://api.opentyphoon.ai/v1",
    version="v1.5",
)
print(ocr_v15.parse("page.jpg")[0].markdown)

version or model? version tells the package which prompt to send and how to read the answer. model is the model's name on the server. On the Typhoon API you only need version: the package picks the matching model for you. You need model when you run the model yourself (next section), because there the name depends on how you started the server.

Run the model yourself

Start a server, then point base_url and model at it:

# vLLM 0.33.0 or newer (GPU)
vllm serve typhoon-ai/typhoon-ocr2-2b --max-model-len 40960 \
  --limit-mm-per-prompt '{"image": 1}' \
  --mm-processor-kwargs '{"min_pixels": 2048, "max_pixels": 16777216}'

# Ollama 0.40.15 or newer
ollama pull SuraponOCR/typhoon-ocr2-2b

# llama.cpp (GGUF)
llama-server -hf typhoon-ai/typhoon-ocr2-2b-GGUF:Q8_0 --jinja --reasoning off -c 40960 --image-max-tokens 16384

ocr = TyphoonOCR(
    base_url="http://localhost:8000/v1",
    model="typhoon-ai/typhoon-ocr2-2b",
    version="v2",
    upscale=True,
)

For the smaller page parser, use typhoon-ai/typhoon-ocr2-0.8b (Ollama: SuraponOCR/typhoon-ocr2-0.8b). On vLLM older than 0.33.0, add --enforce-eager to vllm serve: in the default compiled mode of vLLM 0.27.1, accuracy dropped by about 9 points on MDPBench. Other OpenAI-compatible servers work the same way.

What you get back

ocr.parse() returns one PageResult per page:

Headers, footers and other categories

The model always returns header, footer and page_footnote elements, and they are always in page.elements. Only page.markdown leaves them out by default, because that is how the model was evaluated (and running page numbers and headers usually get in the way of reading). You choose what the Markdown keeps:

pages = ocr.parse("report.pdf")                                   # default: no header, footer, page_footnote
pages = ocr.parse("report.pdf", keep_header_footer=True)          # keep every element
pages = ocr.parse("report.pdf", exclude=["footer"])               # keep headers, drop footers only
pages = ocr.parse("report.pdf", exclude=["header", "footer", "page_footnote", "figure_caption"])  # your own list

footers = [e["text"] for e in pages[0].elements if e["category"] == "footer"]   # the elements themselves

On the command line: --keep-header-footer, or --exclude footer (several names allowed; --exclude with no names keeps everything).

The 13 categories are header, title, text, figure, table, formula, figure_caption, table_caption, formula_caption, figure_footnote, table_footnote, page_footnote and footer. Boxes use a 0–1000 grid relative to the page, so they do not depend on the image size:

from typhoon_ocr2 import draw_layout, load_pages, to_pixels

image = load_pages("report.pdf", pages=[1])[0]
first = pages[0].elements[0]
print(first["category"], to_pixels(first["bbox"], *image.size))   # box in pixels
draw_layout(image, pages[0].elements).save("page1_layout.png")     # boxes numbered in reading order

Questions and key information (Typhoon OCR V2 2B)

answer = ocr.ask("receipt.jpg", "What is the total amount?")      # plain text
fields = ocr.extract("receipt.jpg", ["Date", "Total", "VAT 7%"])   # dict with these keys
everything = ocr.extract("receipt.jpg")                            # every field; the model picks the keys

The 0.8B model is a page parser only; it is much weaker at questions and extraction. Check extracted values before you use them: key-information extraction is the 2B model's weakest task.

Command line

export TYPHOON_API_KEY=YOUR_KEY
API=https://api.opentyphoon.ai/v1

typhoon-ocr2 report.pdf --base-url $API                                  # Markdown of every page (V2)
typhoon-ocr2 report.pdf --base-url $API --pages 2-4 --format json        # layout elements
typhoon-ocr2 receipt.jpg --base-url $API --ask "What is the total amount?"
typhoon-ocr2 receipt.jpg --base-url $API --extract Date Total
typhoon-ocr2 page.jpg --base-url $API --version v1.5                     # Typhoon OCR 1.5
typhoon-ocr2 page.jpg --base-url http://localhost:11434 --model SuraponOCR/typhoon-ocr2-2b   # Ollama

To avoid repeating --base-url, set TYPHOON_OCR_BASE_URL. Add --no-upscale to turn upscaling off.

Settings

All settings of TyphoonOCR(...). The defaults are the settings the models were evaluated with.

The prompts are the ones the models were trained with (typhoon_ocr2.PARSE_PROMPT for V2), and decoding is greedy with thinking turned off.

Coming from typhoon-ocr

Development

pip install -e ".[dev]"
pytest                                                                  # unit tests, no GPU needed
TYPHOON_OCR2_TEST_URL=http://localhost:8000/v1 pytest -m integration    # against a running server

Releasing

1. On pypi.org, add a Trusted Publisher for project typhoon-ocr2: this GitHub repository, workflow publish.yml, environment pypi.
2. Bump __version__ in src/typhoon_ocr2/__init__.py, commit, then tag and push: git tag v0.1.0 && git push origin v0.1.0.

License

Apache-2.0. See LICENSE and NOTICE. Use of the Typhoon models is subject to the OpenTyphoon Terms and Conditions.