由 PyTorch 提供支持，让光学字符识别变得无缝且人人可用

您将从本仓库中获得：

• 从文档中高效解析文本信息（定位并识别每个单词）的方法
• 如何将其集成到您现有架构中的指导

快速入门

获取预训练模型

docTR 中的端到端 OCR 是通过两阶段方法实现的：文本检测（定位单词），然后文本识别（识别单词中的所有字符）。 因此，您可以从可用的实现列表中选择用于文本检测和用于文本识别的架构。

from doctr.models import ocr_predictor

model = ocr_predictor(det_arch='db_resnet50', reco_arch='crnn_vgg16_bn', pretrained=True)

读取文件

文档可以从 PDF 或图像中解析：

from doctr.io import DocumentFile
# PDF
pdf_doc = DocumentFile.from_pdf("path/to/your/doc.pdf")
# 图像
single_img_doc = DocumentFile.from_images("path/to/your/img.jpg")
# 网页（需要安装 `weasyprint`）
webpage_doc = DocumentFile.from_url("https://www.yoursite.com")
# 多页图像
multi_img_doc = DocumentFile.from_images(["path/to/page1.jpg", "path/to/page2.jpg"])

组合使用

让我们以默认的预训练模型为例：

from doctr.io import DocumentFile
from doctr.models import ocr_predictor

model = ocr_predictor(pretrained=True)
# PDF
doc = DocumentFile.from_pdf("path/to/your/doc.pdf")
# 分析
result = model(doc)

处理旋转的文档

如果您在 docTR 中处理包含旋转页面或具有多种框方向的文档，您可以选择以下几种方式来处理：

• 如果您只使用页面和文字都为直立（水平、相同阅读方向）的文档，请考虑在 ocr_predictor 中传递 assume_straight_pages=True。它会直接在您的页面上拟合直立框，并返回直立框，这是最快的方式。

• 如果您希望预测器输出直立框（无论页面方向如何，最终的定位都会被转换为直立框），则需要在预测器中传递 export_as_straight_boxes=True。否则，如果 assume_straight_pages=False，它将返回旋转的边界框（可能角度为 0°）。

如果这两个选项都设置为 False，预测器将始终拟合并返回旋转的边界框。

要解释模型的预测结果，您可以按如下方式交互式地可视化它们：

# 显示结果（需要安装 matplotlib 和 mplcursors）
result.show()

或者甚至可以根据预测结果重建原始文档：

import matplotlib.pyplot as plt

synthetic_pages = result.synthesize()
plt.imshow(synthetic_pages[0]); plt.axis('off'); plt.show()

ocr_predictor 返回一个带有嵌套结构的 Document 对象（包含 Page、Block、Line、Word、Artefact）。要更好地了解我们的文档模型，请查看我们的文档：

您还可以将其导出为更适合 JSON 格式的嵌套字典：

json_output = result.export()

使用 KIE 预测器

与 OCR 相比，KIE 预测器更加灵活，因为您的检测模型可以检测文档中的多个类别。例如，您可以使用检测模型来检测文档中的日期和地址。

KIE 预测器使您能够将多类别的检测模型与识别模型结合使用，并为您预先设置好整个流程。

from doctr.io import DocumentFile
from doctr.models import kie_predictor

# 模型
model = kie_predictor(det_arch='db_resnet50', reco_arch='crnn_vgg16_bn', pretrained=True)
# PDF
doc = DocumentFile.from_pdf("path/to/your/doc.pdf")
# 分析
result = model(doc)

predictions = result.pages[0].predictions
for class_name in predictions.keys():
    list_predictions = predictions[class_name]
    for prediction in list_predictions:
        print(f"Prediction for {class_name}: {prediction}")

KIE 预测器每页的结果以字典格式呈现，每个键代表一个类别名称，其值是该类别的预测结果。

如果您需要 Mindee 团队的支持

安装

先决条件

安装 docTR 需要 Python 3.10（或更高版本）以及 pip。

最新版本

随后，您可以使用 pypi 安装该包的最新版本，命令如下：

pip install python-doctr

我们尽量将额外依赖保持在最低限度。您也可以按需安装特定构建版本，方法如下：

# 标准构建
pip install python-doctr
# 如果需要可视化、HTML 和 contrib 模块的可选依赖，可以这样安装：
pip install "python-doctr[viz,html,contrib]"

开发者模式

此外，您也可以从源代码安装，这需要先安装 Git。首先克隆项目仓库：

git clone https://github.com/mindee/doctr.git
pip install -e doctr/.

同样地，如果您希望避免遗漏依赖的风险，可以直接安装构建版本：

pip install -e doctr/.

