doctr

环境要求

• Python 环境与 pip（README 未指定最低版本）
• 如需可视化结果，需额外安装 matplotlib 与 mplcursors
• 如需解析网页 URL，需额外安装 weasyprint
• 本地 Demo 需要 Streamlit 依赖
• 使用 Docker GPU 镜像时，宿主机 CUDA 需不低于 12.2 并配置 NVIDIA Container Toolkit

安装与启动步骤

1. 1安装 docTR

   使用 pip 安装核心库，即可获得文本检测与识别能力，支持 PyTorch 后端。

   pip install python-doctr

   复制

2. 2安装可选依赖

   需要可视化、HTML 解析和 contrib 模块时再安装这一组附加依赖。

   pip install "python-doctr[viz,html,contrib]"

   复制

3. 3加载预训练模型

   用 ocr_predictor 指定检测与识别架构，pretrained=True 会自动下载权重。

   from doctr.models import ocr_predictor
   
   model = ocr_predictor(det_arch="db_resnet50", reco_arch="crnn_vgg16_bn", pretrained=True)

   复制

4. 4读取文档

   支持 PDF、图片，也支持从 URL 读取网页（需 weasyprint）。把路径换成自己的文件。

   from doctr.io import DocumentFile
   
   pdf_doc = DocumentFile.from_pdf("path/to/your/doc.pdf")
   single_img_doc = DocumentFile.from_images("path/to/your/img.jpg")
   webpage_doc = DocumentFile.from_url("https://www.yoursite.com")

   复制

5. 5执行识别并导出

   推理得到 Document 对象，可直接 show() 查看或 export() 成可转 JSON 的嵌套字典。

   result = model([single_img_doc])
   result.show()
   json_output = result.export()

   复制

6. 6启动本地 Demo

   先安装 demo 专用依赖（含 Streamlit），再用 streamlit 命令在浏览器中打开应用。

   pip install -r demo/pt-requirements.txt
   streamlit run demo/app.py

   复制

7. 7部署本地 API

   进入 api 目录安装 poetry 与依赖，再用 uvicorn 启动带自动文档的 OCR 服务。

   cd api/
   pip install poetry
   make lock
   pip install -r requirements.txt
   uvicorn --reload --workers 1 --host 0.0.0.0 --port=8002 --app-dir api/ app.main:app

   复制

8. 8用容器跑 API

   也可用 docker-compose 一键构建并后台启动同一套 API，端口由 PORT 指定。

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

   复制

关键配置

如何确认成功

API 启动后访问 http://localhost:8002/redoc 能看到自动生成的接口文档，说明检测、识别、OCR、KIE 路由已就绪。

常见问题

注意事项

• README 未给出 pip install 之外的最小 Python 版本要求，建议使用较新的 Python 环境。
• Docker 镜像标签见 GitHub Packages 页面，GPU 运行需加 --gpus all 参数。
• 本地构建镜像可用 docker build -t doctr . 并通过 --build-arg 指定 FRAMEWORK、PYTHON_VERSION、DOCTR_VERSION。