HunyuanOCR

环境要求

• Linux 环境 + Python 3.12（README 用 uv venv --python 3.12 创建环境）
• NVIDIA GPU，快速开始为单卡（-tp 1、GPU=0）
• 依赖 vllm>=0.25.1 与 flash-attn==2.8.3（需源码编译安装）
• 需提前准备 HunyuanOCR 模型权重目录（示例 MODEL_PATH=./HunyuanOCR）

安装与启动步骤

1. 1获取代码仓库

   把 HunyuanOCR 仓库克隆到本地并进入目录，后续所有相对路径（如 inference/vLLM）都以仓库根目录为基准。

   git clone https://github.com/Tencent-Hunyuan/HunyuanOCR.git
   cd HunyuanOCR

   复制

2. 2创建 Python 环境

   安装 uv 并用它创建 Python 3.12 虚拟环境，创建后必须激活，后续 uv pip 才会装到该环境。

   pip install uv
   uv venv --python 3.12 && source .venv/bin/activate

   复制

3. 3安装推理依赖

   依次安装 vLLM 与 flash-attn；flash-attn 需关闭构建隔离并从源码编译，安装耗时较长。

   uv pip install "vllm>=0.25.1"
   uv pip install --no-build-isolation --no-cache-dir "flash-attn==2.8.3"

   复制

4. 4启动 vLLM 服务

   用 serve.sh 拉起 OpenAI 兼容服务，模型名 tencent/HunyuanOCR，-tp 1 单卡，最大上下文 131072。

   MODEL_PATH=./HunyuanOCR GPU=0 PORT=8000 bash inference/vLLM/serve.sh

   复制

5. 5检查服务就绪

   请求 /v1/models 接口，能返回模型列表说明服务已启动成功，可以开始发送图片。

   curl -sf http://127.0.0.1:8000/v1/models

   复制

6. 6单张图片推理

   用客户端脚本请求刚才启动的服务，--task-type 锁定官方任务类型，例如 doc_parse 文档解析。

   python inference/vLLM/infer_vllm_client.py \
       --image /path/to/document.png --task-type doc_parse \
       --model tencent/HunyuanOCR --port 8000 --max-tokens 32768

   复制

7. 7批量目录推理

   对图片目录批量推理，支持多端点并发与断点续跑，--concurrency 控制并发数，结果写入 out-dir。

   python inference/vLLM/batch_infer.py \
       --image-dir /path/to/images --out-dir /path/to/output \
       --ports 8000 --task-type doc_parse --max-tokens 32768 --concurrency 16

   复制

关键配置

如何确认成功

执行 curl -sf http://127.0.0.1:8000/v1/models，能正常返回模型列表即表示服务启动成功、可接收请求。

常见问题

注意事项

• 采样参数已内置：temperature=0.0、top_p=1.0、top_k=-1、repetition_penalty=1.08，并内置尾部重复早停与结果清理。
• README 未给出模型权重的具体下载步骤，需自行按 MODE_PATH 指向的目录准备好 HunyuanOCR 权重再启动服务。
• flash-attn==2.8.3 必须加 --no-build-isolation --no-cache-dir 安装，否则容易编译失败。
• 旧的 HunyuanOCR-1.0 在 v1.0 分支或 HunyuanOCR_v1.0/README_v1.0.md 中查看，与本教程的 1.5 命令不通用。