OCR Agent 使用文档

项目概述

OCR Agent 是一个基于 PaddleOCR 的扫描图书 OCR 处理系统，支持：

📄 多格式输出：DOCX、PDF、JSON、TXT
🖼️ 图片修复：4x 超分辨率、混合去噪（传统+深度学习）
📐 版面分析：自动检测标题、段落、表格、图像等
✅ 质量评估：自动评估 OCR 质量并提供改进建议
🔧 自动纠错：中英文混淆字自动纠正
🎯 高精度：支持中英文混合识别

安装指南

系统要求

Python 3.8+
4GB+ RAM（推荐 8GB+）
2GB+ 磁盘空间（用于模型）

安装步骤

1. 克隆项目

git clone https://github.com/your-repo/ocr-agent.git
cd ocr-agent

2. 创建虚拟环境

# 使用 conda（推荐）
conda create -n ocr python=3.12
conda activate ocr

# 或使用 venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

3. 安装依赖

pip install -e .

4. 验证安装

ocr-agent --version

快速开始

处理单张图片

# 处理单张图片，输出 DOCX 和 JSON
ocr-agent process /path/to/image.png -o ./output

# 指定输出格式
ocr-agent process /path/to/image.png -o ./output --format docx --format json --format pdf

处理 PDF 文件

# 处理 PDF，每页生成一个输出文件
ocr-agent process /path/to/book.pdf -o ./output --format docx

处理整个目录

# 处理目录中的所有图片
ocr-agent process /path/to/images/ -o ./output --format docx --format json

启动 Web 服务

# 启动 FastAPI 服务
ocr-agent serve --port 8000

# 访问 API 文档
# http://localhost:8000/docs

功能说明

1. 图像预处理

自动对输入图像进行以下处理：

灰度转换：将彩色图像转换为灰度
倾斜校正：自动检测并校正倾斜的文本
去噪：使用 fastNlMeansDenoising 去除噪点
对比度增强：使用 CLAHE 增强对比度
自适应二值化：使用 Sauvola 方法进行二值化

2. OCR 识别

中英文混合识别：支持中文、英文、数字、符号
高精度识别：基于 PaddleOCR 2.9
置信度评分：每个识别结果都有置信度分数

3. 图片修复

低分辨率增强

自动检测：根据 DPI 自动选择修复策略
4x 超分辨率：使用 Real-ESRGAN 4x 模型
2x 超分辨率：使用 Real-ESRGAN 2x 模型

混合去噪

轻度噪点：使用传统方法（中值滤波 + 双边滤波）
重度噪点：使用深度学习模型（NAFNet）
自动判断：根据图像质量自动选择方法

4. 版面分析

元素检测：自动检测标题、段落、列表、表格、图像等
阅读顺序：检测多栏布局的正确阅读顺序
表格识别：识别表格结构和单元格内容

5. 质量评估

页面级统计：计算整页的 OCR 质量
区域级分析：定位低置信度区域
改进建议：自动生成改进建议

6. 自动纠错

中文纠错：纠正常见的中文混淆字
英文纠错：纠正常见的英文混淆字
置信度控制：可配置纠错的置信度阈值

命令行工具

处理命令

ocr-agent process [OPTIONS] INPUT_PATH

选项：

选项	说明	默认值
`-o, --output`	输出目录	`./output`
`--format`	输出格式（可多选）	`docx`
`--enable-repair`	启用图片修复	`true`
`--repair-upscale`	超分辨率倍数（2 或 4）	`4`
`--enable-correction`	启用自动纠错	`true`
`--correction-threshold`	纠错置信度阈值	`0.5`
`--verbose`	详细日志	`false`
`--quiet`	静默模式	`false`

示例：

# 启用所有功能，输出多种格式
ocr-agent process book.pdf -o ./output \
  --format docx --format pdf --format json \
  --enable-repair --repair-upscale 4 \
  --enable-correction --correction-threshold 0.6 \
  --verbose

# 快速处理，禁用修复和纠错
ocr-agent process image.png -o ./output \
  --format json \
  --no-repair --no-correction

服务命令

ocr-agent serve [OPTIONS]

选项：

选项	说明	默认值
`--port`	服务端口	`8000`
`--host`	绑定地址	`127.0.0.1`
`--workers`	工作进程数	`4`

