egg/OCR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6452797abe7c045d52a0d56886eae1d8f1792363
OCR/openspec/changes/add-gpu-acceleration-support/tasks.md
egg 6452797abe feat: add GPU acceleration support OpenSpec proposal 
新增 GPU 加速支援的 OpenSpec 變更提案

主要內容：
- 在環境建置腳本中加入 GPU 偵測功能
- 自動安裝對應 CUDA 版本的 PaddlePaddle GPU 套件
- 在 OCR 處理程式中加入 GPU 可用性偵測
- 自動啟用 GPU 加速（可用時）或使用 CPU（不可用時）
- 支援強制 CPU 模式選項
- 加入 GPU 狀態報告到健康檢查 API

變更範圍：
- 新增 capability: environment-setup (環境設置)
- 修改 capability: ocr-processing (加入 GPU 支援)

實作任務包含：
1. 環境設置腳本增強 (GPU 偵測、CUDA 安裝)
2. 配置更新 (GPU 相關環境變數)
3. OCR 服務 GPU 整合 (自動偵測、記憶體管理)
4. 健康檢查與監控 (GPU 狀態報告)
5. 文檔更新
6. 測試與效能評估
7. 錯誤處理與邊界情況

預期效果：
- GPU 系統: 3-10x OCR 處理速度提升
- CPU 系統: 無影響，向後相容
- 自動硬體偵測與優化配置

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-14 07:34:06 +08:00

3.9 KiB
Raw Blame History

Implementation Tasks

1. Environment Setup Enhancement

  • 1.1 Add GPU detection function in setup_dev_env.sh
    • Detect NVIDIA GPU using nvidia-smi or lspci
    • Detect CUDA version if GPU is available
    • Output GPU detection results to user
  • 1.2 Add conditional CUDA package installation
    • Install paddlepaddle-gpu with matching CUDA version when GPU detected
    • Install paddlepaddle (CPU-only) when no GPU detected
    • Handle different CUDA versions (11.2, 11.6, 11.7, 12.0, etc.)
  • 1.3 Add GPU verification step after installation
    • Test PaddlePaddle GPU availability
    • Report GPU status and CUDA version to user
    • Provide fallback instructions if GPU setup fails

2. Configuration Updates

  • 2.1 Add GPU configuration to .env.local
    • Add FORCE_CPU_MODE option (default: false)
    • Add CUDA_VERSION for manual override
    • Add GPU_MEMORY_FRACTION for memory allocation control
  • 2.2 Update backend configuration
    • Add GPU settings to backend/app/core/config.py
    • Load GPU-related environment variables
    • Add validation for GPU configuration values

3. OCR Service GPU Integration

  • 3.1 Add GPU detection in OCR service initialization
    • Create GPU availability check function
    • Detect available GPU devices
    • Log GPU status (available/unavailable, device name, memory)
  • 3.2 Implement automatic GPU/CPU mode selection
    • Enable GPU mode in PaddleOCR when GPU is available
    • Fall back to CPU mode when GPU is unavailable or forced
    • Set appropriate use_gpu parameter for PaddleOCR initialization
  • 3.3 Add GPU memory management
    • Set GPU memory fraction to prevent OOM errors
    • Adjust batch size based on GPU memory availability
    • Handle GPU memory allocation failures gracefully
  • 3.4 Update backend/app/services/ocr_service.py
    • Modify PaddleOCR initialization with GPU parameters
    • Add GPU status logging
    • Add error handling for GPU-related issues

4. Health Check and Monitoring

  • 4.1 Add GPU status to health check endpoint
    • Report GPU availability (true/false)
    • Report GPU device name and compute capability
    • Report CUDA version
    • Report current GPU memory usage
  • 4.2 Update backend/app/api/v1/endpoints/health.py
    • Add GPU status fields to health check response
    • Handle cases where GPU detection fails

5. Documentation Updates

  • 5.1 Update README.md
    • Add GPU requirements section
    • Document GPU detection and setup process
    • Add troubleshooting for GPU issues
  • 5.2 Update openspec/project.md
    • Add GPU hardware recommendations
    • Document CUDA version compatibility
    • Add GPU-specific configuration options
  • 5.3 Create GPU setup guide
    • Document NVIDIA driver installation for WSL
    • Document CUDA toolkit installation
    • Provide GPU verification steps

6. Testing

  • 6.1 Test GPU detection on GPU-enabled system
    • Verify correct CUDA version detection
    • Verify correct PaddlePaddle GPU installation
    • Verify OCR processing uses GPU
  • 6.2 Test CPU fallback on non-GPU system
    • Verify CPU-only installation
    • Verify OCR processing works without GPU
    • Verify no errors or warnings about missing GPU
  • 6.3 Test FORCE_CPU_MODE override
    • Verify GPU is ignored when FORCE_CPU_MODE=true
    • Verify CPU processing works on GPU-enabled system
  • 6.4 Performance benchmarking
    • Measure OCR processing time with GPU
    • Measure OCR processing time with CPU
    • Document performance improvements

7. Error Handling and Edge Cases

  • 7.1 Handle GPU out-of-memory errors
    • Catch CUDA OOM exceptions
    • Automatically fall back to CPU mode
    • Log warning message to user
  • 7.2 Handle CUDA version mismatch
    • Detect PaddlePaddle/CUDA compatibility issues
    • Provide clear error messages
    • Suggest correct CUDA version installation
  • 7.3 Handle missing NVIDIA drivers
    • Detect when GPU hardware exists but drivers are missing
    • Provide installation instructions
    • Fall back to CPU mode gracefully