OCR/README.md

Tool_OCR

智能文檔 OCR 處理系統，支援 PDF/圖片識別、版面分析、表格提取及翻譯功能。

功能特點

• 多格式支援：PDF、PNG、JPG、BMP、TIFF、DOC/DOCX、PPT/PPTX
• 版面保留 OCR：使用 PP-StructureV3 進行版面分析，保留原始文檔結構
• 表格識別：自動識別表格結構並提取內容
• 多語言支援：中文（簡/繁）、英文、日文、韓文
• 翻譯功能：整合 DIFY API 進行文檔翻譯
• 批次處理：支援多檔案同時上傳處理
• 多種匯出格式：TXT、JSON、Markdown、Excel、PDF

系統需求

• Python 3.10+
• Node.js 18+
• MySQL 8.0+
• CUDA 11.8+（GPU 加速，可選）

快速開始

1. 環境設置

# 執行開發環境設置腳本
./setup_dev_env.sh

此腳本會自動：

• 檢測 GPU 並安裝對應的 PyTorch/PaddlePaddle
• 建立 Python 虛擬環境並安裝依賴
• 安裝 Node.js 及前端依賴
• 執行資料庫遷移

2. 配置環境變數

# 複製範本
cp .env.example .env.local

# 編輯配置
nano .env.local

必要配置項：

• MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE
• SECRET_KEY（生產環境請使用隨機字串）
• DIFY_BASE_URL、DIFY_API_KEY（翻譯功能）

3. 啟動服務

開發環境：

./start.sh              # 啟動全部服務
./start.sh backend      # 只啟動後端
./start.sh frontend     # 只啟動前端
./start.sh --stop       # 停止服務
./start.sh --status     # 查看狀態

生產環境：

./start-prod.sh         # 啟動全部服務（多 worker）
./start-prod.sh --stop  # 停止服務

4. 存取服務

• 前端介面：http://localhost:5173（開發）/ http://localhost:12010（生產）
• API 文件：http://localhost:8000/docs
• 健康檢查：http://localhost:8000/health

專案結構

Tool_OCR/
├── backend/                 # 後端 FastAPI 應用
│   ├── app/
│   │   ├── api/            # API 路由
│   │   ├── core/           # 核心配置
│   │   ├── models/         # 資料模型
│   │   ├── schemas/        # Pydantic schemas
│   │   └── services/       # 業務邏輯
│   ├── tests/              # 測試檔案
│   └── alembic/            # 資料庫遷移
├── frontend/               # 前端 React 應用
│   ├── src/
│   │   ├── components/     # React 元件
│   │   ├── pages/          # 頁面元件
│   │   ├── services/       # API 服務
│   │   └── i18n/           # 國際化
│   └── public/             # 靜態資源
├── .env.example            # 環境變數範本
├── start.sh                # 開發環境啟動腳本
├── start-prod.sh           # 生產環境啟動腳本
└── setup_dev_env.sh        # 開發環境設置腳本

環境變數說明

變數	說明	預設值
BACKEND_PORT	後端服務埠號	8000
FRONTEND_PORT	前端服務埠號	5173（開發）/ 12010（生產）
MYSQL_*	資料庫連線設定	-
SECRET_KEY	JWT 簽名金鑰	-
DIFY_BASE_URL	DIFY API 位址	-
DIFY_API_KEY	DIFY API 金鑰	-
LOG_LEVEL	日誌等級	INFO

完整配置請參考 .env.example。

API 文件

啟動後端服務後，存取 http://localhost:8000/docs 查看 Swagger API 文件。

主要端點：

• POST /api/v2/upload/ - 上傳檔案
• POST /api/v2/tasks/{task_id}/start - 開始處理
• GET /api/v2/tasks/{task_id} - 查詢任務狀態
• GET /api/v2/tasks/{task_id}/download/{format} - 下載結果

開發指南

後端開發

# 啟動虛擬環境
source venv/bin/activate

# 執行測試
cd backend
pytest tests/ -v

# 執行資料庫遷移
alembic upgrade head

# 新增遷移
alembic revision --autogenerate -m "description"

前端開發

cd frontend

# 開發模式
npm run dev

# 建置
npm run build

# 型別檢查
npx tsc --noEmit

授權

私有專案，僅供內部使用。