示例：

# 启动服务，监听所有地址
ocr-agent serve --host 0.0.0.0 --port 8000 --workers 4

Python API

基本使用

from ocr_agent.pipeline import OCRPipeline
from ocr_agent.core.config import Config
from pathlib import Path

# 创建配置
config = Config(
    enable_image_repair=True,
    repair_upscale_factor=4,
    enable_correction=True,
    correction_threshold=0.6
)

# 创建 Pipeline
pipeline = OCRPipeline(config)

# 处理单张图片
image_path = Path("image.png")
document = pipeline.process_image(image_path)

# 输出结果
from ocr_agent.modules.output import OutputModule
output = OutputModule(config)
output.generate_docx(document, Path("output.docx"))
output.generate_pdf(document, {0: str(image_path)}, Path("output.pdf"))
output.generate_json(document, Path("output.json"))

处理 PDF

from ocr_agent.pipeline import OCRPipeline
from pathlib import Path

pipeline = OCRPipeline(config)

# 处理 PDF
pdf_path = Path("book.pdf")
document = pipeline.process_pdf(pdf_path)

# 输出结果
output.generate_docx(document, Path("output.docx"))

批量处理

from pathlib import Path

# 处理目录中的所有图片
image_dir = Path("images/")
documents = pipeline.process_directory(image_dir)

# 输出结果
for idx, doc in enumerate(documents):
    output.generate_docx(doc, Path(f"output_{idx}.docx"))

访问 OCR 结果

# 获取文档信息
print(f"页数: {len(document.pages)}")

# 遍历每一页
for page in document.pages:
    print(f"页码: {page.page_num}")
    
    # 获取文本块
    for block in page.text_blocks:
        print(f"文本: {block.text}")
        print(f"置信度: {block.confidence}")
        print(f"位置: ({block.bbox.x}, {block.bbox.y})")
    
    # 获取版面元素
    for element in page.elements:
        print(f"元素类型: {element.type}")
        print(f"文本: {' '.join(b.text for b in element.text_blocks)}")

# 获取质量报告
if document.quality_report:
    print(f"页面质量: {document.quality_report.page_quality}")
    print(f"平均置信度: {document.quality_report.avg_confidence}")

Web API

启动服务

ocr-agent serve --port 8000

API 端点

1. 上传处理

curl -X POST http://localhost:8000/api/v1/jobs \
  -F "file=@image.png" \
  -F "format=docx" \
  -F "format=json"

响应：

{
  "job_id": "abc123",
  "status": "processing",
  "created_at": "2026-05-21T10:00:00Z"
}

2. 查询状态

curl http://localhost:8000/api/v1/jobs/abc123

响应：

{
  "job_id": "abc123",
  "status": "completed",
  "created_at": "2026-05-21T10:00:00Z",
  "completed_at": "2026-05-21T10:05:00Z",
  "results": {
    "docx": "output.docx",
    "json": "output.json"
  }
}

3. 下载结果

curl http://localhost:8000/api/v1/jobs/abc123/results/output.docx \
  -o output.docx

4. 删除任务

curl -X DELETE http://localhost:8000/api/v1/jobs/abc123

5. 健康检查

curl http://localhost:8000/api/v1/health

配置说明

配置文件

创建 config.yaml：

# 图像预处理
preprocessing:
  enable_deskew: true
  enable_denoise: true
  enable_contrast_enhancement: true

# OCR 识别
ocr:
  language: "ch"  # 中文
  use_angle_cls: false

# 图片修复
image_repair:
  enable: true
  upscale_factor: 4  # 2 或 4
  denoise_method: "auto"  # auto, traditional, deep_learning
  denoise_threshold: 0.5

# 自动纠错
correction:
  enable: true
  threshold: 0.6

# 输出
output:
  formats: ["docx", "json", "pdf"]
  pdf_page_width: 210  # mm (A4)
  pdf_page_height: 297  # mm (A4)
  pdf_margin: 10  # mm

Python 配置

from ocr_agent.core.config import Config

config = Config(
    # 预处理
    enable_deskew=True,
    enable_denoise=True,
    
    # OCR
    ocr_language="ch",
    
    # 图片修复
    enable_image_repair=True,
    repair_upscale_factor=4,
    repair_denoise_method="auto",
    repair_denoise_threshold=0.5,
    
    # 纠错
    enable_correction=True,
    correction_threshold=0.6,
    
    # PDF 输出
    pdf_page_width=210,
    pdf_page_height=297,
    pdf_margin=10
)

