OCR MCP Service

# 防中断机制说明 ## 🛡️ 概述 为确保长任务处理不会中断，我们实现了多层防中断机制，确保OCR处理过程稳定可靠。 ## ✅ 已实现的防中断机制 ### 1. 自动心跳机制 ⭐⭐⭐ **实现位置**: `src/ocr_mcp_service/progress_tracker.py` **功能**: - 在长时间OCR操作期间自动启动心跳线程 - 每5秒自动发送进度更新，即使进度没有变化 - 防止客户端因长时间无响应而断开连接 **工作原理**: ```python # 启动心跳 progress_tracker.start_heartbeat() # 心跳线程每5秒发送一次进度更新 # 即使OCR引擎正在处理，也会持续发送心跳 # 操作完成后停止心跳 progress_tracker.stop_heartbeat() ``` **应用范围**: - ✅ PaddleOCR引擎 - ✅ EasyOCR引擎 - ✅ DeepSeek OCR引擎 - ✅ PaddleOCR-MCP引擎 --- ### 2. 进度更新机制 ⭐⭐⭐ **实现位置**: 所有OCR引擎的`recognize_image`方法 **功能**: - 关键阶段必须发送进度更新（10%, 20%, 50%, 80%, 100%） - 在长时间操作中定期更新进度 - 解析阶段每10%的文本块发送一次更新 **关键阶段**: 1. **10%** - 图像加载完成 2. **20%** - OCR引擎调用开始 3. **50%** - OCR处理中（如果处理时间较长） 4. **80%** - OCR完成，开始解析结果 5. **95%** - 后处理（生成分析） 6. **100%** - 处理完成 --- ### 3. 异常保护机制 ⭐⭐⭐ **实现位置**: `src/ocr_mcp_service/__main__.py` **功能**: - 全局异常处理，防止未捕获异常导致进程退出 - 区分不同类型的异常（KeyboardInterrupt, SystemExit, 普通异常） - 优雅退出，允许Cursor重新启动服务 **保护措施**: ```python try: mcp.run() except KeyboardInterrupt: # 优雅处理中断信号 except SystemExit: # 允许系统退出 except Exception as e: # 记录错误但不立即退出 # 让Cursor重新启动服务 ``` --- ### 4. 超时保护机制 ⭐⭐ **实现位置**: `src/ocr_mcp_service/tools.py` **功能**: - 动态超时：根据图片大小自动调整超时时间 - 防止任务无限期挂起 - 超时后返回明确的错误信息 **超时设置**: - 小图片（< 1MB）: 60秒 - 中等图片（1-5MB）: 120秒 - 大图片（> 5MB）: 180秒 --- ### 5. 资源清理机制 ⭐⭐ **实现位置**: 所有OCR引擎 **功能**: - 使用`try-finally`确保资源清理 - 确保心跳线程在操作完成后停止 - 清理临时文件和目录 **示例**: ```python progress_tracker.start_heartbeat() try: # OCR处理 result = engine.recognize_image(image_path) finally: # 确保心跳停止 progress_tracker.stop_heartbeat() ``` --- ## 🔄 工作流程 ### 正常处理流程 ``` 1. 开始OCR识别 ↓ 2. 启动心跳线程（每5秒发送进度） ↓ 3. 发送进度更新（10% - 图像加载） ↓ 4. 发送进度更新（20% - OCR引擎调用） ↓ 5. [心跳持续发送，保持连接活跃] ↓ 6. OCR引擎处理中... ↓ 7. 发送进度更新（80% - OCR完成） ↓ 8. 解析结果，定期发送进度 ↓ 9. 发送进度更新（95% - 后处理） ↓ 10. 发送进度更新（100% - 完成） ↓ 11. 停止心跳线程 ↓ 12. 返回结果 ``` ### 异常处理流程 ``` 1. 发生异常 ↓ 2. 记录错误日志 ↓ 3. 停止心跳线程 ↓ 4. 清理资源 ↓ 5. 返回错误信息（不中断服务） ↓ 6. 服务继续运行，等待下一个请求 ``` --- ## 📊 防中断效果 ### 连接保持 | 机制 | 频率 | 效果 | |------|------|------| | 心跳更新 | 每5秒 | 保持连接活跃 | | 进度更新 | 关键阶段 | 用户可见进度 | | 解析更新 | 每10%文本块 | 详细进度反馈 | ### 异常保护 | 异常类型 | 处理方式 | 服务状态 | |---------|---------|---------| | KeyboardInterrupt | 优雅退出 | 正常关闭 | | SystemExit | 允许退出 | 正常关闭 | | 普通异常 | 记录并继续 | 继续运行 | | OCR引擎异常 | 返回错误 | 继续运行 | --- ## 🎯 最佳实践 ### 1. 长时间操作 对于超过10秒的操作： - ✅ 必须启动心跳机制 - ✅ 必须定期发送进度更新 - ✅ 必须使用try-finally确保清理 ### 2. 错误处理 对于可能失败的操作： - ✅ 捕获所有异常 - ✅ 记录详细错误信息 - ✅ 返回用户友好的错误消息 - ✅ 不中断服务运行 ### 3. 资源管理 对于需要清理的资源： - ✅ 使用try-finally - ✅ 确保心跳线程停止 - ✅ 清理临时文件 - ✅ 释放内存资源 --- ## ⚙️ 配置 ### 心跳间隔 默认心跳间隔为5秒，可通过修改`ProgressTracker`初始化参数调整： ```python progress_tracker = ProgressTracker( on_progress=callback, heartbeat_interval=3.0 # 3秒心跳间隔（更频繁） ) ``` ### 超时设置 可通过环境变量配置超时时间： ```bash # 基础超时 export OCR_TIMEOUT=120 # 小图片超时 export SMALL_IMAGE_TIMEOUT=60 # 大图片超时 export LARGE_IMAGE_TIMEOUT=180 ``` --- ## 📝 总结 通过多层防中断机制： 1. ✅ **心跳机制** - 保持连接活跃，防止超时断开 2. ✅ **进度更新** - 用户可见的进度反馈 3. ✅ **异常保护** - 防止异常导致服务中断 4. ✅ **超时保护** - 防止任务无限期挂起 5. ✅ **资源清理** - 确保资源正确释放 这些机制确保了OCR处理过程的稳定性和可靠性，即使在处理大图片或复杂场景时也不会中断。