模型架构

在此特别鸣谢：本仓库实现了多篇已发表研究论文中的模型架构。

文本检测

• DBNet：基于可微二值化的实时场景文本检测
• LinkNet：LinkNet：利用编码器表示进行高效语义分割
• FAST：FAST：基于极简核表示的更快任意形状文本检测器

文本识别

• CRNN：端到端可训练的图像序列识别神经网络及其在场景文本识别中的应用
• SAR：展示、注意与阅读：一种简单而强大的不规则文本识别基线
• MASTER：MASTER：用于场景文本识别的多视角非局部网络
• ViTSTR：用于快速高效场景文本识别的视觉Transformer
• PARSeq：基于置换自回归序列模型的场景文本识别
• VIPTR：用于快速高效场景文本识别的视觉可置换提取器

更多实用功能

文档

完整的包文档请访问 这里，以获取详细说明。

示例应用

我们提供了一个极简示例应用，供您体验我们的端到端 OCR 模型！

在线演示

感谢 :hugs: Hugging Face :hugs:，docTR 现已在 Spaces 上部署了完整版本！快去看看吧

本地运行

如果您更倾向于在本地使用，还需要安装一个额外的依赖项（Streamlit)。

pip install -r demo/pt-requirements.txt

然后在您的默认浏览器中运行应用：

streamlit run demo/app.py

Docker 容器

我们提供了 Docker 容器支持，方便测试和部署。可用的 Docker 标签在这里。。

使用 GPU 运行 docTR Docker 镜像

docTR 的 Docker 镜像已支持 GPU，并基于 CUDA 12.2 构建。请确保您的主机至少为 12.2 版本，否则 PyTorch 将无法初始化 GPU。同时，请确保 Docker 已正确配置以使用您的 GPU。

要验证并配置 Docker 的 GPU 支持，请按照 NVIDIA Container Toolkit 安装指南 中的说明操作。

完成 GPU 配置后，您可以运行支持 GPU 的 docTR Docker 容器：

docker run -it --gpus all ghcr.io/mindee/doctr:torch-py3.9.18-2024-10 bash

可用标签

docTR 的 Docker 镜像采用特定的标签命名规则：-py-<doctr_version|YYYY-MM>。标签结构分解如下：

• <deps>：torch、torch-viz-html-contrib。
• <python_version>：3.9.18、3.10.13 或 3.11.8。
• <doctr_version>：标签 ≥ v0.11.0。
• <YYYY-MM>：例如 2014-10。

以下是不同镜像标签的示例：

标签	描述
torch-viz-html-contrib-py3.11.8-2024-10	带有额外依赖的 PyTorch 版本 3.11.8，基于 main 分支在 2024 年 10 月的最新提交。
torch-py3.11.8-2024-10	PyTorch 版本 3.11.8，基于 main 分支在 2024 年 10 月的最新提交。

本地构建 Docker 镜像

您也可以在本地计算机上构建 docTR 的 Docker 镜像。

docker build -t doctr .

您可以通过构建参数指定自定义的 Python 版本和 docTR 版本。例如，要构建一个包含 PyTorch、Python 3.9.10 和 docTR v0.7.0 的镜像，可以运行以下命令：

docker build -t doctr --build-arg FRAMEWORK=torch --build-arg PYTHON_VERSION=3.9.10 --build-arg DOCTR_VERSION=v0.7.0 .

示例脚本

我们提供了一个示例脚本，用于对 PDF 或图像文件进行简单的文档分析：

python scripts/analyze.py path/to/your/doc.pdf

您可以通过 python scripts/analyze.py --help 查看所有脚本参数。

极简 API 集成

希望将 docTR 集成到您的 API 中吗？这里有一个模板，帮助您使用优秀的 FastAPI 框架快速搭建一个可运行的 API。

在本地部署您的 API

运行此 API 模板需要一些特定的依赖项，您可以按如下方式安装：

cd api/
pip install poetry
make lock
pip install -r requirements.txt

现在您可以在本地运行您的 API：

uvicorn --reload --workers 1 --host 0.0.0.0 --port=8002 --app-dir api/ app.main:app

或者，如果您更喜欢使用 Docker 容器，也可以通过以下命令启动相同的服务：

PORT=8002 docker-compose up -d --build

您已部署的内容

您的 API 现在应该正在本地的 8002 端口上运行。您可以通过 http://localhost:8002/redoc 访问自动生成的文档，并体验三个可用的路由（“/detection”、“/recognition”、“/ocr”、“/kie”）。以下是一个使用 Python 向 OCR 路由发送请求的示例：

import requests

