PicAnalysis/OCR_SETUP_GUIDE.md

PicAnalysis OCR 配置指南

当前 OCR 状态

Provider	类型	状态	配置说明
Tesseract.js	本地	✅ 已安装	默认使用，无需配置
RapidOCR	本地	⚠️ 需配置	需要额外部署
Baidu OCR	云端	⚠️ 需配置	需要 API Key
PaddleOCR	本地	❌ 暂不支持	需要 Python 环境

---

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

特点

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

配置

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

优化建议

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

---

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

特点

• ✅ 速度快
• ✅ 准确率高
• ✅ 本地部署，隐私安全
• ⚠️ 需要单独部署服务

Docker 部署方式

方案 A: 使用 Docker Compose (推荐)

在 docker-compose.yml 中添加 RapidOCR 服务：

services:
  # ... 其他服务 ...

  rapidocr:
    image: xiaoshaizaiai/rapidocr:latest
    container_name: picanalysis-rapidocr
    restart: unless-stopped
    ports:
      - "8080:8080"
    networks:
      - picanalysis-network

然后更新 .env 文件：

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

方案 B: 使用外部 RapidOCR 服务

如果你已经有运行中的 RapidOCR 服务，只需要配置 URL：

# .env 文件
RAPIDOCR_API_URL="http://your-rapidocr-host:8080"
OCR_PROVIDER="rapidocr"

验证 RapidOCR

# 测试 RapidOCR 服务是否可用
curl http://localhost:8080

---

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 (暂不支持)

限制

PaddleOCR 是 Python 库，在 Node.js 环境中集成比较复杂。

替代方案

建议使用以下替代方案：

• RapidOCR - 同样使用 PaddleOCR 引擎，但提供 HTTP API
• Baidu OCR - 云端调用，准确率高
• Tesseract.js - 本地轻量级方案

---

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:8080

# 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. 尝试调整图片对比度和亮度