当前位置：首页 > news >正文

OvisOCR2 API参考大全：从基础调用到高级配置的完整文档

news 2026/7/15 18:18:59

OvisOCR2 API参考大全：从基础调用到高级配置的完整文档

【免费下载链接】OvisOCR2项目地址: https://ai.gitcode.com/hf_mirrors/ATH-MaaS/OvisOCR2

OvisOCR2是一款强大的端到端文档解析模型，能够将文档页面图像转换为Markdown格式的自然阅读顺序输出。这款仅0.8B参数的小型模型在文档解析性能上表现出色，支持文本、公式、表格和视觉区域的识别与转换。本指南将为您提供完整的API参考，从基础安装到高级配置，帮助您充分利用OvisOCR2的强大功能。

🚀 快速开始：安装与基础使用

要开始使用OvisOCR2，首先需要安装必要的依赖包：

pip install "vllm==0.22.1" pillow

基础调用非常简单，只需几行代码即可完成文档解析：

from PIL import Image from vllm import LLM, SamplingParams class OvisOCR2Parser: def __init__(self, model_name_or_path: str): self.model = LLM( model=model_name_or_path, tensor_parallel_size=1, gpu_memory_utilization=0.8, gdn_prefill_backend="triton" ) # 初始化提示词和采样参数 self.sampling_params = SamplingParams(max_tokens=16384, temperature=0.0) def parse(self, images: list[Image.Image]) -> list[str]: # 解析文档图像 outputs = self.model.generate(vllm_inputs, self.sampling_params) return [output.outputs[0].text.strip() for output in outputs] # 使用示例 parser = OvisOCR2Parser("ATH-MaaS/OvisOCR2") images = [Image.open("document.jpg")] markdowns = parser.parse(images) print(markdowns[0])

📊 核心API详解

OvisOCR2Parser类

OvisOCR2Parser是整个库的核心类，负责初始化模型和处理文档解析任务。

构造函数参数

def __init__(self, model_name_or_path: str): """ 初始化OvisOCR2解析器 参数： - model_name_or_path: 模型名称或本地路径，如"ATH-MaaS/OvisOCR2" """

构造函数会自动配置vLLM引擎，使用以下优化设置：

tensor_parallel_size=1: 单GPU并行
gpu_memory_utilization=0.8: 80% GPU内存利用率
gdn_prefill_backend="triton": 使用Triton后端加速

parse方法

def parse(self, images: list[Image.Image], filter_imgtags: bool = True) -> list[str]: """ 解析文档图像为Markdown格式 参数： - images: PIL.Image.Image对象列表 - filter_imgtags: 是否过滤HTML图像标签（默认为True） 返回： - 解析后的Markdown字符串列表 """

parse方法支持批量处理多个文档图像，每个图像都会生成独立的Markdown输出。当filter_imgtags=True时，系统会自动移除视觉区域的HTML标签，只保留文本内容。

🔧 高级配置选项

模型配置详解

OvisOCR2基于Qwen3.5-0.8B架构，配置文件位于config.json中，包含以下关键配置：

{ "architectures": ["Qwen3_5ForConditionalGeneration"], "model_type": "qwen3_5", "text_config": { "hidden_size": 1024, "num_hidden_layers": 24, "num_attention_heads": 8, "max_position_embeddings": 262144, "vocab_size": 248320 }, "vision_config": { "hidden_size": 768, "num_heads": 12, "patch_size": 16, "num_position_embeddings": 2304 } }

采样参数优化

通过调整SamplingParams可以优化输出质量：

sampling_params = SamplingParams( max_tokens=16384, # 最大输出token数 temperature=0.0, # 温度参数（0为确定性输出） top_p=0.9, # 核采样参数 top_k=50, # Top-K采样 repetition_penalty=1.1 # 重复惩罚 )

🎯 视觉区域处理

OvisOCR2能够识别文档中的视觉区域（如图表、图像），并以HTML标签形式标注：

def save_renderable_markdown_with_visual_regions( markdown: str, page_image: Image.Image, output_dir: str, ) -> None: """ 保存包含视觉区域的Markdown文档 参数： - markdown: 解析后的Markdown文本 - page_image: 原始页面图像 - output_dir: 输出目录路径 """

该方法会：

解析Markdown中的图像标签：<img src="images/bbox_{left}_{top}_{right}_{bottom}.jpg" />
根据坐标裁剪原始图像
保存裁剪后的图像到指定目录
生成完整的Markdown文件

⚡ 性能调优技巧

内存优化

对于大文档或批量处理，可以调整GPU内存使用：

self.model = LLM( model=model_name_or_path, tensor_parallel_size=2, # 多GPU并行 gpu_memory_utilization=0.7, # 降低内存使用率 max_model_len=32768, # 增加最大模型长度 enable_prefix_caching=True # 启用前缀缓存 )

批处理优化

# 批量处理提高效率 batch_size = 4 images_batches = [images[i:i+batch_size] for i in range(0, len(images), batch_size)] for batch in images_batches: markdowns = parser.parse(batch) # 处理结果...

🔍 错误处理与调试

常见问题解决

内存不足错误：降低gpu_memory_utilization或减少批处理大小
输出截断：增加max_tokens参数值
重复内容：使用内置的_clean_truncated_repeats方法清理

调试模式

# 启用详细日志 import logging logging.basicConfig(level=logging.DEBUG) # 检查输入图像尺寸 for img in images: print(f"图像尺寸: {img.size}, 模式: {img.mode}")

📈 性能基准

OvisOCR2在多个基准测试中表现优异：

OmniDocBench v1.6: 总分96.58，超越所有端到端模型
PureDocBench: Avg3得分75.06，保持领先地位
支持格式: 文本、公式、表格、视觉区域
输出格式: Markdown，保持自然阅读顺序

🛠️ 高级用法示例

自定义提示词

custom_prompt = """ 请从图像中提取所有可读内容，按照自然阅读顺序输出为Markdown文档。 对于图表或图像，使用HTML图像标签表示：<img src="images/bbox_{left}_{top}_{right}_{bottom}.jpg" /> 公式使用LaTeX格式，表格使用HTML格式。 保留原始文本，不进行翻译或改写。 """ # 在初始化时替换默认提示词 self.prompt = self.model.get_tokenizer().apply_chat_template( [{"role": "user", "content": [{"type": "image"}, {"type": "text", "text": custom_prompt}]}], tokenize=False, add_generation_prompt=True )

多语言支持

虽然OvisOCR2主要针对中文文档优化，但也能处理多语言内容：

# 设置语言特定的提示词 multilingual_prompt = """ Extract all readable content from the image in natural reading order. For charts or images, use HTML image tags. Format formulas as LaTeX and tables as HTML. Preserve the original text without translation. """