params = {"det_arch": "db_resnet50", "reco_arch": "crnn_vgg16_bn"}

with open('/path/to/your/doc.jpg', 'rb') as f:
    files = [  # 支持 application/pdf、image/jpeg、image/png 格式
        ("files", ("doc.jpg", f.read(), "image/jpeg")),
    ]
print(requests.post("http://localhost:8080/ocr", params=params, files=files).json())

示例笔记本

想了解更多关于 docTR 功能的示例吗？不妨查看我们精心设计的 Jupyter 笔记本，它们将为您提供更全面的概览。

支持单位

本项目由 t2k GmbH 提供支持。

引用

如果您希望引用本项目，可以使用以下 BibTeX 格式的参考文献：

@misc{doctr2021,
    title={docTR: 文档文本识别},
    author={Mindee},
    year={2021},
    publisher = {GitHub},
    howpublished = {\url{https://github.com/mindee/doctr}}
}

贡献

如果您翻到这一部分，很可能您非常认可开源精神。您是否愿意扩展我们支持的字符范围？或者提交一篇论文实现？亦或是以其他方式做出贡献？

那您就来对了！我们为您整理了一份简短指南（参见 CONTRIBUTING），帮助您轻松参与贡献！

许可证

本项目采用 Apache 2.0 许可证进行分发。更多信息请参阅 LICENSE 文件。

doctr 快速上手指南

doctr 是一个基于 PyTorch 的开源光学字符识别（OCR）工具，旨在让文档文本信息的提取（定位与识别）变得简单高效。它采用两阶段方法：先进行文本检测（定位单词），再进行文本识别（识别字符）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.10 或更高版本
• 包管理工具：pip
• 可选依赖：
  • 若需可视化结果，需安装 matplotlib 和 mplcursors。
  • 若需解析网页，需安装 weasyprint。
  • 若需运行本地 Demo 应用，需安装 streamlit。

提示：国内用户建议使用国内镜像源加速安装，例如阿里云或清华大学镜像源。

安装步骤

方式一：通过 PyPI 安装（推荐）

安装最新稳定版：

pip install python-doctr -i https://pypi.tuna.tsinghua.edu.cn/simple

若需要额外的可视化、HTML 导出或贡献模块功能，可安装完整依赖：

pip install "python-doctr[viz,html,contrib]" -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装（开发者模式）

如果您希望使用最新开发版本或参与贡献：

git clone https://github.com/mindee/doctr.git
cd doctr
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的端到端 OCR 使用流程，涵盖模型加载、文档读取及结果分析。

1. 快速开始示例

这段代码将加载预训练模型，读取一个 PDF 文件，并输出识别结果。

from doctr.io import DocumentFile
from doctr.models import ocr_predictor

# 加载预训练模型 (默认使用 db_resnet50 进行检测，crnn_vgg16_bn 进行识别)
model = ocr_predictor(pretrained=True)

# 读取文档 (支持 PDF, 图片，或图片列表)
doc = DocumentFile.from_pdf("path/to/your/doc.pdf")
# 如果是图片：doc = DocumentFile.from_images("path/to/your/img.jpg")

# 执行 OCR 分析
result = model(doc)

# 查看结果结构 (result 是一个包含 Page, Block, Line, Word 的嵌套对象)
print(result.export()) 

2. 可视化结果

若已安装可视化依赖，可以直接展示检测框和识别文本：

# 交互式显示结果
result.show()

或者合成重建文档图像：

import matplotlib.pyplot as plt

synthetic_pages = result.synthesize()
plt.imshow(synthetic_pages[0])
plt.axis('off')
plt.show()

3. 处理旋转文档

如果您的文档包含旋转页面或非水平文本，可以通过调整参数优化效果：

• assume_straight_pages=True：假设页面和文字都是水平的（速度最快）。
• export_as_straight_boxes=True：无论原始角度如何，强制输出水平边界框。

# 针对可能包含旋转内容的文档
model = ocr_predictor(pretrained=True, assume_straight_pages=False, export_as_straight_boxes=True)
result = model(doc)

4. 关键信息提取 (KIE)

除了通用 OCR，doctr 还支持针对特定类别（如日期、地址）的关键信息提取：

from doctr.models import kie_predictor

# 加载 KIE 预测器
model = kie_predictor(det_arch='db_resnet50', reco_arch='crnn_vgg16_bn', pretrained=True)

doc = DocumentFile.from_pdf("path/to/your/doc.pdf")
result = model(doc)

# 遍历不同类别的预测结果
predictions = result.pages[0].predictions
for class_name, list_predictions in predictions.items():
    for prediction in list_predictions:
        print(f"类别 {class_name}: {prediction}")