综合介绍

dots.ocr 是一个开源的文档解析工具，它基于一个1.7B参数的视觉语言模型（Vision-Language Model），实现了在单一模型内同时完成多语言文档的版面布局分析和文字内容识别。与依赖多个模型组合的传统方法不同，dots.ocr 的架构更为精简。用户仅通过修改输入的提示词（Prompt），就能切换不同的解析任务，例如仅检测版面、仅识别文字或两者都做。该模型在处理英文、中文及其他低资源语言的文档时，均表现出强大的性能，特别是在文本、表格识别和阅读顺序方面达到了业界先进水平。由于其模型规模相对较小，它在保证解析效果的同时，也提供了比许多基于更大规模模型的工具更快的推理速度。

功能列表

• 统一架构：在单个视觉语言模型中集成了版面检测和内容识别功能，简化了传统复杂的处理流程。
• 多语言支持：能有效解析多种语言的文档，包括一些计算资源较少的“低资源”语言，并在自建的多语言基准测试中表现出色。
• 任务切换灵活：用户只需更改输入的提示词，即可命令模型执行不同的任务，如仅进行版面检测或仅内容识别，无需更换模型。
• 高性能表现：在公开的文档解析评测基准 OmniDocBench 上，其文本、表格和阅读顺序处理效果达到顶尖水平（SOTA），公式识别效果可与 Gemini2.5-Pro 等更大模型相媲美。
• 结构化输出：将解析结果以结构化的 JSON 格式输出，内容包含布局元素的类别、位置坐标（bbox）和识别出的文本。同时提供 Markdown 文件和带有标注框的可视化图片。
• 高效推理：基于一个相对紧凑的1.7B参数语言模型构建，相比许多基于更大模型的工具，处理速度更快。
• 部署简便：支持使用 vLLM 进行高性能服务部署，同时也提供了基于 Hugging Face Transformers 的本地推理方式，并提供 Docker 镜像简化环境配置。

使用帮助

dots.ocr 的使用流程主要分为环境安装、下载模型和执行解析三个步骤。官方推荐使用 vLLM 进行服务化部署以获得最佳性能。

1. 环境安装

官方推荐使用 Conda 创建独立的 Python 环境。

# 创建一个名为 dots_ocr 的环境，并指定 Python 版本为 3.12
conda create -n dots_ocr python=3.12
# 激活该环境
conda activate dots_ocr
# 从 GitHub 克隆项目代码
git clone https://github.com/rednote-hilab/dots.ocr.git
# 进入项目目录
cd dots.ocr
# 安装 PyTorch，请根据你的 CUDA 版本访问官网 (https://pytorch.org/get-started/previous-versions/) 获取对应的安装命令
# 以下命令适用于 CUDA 12.8
pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://download.pytorch.org/whl/cu128
# 安装 dots.ocr 的其他依赖
pip install -e .

备选方案：使用 Docker

如果手动安装遇到困难，可以使用官方提供的 Docker 镜像来简化环境配置。

2. 下载模型权重

安装完环境后，需要下载模型文件。

# 运行下载脚本，脚本将从 ModelScope 或 Hugging Face 下载模型
python3 tools/download_model.py

注意：下载时，请确保模型保存的路径目录名不包含点号（.），例如使用 DotsOCR 而非 dots.ocr。这是为了兼容 Transformers 加载的一个临时措施。

3. 部署与使用

方案一：vLLM 服务化部署（推荐）

vLLM 提供了非常高的推理效率，是官方推荐的部署方式。

1. 注册模型到 vLLM在启动服务前，需要先向 vLLM 注册 dots.ocr 模型。

   # 设置模型路径变量，请确保这里的路径是你下载模型时使用的无点号路径
   export hf_model_path=./weights/DotsOCR
   # 将模型路径添加到 Python 环境变量
   export PYTHONPATH=$(dirname "$hf_model_path"):$PYTHONPATH
   # 将模型导入语句添加到 vllm 的启动脚本中
   # 注意：如果你的模型目录名不是 DotsOCR，请替换下面的 `DotsOCR`
   sed -i '/^from vllm\.entrypoints\.cli\.main import main$/a\ from DotsOCR import modeling_dots_ocr_vllm' `which vllm`
   

2. 启动 vLLM 服务

   # 在指定的 GPU (例如0号卡) 上启动服务
   CUDA_VISIBLE_DEVICES=0 vllm serve ${hf_model_path} \
   --tensor-parallel-size 1 \
   --gpu-memory-utilization 0.95 \
   --chat-template-content-format string \
   --served-model-name model \
   --trust-remote-code
   

   如果启动时遇到 ModuleNotFoundError: No module named 'DotsOCR'，请检查模型保存的目录名是否不含点号。

3. 通过 API 调用服务进行解析服务启动后，可以运行 parser.py 脚本来解析文档。
   • 解析单个图片（完整解析：版面+内容）

     python3 dots_ocr/parser.py demo/demo_image1.jpg
     

   • 解析单个 PDF 文件可以指定线程数 --num_thread 来加速处理多页PDF。

     python3 dots_ocr/parser.py demo/demo_pdf1.pdf --num_thread 64
     

   • 指定不同解析模式（通过 prompt 参数）通过 --prompt 参数可以控制模型的行为。

     # 仅进行版面检测，不识别内容
     python3 dots_ocr/parser.py demo/demo_image1.jpg --prompt prompt_layout_only_en
     # 仅进行文字识别（OCR），忽略页眉和页脚
     python3 dots_ocr/parser.py demo/demo_image1.jpg --prompt prompt_ocr
     # 对指定区域（bbox）进行识别
     python3 dots_ocr/parser.py demo/demo_image1.jpg --prompt prompt_grounding_ocr --bbox 163 241 1536 705
     