输出格式

DOCX 格式

保留原始排版结构
支持标题、段落、列表、表格
支持中文字体（SimSun）
文件大小：通常为原始图像的 5-10%

PDF 格式

混合内容处理（文本 + 图像 + 表格）
文本可选和可复制
图像从原始扫描图像中裁剪
保留基本排版结构
文件大小：通常为原始图像的 50-100%

JSON 格式

完整的元数据和结构信息
包含置信度、位置、字体等信息
便于进一步处理和分析

TXT 格式

纯文本输出
按阅读顺序排列
文件大小最小

常见问题

Q1: 如何提高 OCR 准确率？

使用图片修复功能（启用 4x 超分辨率）
确保输入图像清晰（DPI ≥ 150）
调整纠错阈值（correction_threshold）
使用高质量的扫描图像

Q2: 处理速度太慢怎么办？

禁用图片修复：--no-repair
禁用自动纠错：--no-correction
使用 2x 超分辨率而不是 4x：--repair-upscale 2
增加工作进程数：--workers 8

Q3: 内存占用过高怎么办？

处理较小的图像或 PDF
禁用 4x 超分辨率（使用 2x）
减少工作进程数
增加系统 RAM

Q4: 如何处理特殊格式的文档？

扫描 PDF：直接使用 ocr-agent process book.pdf
图片集合：使用 ocr-agent process /path/to/images/
混合格式：分别处理后合并结果

Q5: 如何自定义输出格式？

from ocr_agent.modules.output import OutputModule

output = OutputModule(config)

# 自定义 DOCX 样式
output.generate_docx(document, output_path)

# 自定义 PDF 样式
output.generate_pdf(document, image_paths, output_path)

# 自定义 JSON 结构
output.generate_json(document, output_path)

Q6: 支持哪些语言？

中文：简体中文、繁体中文
英文：完全支持
混合：中英文混合文档

Q7: 如何处理表格？

自动检测表格结构
在 DOCX 中保留表格格式
在 JSON 中包含表格单元格信息
在 PDF 中绘制表格边框

Q8: 如何处理图像？

自动检测图像区域
在 PDF 中嵌入原始图像
在 JSON 中记录图像位置
在 DOCX 中保留图像占位符

性能指标

操作	时间	内存
处理单页图片（无修复）	2-5 秒	500MB
处理单页图片（4x 修复）	5-10 秒	1.5GB
处理 100 页 PDF	5-10 分钟	2GB
生成 DOCX	< 1 秒	100MB
生成 PDF	1-2 秒	200MB

获取帮助

文档：查看 docs/ 目录
示例：查看 examples/ 目录
问题：提交 GitHub Issue
讨论：参与 GitHub Discussions

许可证

MIT License

最后更新: 2026-05-21

FilesExpand file tree

USER_GUIDE.md

Latest commit

History

USER_GUIDE.md

File metadata and controls

OCR Agent 使用文档

目录

项目概述

安装指南

系统要求

安装步骤

1. 克隆项目

2. 创建虚拟环境

3. 安装依赖

4. 验证安装

快速开始

处理单张图片

处理 PDF 文件

处理整个目录

启动 Web 服务

功能说明

1. 图像预处理

2. OCR 识别

3. 图片修复

低分辨率增强

混合去噪

4. 版面分析

5. 质量评估

6. 自动纠错

命令行工具

处理命令

服务命令

Python API

基本使用

处理 PDF

批量处理

访问 OCR 结果

Web API

启动服务

API 端点

1. 上传处理

2. 查询状态

3. 下载结果

4. 删除任务

5. 健康检查

配置说明

配置文件

Python 配置

输出格式

DOCX 格式

PDF 格式

JSON 格式

TXT 格式

常见问题

Q1: 如何提高 OCR 准确率？

Q2: 处理速度太慢怎么办？

Q3: 内存占用过高怎么办？

Q4: 如何处理特殊格式的文档？

Q5: 如何自定义输出格式？

Q6: 支持哪些语言？

Q7: 如何处理表格？

Q8: 如何处理图像？

性能指标

获取帮助

许可证