一、模型介绍

腾讯混元团队于 2025 年 11 月 25 日正式开源了 HunyuanOCR——一款仅 10 亿参数、却拿下多项 SOTA 的商业级 OCR 视觉-语言模型。

HunyuanOCR 是一款基于腾讯混元原生多模态架构的端到端 OCR 专家模型。仅以 1B 轻量化参数，便已斩获多项业界 SOTA 成绩。该模型精通 复杂多语种文档解析 ，同时在文字检测识别、开放字段信息抽取、视频字幕识别、拍照翻译等全场景实用技能中表现出色。

核心特点

• 💪 轻量化架构 ：基于混元原生多模态架构与训练策略，打造仅 1B 参数的 OCR 专项模型，大幅降低部署成本。
• 📑 全场景功能 ：单一模型覆盖文字检测和识别、复杂文档解析、卡证票据字段抽取、字幕提取等 OCR 经典任务，更支持端到端拍照翻译与文档问答。
• 🚀 极致易用 ：深度贯彻大模型"端到端"理念，单一指令、单次推理直达 SOTA 结果，较业界级联方案更高效便捷。
• 🌏 多语种支持 ：支持超过 100 种语言，在单语种和混合语言场景下均表现出色。
  

更多详情请见：Tencent-Hunyuan/HunyuanOCR

二、部署流程

基础环境推荐：

环境名称	版本信息
Ubuntu	24.04.3 LTS
Cuda	V12.9
Python	3.12
PyTorch	2.7.1
NVIDIA Corporation	RTX 4090

注：该模型对于CUDA、Python及PyTorch版本要求较高；若低于如上版本信息，则无法进行vllm推理。

1.更新基础软件包

查看系统版本信息

#查看系统的版本信息，包括 ID（如 ubuntu、centos 等）、版本号、名称、版本号 ID 等
cat /etc/os-release

更新软件包列表

#更新软件列表
apt-get update

2.创建虚拟环境

为方便后续vllm的推理使用，这里利用 uv venv hunyuanocr 创建一个名为hunyuanocr的虚拟环境。

#创建一个名为hunyuanocr的虚拟环境
uv venv hunyuanocr

激活虚拟环境

source hunyuanocr/bin/activate

3.克隆仓库、安装依赖

特别的，如需要该模型可视化访问页面，这里推荐 huggingface 上官方给出的 gradio 页面模板

git clone https://huggingface.co/spaces/tencent/HunyuanOCR

同样的，使用该模板，也需要进入 HunyuanOCR 目录下，安装所需依赖项

cd HunyuanOCR
uv pip install -r requirements.txt

4.vllm推理安装包（可选）

安装/升级 vLLM 到最新 nightly 预览版。

uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
uv pip install -r requirements.txt0

安装 cuda-compat-12-9 :

sudo dpkg -i cuda-compat-12-9_575.57.08-0ubuntu1_amd64.deb

若输入命令后提示找不到存储文件，则需要进行手动下载并安装

把兼容库路径永久写进当前用户的 ~/.bashrc，使其每次打开新终端自动生效。

echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.9/compat:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

5.模型下载

这里推荐转到魔塔社区官网下载模型文件：HunyuanOCR · 模型库

使用命令行下载完整模型库

#在下载前，请先通过如下命令安装
pip install modelscope

转到根目录下，创建 model 目录用于存放模型权重文件，在使用命令行下载 modelscope download --model Tencent-Hunyuan/HunyuanOCR --local_dir ./

cd /
mkdir model 
cd model
modelscope download --model Tencent-Hunyuan/HunyuanOCR  --local_dir ./

6.运行gradio脚本，实现模型交互

进入 /HunyuanOCR  目录，修改其中的 web 启动代码 app.py：

vim /HunyuanOCR/app.py

将模型的加载路径改为本地路径 /model/ , 以及 lunch 加载函数中设置 share=False,server_name='0.0.0.0',server_port=8080

运行脚本

#执行修改好的 app.py 文件
python app.py

将网址：http://localhost:8080/粘贴到浏览器中，便可与模型进行对话

7.启动vllm推理（可选）

vllm serve /model \
--no-enable-prefix-caching \
--mm-processor-cache-gb 0 \
--gpu-memory-utilization 0.2