方案二：Hugging Face Transformers 本地推理

这种方式无需启动服务，但推理速度比 vLLM 慢，适合快速测试或在没有 vLLM 环境时使用。

1. 直接运行解析脚本在使用 parser.py 脚本时，增加 --use_hf true 参数即可。

   python3 dots_ocr/parser.py demo/demo_image1.jpg --use_hf true
   

2. 在 Python 代码中调用你也可以在自己的 Python 代码中直接加载模型进行推理。

   import torch
   from transformers import AutoModelForCausalLM, AutoProcessor
   from dots_ocr.utils import process_vision_info # 自定义工具函数
   # 指定模型路径（不含点号）
   model_path = "./weights/DotsOCR"
   # 加载模型和处理器
   model = AutoModelForCausalLM.from_pretrained(
   model_path,
   attn_implementation="flash_attention_2",
   torch_dtype=torch.bfloat16,
   device_map="auto",
   trust_remote_code=True
   )
   processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)
   image_path = "demo/demo_image1.jpg"
   # 定义任务指令
   prompt = """请从PDF图像中输出版面布局信息，包括每个布局元素的边界框（bbox）、类别以及框内的相应文本内容。1. Bbox格式：[x1, y1, x2, y2] 2. 布局类别：可能的类别包括['Caption', 'Footnote', 'Formula', 'List-item', 'Page-footer', 'Page-header', 'Picture', 'Section-header', 'Table', 'Text', 'Title']。3. 文本提取和格式化规则： - Picture：对于'Picture'类别，文本字段应省略。 - Formula：将其文本格式化为LaTeX。 - Table：将其文本格式化为HTML。 - 其他所有（Text, Title等）：将其文本格式化为Markdown。4. 约束条件： - 输出的文本必须是图像中的原始文本，不得翻译。 - 所有布局元素必须按照人类阅读顺序排序。5. 最终输出：整个输出必须是一个单一的JSON对象。"""
   messages = [
   {
   "role": "user",
   "content": [
   {"type": "image", "image": image_path},
   {"type": "text", "text": prompt}
   ]
   }
   ]
   # 准备推理输入
   text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
   image_inputs, _ = process_vision_info(messages)
   inputs = processor(
   text=[text],
   images=image_inputs,
   padding=True,
   return_tensors="pt",
   ).to("cuda")
   # 执行推理
   generated_ids = model.generate(**inputs, max_new_tokens=24000)
   generated_ids_trimmed = [out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
   output_text = processor.batch_decode(generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False)
   print(output_text)
   

4. 查看输出结果

解析完成后，默认会在输入文件同级目录下生成三个文件：

• {文件名}.json: 包含所有版面元素（如文本块、表格、公式等）的类别、坐标和识别内容的结构化数据文件。
• {文件名}.md: 将所有识别出的文本内容（不含页眉页脚）拼接而成的 Markdown 文件，便于阅读和复制。
• {文件名}_vis.jpg: 在原图上绘制了识别出的版面区域框的可视化图片，用于直观检查检测效果。

应用场景

1. 文档数字化与归档将扫描的纸质文件、书籍、报告等批量转换为结构化的电子数据。例如，图书馆可以将古籍或旧报纸扫描后，通过 dots.ocr 解析其版面和文字，方便后续的检索和数据分析。
2. 自动化数据提取从发票、合同、财务报表等半结构化文档中自动提取关键信息。例如，企业可以利用它自动读取报表中的表格数据，并将其存入数据库，减少人工录入的成本和错误。
3. 学术研究辅助研究人员可以使用 dots.ocr 解析学术论文，快速提取其中的文本、公式（以LaTeX格式）和表格（以HTML格式），方便进行文献回顾、数据引用和模型训练。
4. 多语言内容处理处理包含多种语言的混合文档。例如，一家跨国公司需要处理来自不同国家的报告，dots.ocr 可以在一个流程中解析所有文档，无需为每种语言配置不同的工具。

QA

1. dots.ocr 目前存在哪些局限性？
   • 复杂元素处理：对于结构异常复杂或嵌套层次很深的表格和数学公式，解析效果可能不完美。同时，模型目前不会解析图片中的内容。
   • 解析失败场景：当图片分辨率过低（字符与像素比过高）时，模型可能无法成功解析。此外，连续的特殊字符（如大量下划线 _ 或省略号 ...）可能导致模型输出异常。
   • 处理效率瓶颈：尽管模型本身是轻量级的，但在处理海量PDF文件时，其吞吐量尚未达到最优，不适合对速度要求极高的工业级高并发场景。
2. 如果遇到解析失败或效果不佳，应该如何处理？
   • 提升图片质量：尝试将图片放大或在解析PDF时提高DPI（推荐设置为200）。模型在处理总像素低于1128万的图片时表现最佳。
   • 更换提示词：如果遇到因特殊字符导致的输出问题，可以尝试使用其他功能的提示词，例如 prompt_layout_only_en（仅检测版面）、prompt_ocr（仅识别文本）或 prompt_grounding_ocr（识别指定区域）。
3. 推荐使用哪种方式部署 dots.ocr？官方强烈推荐使用 vLLM 进行服务化部署。vLLM 专为大型语言模型推理优化，可以提供最高的处理效率和吞吐量。若只是进行功能测试或小批量处理，也可以直接使用基于 Hugging Face Transformers 的方式。
4. 这个项目是否支持处理手写体文字？该项目主要针对印刷体文档的版面和内容解析。从其提供的基准测试和示例来看，并未特别提及对手写体的支持，因此在处理手写内容时效果可能无法保证。