PaddleOCR 安装和使用指南

快速开始

1. 安装依赖

Windows 系统

# 1. 安装 Python 包
pip install paddlepaddle paddleocr pdf2image pillow

# 2. 安装 Poppler (PDF 转图片需要)
# 下载地址: https://github.com/oschwartz10612/poppler-windows/releases
# 下载 poppler-xx.xx.x_x64.zip
# 解压到 C:\Program Files\poppler
# 将 C:\Program Files\poppler\Library\bin 添加到系统 PATH

# 或者使用 Chocolatey 安装:
choco install poppler

Linux 系统

# 1. 安装 Python 包
pip install paddlepaddle paddleocr pdf2image pillow

# 2. 安装 Poppler
# Ubuntu/Debian:
sudo apt-get install poppler-utils

# CentOS/RHEL:
sudo yum install poppler-utils

macOS 系统

# 1. 安装 Python 包
pip install paddlepaddle paddleocr pdf2image pillow

# 2. 安装 Poppler
brew install poppler

2. 使用脚本

基本用法

# 处理 PDF 文件（自动生成知识库 ID）
python scripts/reprocess_pdf_with_paddleocr.py "path/to/document.pdf"

# 指定知识库 ID
python scripts/reprocess_pdf_with_paddleocr.py "path/to/document.pdf" --kb-id f7cdefb77b24

高级选项

# 高分辨率识别（更慢但更准确）
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --dpi 400

# 调整分块大小
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --chunk-size 1200 --overlap 150

# 日文文档识别
python scripts/reprocess_pdf_with_paddleocr.py japanese_book.pdf --lang japan

# CPU 模式（无 GPU）
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --no-gpu

3. 完整工作流

# Step 1: OCR 识别 PDF
python scripts/reprocess_pdf_with_paddleocr.py "知日·日本茶道完全入门.pdf" --kb-id f7cdefb77b24

# Step 2: 验证质量
python scripts/check_kb_quality.py

# Step 3: 生成向量（如果质量达标）
python scripts/regenerate_vectors.py f7cdefb77b24

# Step 4: 在 knowledge_bases/experts/index.json 中启用专家
# 设置 "enabled": true

# Step 5: 在 knowledge_bases/permissions.json 中启用权限
# 设置 "enabled": true

# Step 6: 重启服务
docker-compose restart mbe-api

# Step 7: 测试专家回答
# 访问 https://mbe.hi-maker.com/ 测试

参数说明

DPI 选择建议

• 200 DPI: 快速识别，适合文本清晰的文档
• 300 DPI: 推荐，平衡速度和质量
• 400-600 DPI: 慢速高质量，适合扫描版或模糊文档

分块大小建议

• 500-800: 适合短问答、片段检索
• 1000-1200: 推荐，适合大多数场景
• 1500-2000: 适合长文档、完整段落

支持的语言

PaddleOCR 支持 80+ 种语言：

完整列表: https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.7/doc/doc_en/multi_languages_en.md

性能优化

GPU 加速

检查 GPU 是否可用:

import paddle
print(f"GPU 可用: {paddle.is_compiled_with_cuda()}")
print(f"GPU 数量: {paddle.device.cuda.device_count()}")

配置 GPU:

# 使用特定 GPU
export CUDA_VISIBLE_DEVICES=0

# 禁用 GPU（使用 CPU）
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --no-gpu

处理速度参考

以一本 200 页的中文书为例：

常见问题

1. Poppler 未找到

错误:

PDFInfoNotInstalledError: Unable to get page count. Is poppler installed and in PATH?

解决:

• Windows: 下载 Poppler，添加到 PATH
• Linux: sudo apt-get install poppler-utils
• macOS: brew install poppler

2. 内存不足

错误:

MemoryError: Unable to allocate array

解决:

# 降低 DPI
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --dpi 200

# 或者分批处理（需要手动拆分 PDF）

3. GPU 内存不足

错误:

Out of memory error

解决:

# 使用 CPU 模式
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --no-gpu

4. 识别质量差

问题: 识别出很多乱码或错误

解决:

# 1. 提高分辨率
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --dpi 400

# 2. 确认语言设置正确
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --lang japan

# 3. 检查原始 PDF 质量
# 如果原始 PDF 是扫描版且质量很差，可能需要:
# - 使用商业 OCR (腾讯云/阿里云)
# - 寻找更高质量的 PDF 版本
# - 手动录入核心内容

5. 处理很慢

问题: 一本书要处理几个小时

解决:

# 1. 确保使用 GPU
python scripts/reprocess_pdf_with_paddleocr.py document.pdf
# 应该显示: 初始化 PaddleOCR (GPU: True, ...)

# 2. 降低分辨率
python scripts/reprocess_pdf_with_paddleocr.py document.pdf --dpi 250

# 3. 使用更快的 GPU 或云服务

输出文件说明

处理完成后会生成以下文件：

knowledge_bases/
├── f7cdefb77b24_chunks.json          # 分块数据（主文件）
├── f7cdefb77b24_chunks.json.backup_* # 原文件备份
└── f7cdefb77b24_ocr_summary.txt      # 处理摘要

chunks.json 格式

[
  {
    "id": "chunk_0",
    "text": "日本茶道的历史可以追溯到...",
    "chunk_index": 0
  },
  {
    "id": "chunk_1",
    "text": "抹茶的制作方法...",
    "chunk_index": 1
  }
]

质量对比

处理前（旧 OCR）

缅
宫
障口＂丁烹
心
传
承
千
年
的
本
茶
道

• 换行符比例: 28.0%
• 平均行长: 1.03 字符
• 质量评分: 64.5 / 100

处理后（PaddleOCR）

传承千年的日本茶道

日本茶道是一种独特的文化艺术形式，它融合了禅宗思想、
美学追求和生活哲学。茶道不仅仅是喝茶，更是一种精神修养
和审美体验。

• 换行符比例: 2.5%
• 平均行长: 45 字符
• 质量评分: 90+ / 100

批量处理

处理多个 PDF 文件：

# Windows PowerShell
Get-ChildItem *.pdf | ForEach-Object {
    python scripts/reprocess_pdf_with_paddleocr.py $_.FullName
}

# Linux/macOS
for pdf in *.pdf; do
    python scripts/reprocess_pdf_with_paddleocr.py "$pdf"
done

下一步

处理完成后：

1. ✅ 查看质量报告: knowledge_bases/{kb_id}_ocr_summary.txt
2. ✅ 验证质量: python scripts/check_kb_quality.py
3. ✅ 生成向量: python scripts/regenerate_vectors.py {kb_id}
4. ✅ 启用专家: 编辑 knowledge_bases/experts/index.json
5. ✅ 重启服务: docker-compose restart mbe-api
6. ✅ 测试回答: 在 UI 中提问相关问题

技术支持

遇到问题？

1. 查看完整文档: docs/guides/OCR_QUALITY_IMPROVEMENT_GUIDE.md
2. 检查依赖安装: pip list | grep -E "paddle|pdf2image"
3. 查看处理日志: 脚本输出详细日志
4. 提交 Issue: 附带错误信息和 PDF 样本

最后更新: 2026-02-03
维护者: AI Assistant