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` 中已包含：

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

后端环境变量自动配置：
```bash
RAPIDOCR_API_URL="http://rapidocr:9004"
```

### 启动服务

```bash
# 启动 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](https://cloud.baidu.com/product/ocr)
2. 注册/登录百度账号
3. 创建 OCR 应用，获取：
   - `API Key`
   - `Secret Key`
4. 在 `.env` 中配置：

```bash
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 是可选依赖，可能未正确安装

**解决方案**:
```bash
# 检查后端日志
docker compose logs backend | grep tesseract

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

### RapidOCR 测试失败

**问题**: "服务不可用"

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

**解决方案**:
```bash
# 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
```

### 图片上传后无法显示

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

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

**解决方案**:
```bash
# 检查 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 (本地快速)
```bash
OCR_PROVIDER="rapidocr"
RAPIDOCR_API_URL="http://rapidocr:8080"
```

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

### 推荐方案 2: Baidu OCR (云端准确)
```bash
OCR_PROVIDER="baidu"
BAIDU_OCR_API_KEY="your_key"
BAIDU_OCR_SECRET_KEY="your_secret"
```

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

### 兜底方案: Tesseract.js
```bash
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. 尝试调整图片对比度和亮度