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 服务：

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

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

然后更新 `.env` 文件：

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

#### 方案 B: 使用外部 RapidOCR 服务

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

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

#### 验证 RapidOCR

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

---

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

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

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

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