PicAnalysis/OCR_SETUP_GUIDE.md

PicAnalysis OCR 配置指南

当前 OCR 状态

Provider	类型	状态	配置说明
Tesseract.js	本地	✅ 已安装	默认使用，无需配置
RapidOCR	本地	✅ 已部署	端口 13058，快速准确
Baidu OCR	云端	⚠️ 需配置	需要 API Key
PaddleOCR	本地	❌ 镜像问题	protobuf 兼容性问题

---

1. Tesseract.js (默认，已启用)

特点

• ✅ 内置在 Docker 镜像中，无需额外配置
• ✅ 支持中英文识别
• ⚠️ 速度较慢
• ⚠️ 准确率一般

配置

无需任何配置，系统默认使用 Tesseract.js。

优化建议

如果 Tesseract.js 识别效果不理想，建议配置 RapidOCR 或 Baidu OCR。

---

2. RapidOCR (推荐 - 快速准确)

特点

• ✅ 速度快
• ✅ 准确率高
• ✅ 本地部署，隐私安全
• ✅ 已集成到 Docker Compose

当前部署状态

RapidOCR 已集成到项目的 Docker Compose 配置中：

• 容器名: picanalysis-rapidocr
• 内部端口: 9004
• 外部端口: 13058
• 健康检查: 自动启动和重启

Docker Compose 部署 (已配置)

在 docker-compose.yml 中已包含：

rapidocr:
  image: volador/rapidocr:latest
  container_name: picanalysis-rapidocr
  restart: unless-stopped
  ports:
    - "13058:9004"
  networks:
    - picanalysis-network

后端环境变量自动配置：

RAPIDOCR_API_URL="http://rapidocr:9004"

启动服务

# 启动 RapidOCR 服务
docker compose up -d rapidocr

# 查看日志
docker compose logs -f rapidocr

# 测试服务
curl http://localhost:13058
# 应返回: {"message":"Welcome to RapidOCR Server!"}

使用方式

1. 自动选择: 在设置页面选择 "RapidOCR"
2. 环境变量: 设置 OCR_PROVIDER=rapidocr
3. API 调用: 后端自动使用 http://rapidocr:9004

---

3. Baidu OCR (云端 - 最准确)

特点

• ✅ 准确率最高
• ✅ 无需本地部署
• ⚠️ 需要申请 API Key
• ⚠️ 有调用限制（免费额度）

申请步骤

1. 访问 百度智能云 OCR
2. 注册/登录百度账号
3. 创建 OCR 应用，获取：
   • API Key
   • Secret Key
4. 在 .env 中配置：

BAIDU_OCR_API_KEY="your_api_key"
BAIDU_OCR_SECRET_KEY="your_secret_key"
OCR_PROVIDER="baidu"

免费额度

• 每天 500 次免费调用
• 超过后按次计费

---

4. PaddleOCR (暂时不可用)

当前状态

❌ Docker 镜像存在 protobuf 兼容性问题，暂时无法使用。

问题描述

常见的 PaddleOCR Docker 镜像（如 987846/paddleocr）使用了旧版本的 protobuf，与当前环境不兼容，会导致服务无法启动。

替代方案

建议使用以下替代方案：

• RapidOCR ⭐ - 同样基于 PaddleOCR 引擎，但提供稳定的 HTTP API (已集成)
• Baidu OCR - 云端调用，准确率高，有免费额度
• Tesseract.js - 本地轻量级方案，无需额外部署

如果需要使用 PaddleOCR

您可以：

1. 寻找其他维护良好的 PaddleOCR Docker 镜像
2. 手动构建 PaddleOCR 服务（需要 Python 环境）
3. 使用官方 PaddleOCR 的其他部署方式

---

OCR 配置优先级

系统按以下优先级自动选择 OCR 提供商：

1. RAPIDOCR_API_URL 已配置 → 使用 RapidOCR
2. BAIDU_OCR_API_KEY 和 BAIDU_OCR_SECRET_KEY 已配置 → 使用 Baidu OCR
3. 默认 → 使用 Tesseract.js

---

测试 OCR 配置

在部署后的系统中，你可以：

1. 访问应用 → 打开 设置 页面
2. 找到 OCR 设置 部分
3. 点击不同提供商的 测试 按钮
4. 查看测试结果和响应时间

测试指标

• ✅ 连接成功 - OCR 服务可用
• ❌ 服务不可用 - OCR 服务无法连接

---

故障排查

Tesseract.js 测试失败

问题: "Unexpected end of JSON input"

原因: Tesseract.js 是可选依赖，可能未正确安装

解决方案:

# 检查后端日志
docker compose logs backend | grep tesseract

# 如果看到模块未找到错误，重新构建镜像
docker compose down
docker compose up -d --build

RapidOCR 测试失败

问题: "服务不可用"

原因: RapidOCR 服务未运行或 URL 配置错误

解决方案:

# 1. 检查 RapidOCR 容器状态
docker compose ps rapidocr

# 2. 检查 RapidOCR 日志
docker compose logs rapidocr

# 3. 测试 RapidOCR 连接
curl http://localhost:13058
# 应返回: {"message":"Welcome to RapidOCR Server!"}

# 4. 如果服务未运行，启动它
docker compose up -d rapidocr

图片上传后无法显示

问题: "图片文件不存在"

原因: 静态文件路径配置问题

解决方案:

# 检查 uploads 目录权限
docker compose exec backend ls -la /app/uploads

# 检查静态文件访问
curl -I http://localhost:13056/uploads/test.jpg

# 重新构建后端（已修复路径问题）
docker compose up -d --build backend

---

生产环境推荐配置

推荐方案 1: RapidOCR (本地快速)

OCR_PROVIDER="rapidocr"
RAPIDOCR_API_URL="http://rapidocr:8080"

优点: 快速、准确、免费、隐私安全

推荐方案 2: Baidu OCR (云端准确)

OCR_PROVIDER="baidu"
BAIDU_OCR_API_KEY="your_key"
BAIDU_OCR_SECRET_KEY="your_secret"

优点: 最准确、无需维护、有免费额度

兜底方案: Tesseract.js

OCR_PROVIDER="tesseract"

优点: 无需配置、内置支持

---

常见问题 FAQ

Q: 为什么不建议使用 PaddleOCR？

A: PaddleOCR 需要 Python 环境，与 Node.js 集成复杂。建议使用 RapidOCR（基于相同技术栈，提供 HTTP API）。

Q: 如何切换 OCR 提供商？

A:

1. 修改 .env 文件中的 OCR_PROVIDER
2. 重启后端服务: docker compose restart backend
3. 或在设置页面动态选择

Q: 可以同时使用多个 OCR 提供商吗？

A: 当前版本使用单一提供商。可以在设置页面手动切换。

Q: OCR 识别不准确怎么办？

A:

1. 尝试使用 RapidOCR 或 Baidu OCR
2. 确保上传的图片清晰度足够
3. 尝试调整图片对比度和亮度