HunyuanOCR Usage Guide

Introduction

HunyuanOCR stands as a leading end-to-end OCR expert VLM powered by Hunyuan’s native multimodal architecture. In this guide, we demonstrate how to set up HunyuanOCR for online OCR serving with OpenAI compatible API server.

Installing vLLM

  1. uv venv
  2. source .venv/bin/activate
  3. # Until v0.11.3 release, you need to install vLLM from nightly build
  4. uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly

Deploying HunyuanOCR

  1. vllm serve tencent/HunyuanOCR \
  2.     --no-enable-prefix-caching \
  3.     --mm-processor-cache-gb 0

Querying with OpenAI API Client

  1. from openai import OpenAI
  3. client = OpenAI(
  4.     api_key="EMPTY",
  5.     base_url="http://localhost:8000/v1",
  6.     timeout=3600
  7. )
  9. messages = [
  10.     {"role": "system", "content": ""},
  11.     {
  12.         "role": "user",
  13.         "content": [
  14.             {
  15.                 "type": "image_url",
  16.                 "image_url": {
  17.                     "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/chat-ui/tools-dark.png"
  18.                 }
  19.             },
  20.             {
  21.                 "type": "text",
  22.                 "text": (
  23.                     "Extract all information from the main body of the document image "
  24.                     "and represent it in markdown format, ignoring headers and footers."
  25.                     "Tables should be expressed in HTML format, formulas in the document "
  26.                     "should be represented using LaTeX format, and the parsing should be "
  27.                     "organized according to the reading order."
  28.                 )
  29.             }
  30.         ]
  31.     }
  32. ]
  34. response = client.chat.completions.create(
  35.     model="tencent/HunyuanOCR",
  36.     messages=messages,
  37.     temperature=0.0,
  38.     extra_body={
  39.         "top_k": 1,
  40.         "repetition_penalty": 1.0
  41.     },
  42. )
  43. print(f"Generated text: {response.choices[0].message.content}")

Configuration Tips

  • Use greedy sampling (i.e., temperature=0.0) or sampling with low temperature for the optimal OCR performance.
  • Unlike multi-turn chat use cases, we do not expect OCR tasks to benefit significantly from prefix caching or image reuse, therefore it’s recommended to turn off these features to avoid unnecessary hashing and caching.
  • Depending on your hardware capability, adjust max_num_batched_tokens for better throughput performance.
  • Check out the official HunyuanOCR documentation for more application-oriented prompts for various document parsing tasks.