diff --git a/docs/FAQ.en.md b/docs/FAQ.en.md index c90bcad35c..65b3617eb8 100644 --- a/docs/FAQ.en.md +++ b/docs/FAQ.en.md @@ -5,6 +5,136 @@ hide: - toc --- +> 🎉 **Welcome to PaddleOCR FAQ!** +> This document compiles common issues and solutions from GitHub Issues and Discussions, providing reference for OCR developers. + +## 1. Installation and Environment Setup + +### 1.1 Basic Installation Issues + +#### Q: PaddleOCR installation failed with dependency conflicts + +**A**: This is a common issue that can be resolved by: +(1) Create a new virtual environment: `conda create -n paddleocr python=3.8`, then activate and install +(2) Install with specific versions: `pip install paddleocr==3.2.0 --no-deps`, then install dependencies separately +(3) If using conda, try: `conda install -c conda-forge paddleocr` + +#### Q: GPU environment configuration issues, CUDA version mismatch + +**A**: First check CUDA version: `nvidia-smi`, then install corresponding PaddlePaddle version: +- CUDA 11.8: `pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html` +- CUDA 12.0: `pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html` +Verify GPU availability: `python -c "import paddle; print(paddle.is_compiled_with_cuda())"` + +#### Q: Model download failed or slow download + +**A**: Can be resolved by: +(1) Set model download source: `os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'BOS'` (use Baidu Cloud Storage) +(2) Manual model download: directly access model links to download and extract to local directory +(3) Use local models: specify `model_dir` parameter pointing to local model path during initialization + +#### Q: How to run on Windows or Mac? + +**A**: PaddleOCR has completed adaptation to Windows and MAC systems. Two points should be noted during operation: + 1. In [Quick installation](./installation_en.md), if you do not want to install docker, you can skip the first step and start with the second step. + 2. When downloading the inference model, if wget is not installed, you can directly click the model link or copy the link address to the browser to download, then extract and place it in the corresponding directory. + +## 2. Model Usage and Configuration + +### 2.1 Model Selection + +#### Q: How to choose the right model? + +**A**: Choose based on application scenario: +- Server high accuracy: Use `PP-OCRv5_server` series, highest accuracy +- Mobile deployment: Use `PP-OCRv5_mobile` series, small model fast speed +- Real-time processing: Use `PP-OCRv5_mobile` series, fast inference speed +- Batch processing: Use `PP-OCRv5_server` series, high accuracy +- Multi-language recognition: Use `PP-OCRv5_multi_languages`, supports 37 languages + +#### Q: Local model path configuration, how to use in isolated network environment? + +**A**: Can be configured by: +(1) Use local model path: specify `model_dir` parameter during initialization +(2) Set model download source: `os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'BOS'` +(3) Manual model download: download models from official links and extract locally +(4) Example code: +```python +ocr = PaddleOCR( + det_model_dir='./models/PP-OCRv5_server_det_infer/', + rec_model_dir='./models/PP-OCRv5_server_rec_infer/', + cls_model_dir='./models/PP-OCRv5_cls_infer/', + use_angle_cls=True, + lang='ch' +) +``` + +## 3. Performance Optimization + +### 3.1 GPU Optimization + +#### Q: Slow GPU inference speed, how to optimize performance? + +**A**: Can be optimized by: +(1) Enable high-performance inference: set `enable_hpi=True`, automatically select optimal acceleration strategy +(2) Enable TensorRT acceleration: set `use_tensorrt=True`, requires CUDA 11.8+ and TensorRT 8.6+ +(3) Use half precision: set `precision="fp16"`, can significantly improve speed +(4) Adjust batch size: set appropriate `batch_size` based on GPU memory +(5) Use mobile models: use `PP-OCRv5_mobile` series when accuracy requirements are not high + +#### Q: GPU memory insufficient (CUDA out of memory) what to do? + +**A**: Can be resolved by: +(1) Reduce batch size: set `batch_size` to 1 +(2) Reduce image size: set `det_limit_side_len=640` +(3) Enable memory optimization: set `enable_memory_optim=True` +(4) Limit GPU memory usage: set `gpu_mem=200` +(5) Use mobile models: switch to `PP-OCRv5_mobile` series models + +## 4. Deployment Issues + +### 4.1 Service Deployment + +#### Q: How to deploy PaddleOCR as a web service? + +**A**: Can be deployed by: +(1) Use Flask deployment: create simple Web API service +(2) Use gunicorn deployment: `gunicorn -w 4 -b 0.0.0.0:5000 app:app` +(3) Use asynchronous processing: combine asyncio and ThreadPoolExecutor +(4) Example code: +```python +from flask import Flask, request, jsonify +from paddleocr import PaddleOCR + +app = Flask(__name__) +ocr = PaddleOCR(use_angle_cls=True, lang='ch') + +@app.route('/ocr', methods=['POST']) +def ocr_api(): + file = request.files['image'] + result = ocr.ocr(file, cls=True) + return jsonify({'result': result}) +``` + +#### Q: C++ deployment common issues and solutions? + +**A**: Common issues and solutions: +(1) Cannot find dynamic library: set `export LD_LIBRARY_PATH=/path/to/paddle/lib:$LD_LIBRARY_PATH` +(2) OpenCV version mismatch: ensure OpenCV version matches compilation time +(3) Model format issues: ensure correct inference model format +(4) Compilation issues: ensure CMake configuration is correct, use `cmake .. -DCMAKE_BUILD_TYPE=Release` + +#### Q: Service performance optimization suggestions? + +**A**: Can be optimized by: +(1) Enable high-performance inference: set `enable_hpi=True` +(2) Use batch processing: set appropriate `batch_size` +(3) Enable TensorRT: set `use_tensorrt=True` +(4) Use asynchronous processing: avoid blocking requests +(5) Load balancing: use multiple service instances + +## 5. Legacy Issues (for reference) + 1. **Prediction error: got an unexpected keyword argument 'gradient_clip'** The installed version of paddle is incorrect. Currently, this project only supports Paddle 1.7, which will be adapted to 1.8 in the near future. diff --git a/docs/FAQ.md b/docs/FAQ.md index 66cb5c72d2..d06095d221 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -275,6 +275,27 @@ export FLAGS_initial_cpu_memory_in_mb=2000 # 设置初始化内存约2G左右 （1）在快速安装时，如果不想安装docker，可跳过第一步，直接从第二步安装paddle开始。 （2）inference模型下载时，如果没有安装wget，可直接点击模型链接或将链接地址复制到浏览器进行下载，并解压放置到相应目录。 +#### Q：PaddleOCR安装失败，提示依赖冲突怎么办？ + +**A**：这是常见问题，可以通过以下方式解决： +（1）创建新的虚拟环境：`conda create -n paddleocr python=3.8`，然后激活环境安装 +（2）使用指定版本安装：`pip install paddleocr==3.2.0 --no-deps`，然后单独安装依赖 +（3）如果使用conda，可以尝试：`conda install -c conda-forge paddleocr` + +#### Q：GPU环境配置问题，CUDA版本不匹配怎么办？ + +**A**：首先检查CUDA版本：`nvidia-smi`，然后安装对应版本的PaddlePaddle： +- CUDA 11.8：`pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html` +- CUDA 12.0：`pip install paddlepaddle-gpu==3.0.0 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html` +验证GPU是否可用：`python -c "import paddle; print(paddle.is_compiled_with_cuda())"` + +#### Q：模型下载失败或下载缓慢怎么办？ + +**A**：可以通过以下方式解决： +（1）设置模型下载源：`os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'BOS'`（使用百度云存储） +（2）手动下载模型：直接访问模型链接下载并解压到本地目录 +（3）使用本地模型：在初始化时指定`model_dir`参数指向本地模型路径 + ### 2.3 数据量说明 #### Q：简单的对于精度要求不高的OCR任务，数据集需要准备多少张呢？ @@ -496,6 +517,50 @@ checkpoints：指之前训练的中间结果，例如前一次训练到了100个 检测框存在很多漏检问题，可以减小DB检测后处理的阈值参数det_db_box_thresh，防止一些检测框被过滤掉，也可以尝试设置det_db_score_mode为'slow'; 其他方法可以选择use_dilation为True，对检测输出的feature map做膨胀处理，一般情况下，会有效果改善； +#### Q: GPU推理速度慢，如何优化性能？ + +**A**：可以通过以下方式优化： +（1）启用高性能推理：设置`enable_hpi=True`，自动选择最优加速策略 +（2）启用TensorRT加速：设置`use_tensorrt=True`，需要CUDA 11.8+和TensorRT 8.6+ +（3）使用半精度：设置`precision="fp16"`，可以显著提升速度 +（4）调整批处理大小：根据显存大小设置合适的`batch_size` +（5）使用移动端模型：在精度要求不高时使用`PP-OCRv5_mobile`系列模型 + +#### Q: GPU内存不足（CUDA out of memory）怎么办？ + +**A**：可以通过以下方式解决： +（1）减小批处理大小：将`batch_size`设置为1 +（2）减小图像尺寸：设置`det_limit_side_len=640` +（3）启用内存优化：设置`enable_memory_optim=True` +（4）限制GPU内存使用：设置`gpu_mem=200` +（5）使用移动端模型：切换到`PP-OCRv5_mobile`系列模型 + +#### Q: 如何选择合适的模型？ + +**A**：根据应用场景选择： +- 服务器高精度场景：使用`PP-OCRv5_server`系列，精度最高 +- 移动端部署：使用`PP-OCRv5_mobile`系列，模型小速度快 +- 实时处理：使用`PP-OCRv5_mobile`系列，推理速度快 +- 批量处理：使用`PP-OCRv5_server`系列，精度高 +- 多语言识别：使用`PP-OCRv5_multi_languages`，支持37种语言 + +#### Q: 本地模型路径配置问题，如何在隔离网络环境下使用？ + +**A**：可以通过以下方式配置： +（1）使用本地模型路径：在初始化时指定`model_dir`参数 +（2）设置模型下载源：`os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'BOS'` +（3）手动下载模型：从官方链接下载模型并解压到本地 +（4）示例代码： +```python +ocr = PaddleOCR( + det_model_dir='./models/PP-OCRv5_server_det_infer/', + rec_model_dir='./models/PP-OCRv5_server_rec_infer/', + cls_model_dir='./models/PP-OCRv5_cls_infer/', + use_angle_cls=True, + lang='ch' +) +``` + #### Q：同一张图通用检测出21个条目，轻量级检测出26个 ，难道不是轻量级的好吗？ **A**：可以主要参考可视化效果，通用模型更倾向于检测一整行文字，轻量级可能会有一行文字被分成两段检测的情况，不是数量越多，效果就越好。 @@ -730,6 +795,44 @@ ocr_system: 检测识别串联预测 **A**: 近期PaddleOCR新增了[多进程预测控制参数](https://github.com/PaddlePaddle/PaddleOCR/blob/a312647be716776c1aac33ff939ae358a39e8188/tools/infer/utility.py#L103)，`use_mp`表示是否使用多进程，`total_process_num`表示在使用多进程时的进程数。具体使用方式请参考[文档](https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.1/doc/doc_ch/inference.md#1-%E8%B6%85%E8%BD%BB%E9%87%8F%E4%B8%AD%E6%96%87ocr%E6%A8%A1%E5%9E%8B%E6%8E%A8%E7%90%86)。 +#### Q: 如何部署PaddleOCR为Web服务？ + +**A**：可以通过以下方式部署： +（1）使用Flask部署：创建简单的Web API服务 +（2）使用gunicorn部署：`gunicorn -w 4 -b 0.0.0.0:5000 app:app` +（3）使用异步处理：结合asyncio和ThreadPoolExecutor +（4）示例代码： +```python +from flask import Flask, request, jsonify +from paddleocr import PaddleOCR + +app = Flask(__name__) +ocr = PaddleOCR(use_angle_cls=True, lang='ch') + +@app.route('/ocr', methods=['POST']) +def ocr_api(): + file = request.files['image'] + result = ocr.ocr(file, cls=True) + return jsonify({'result': result}) +``` + +#### Q: C++部署常见问题及解决方案？ + +**A**：常见问题及解决方案： +（1）找不到动态库：设置`export LD_LIBRARY_PATH=/path/to/paddle/lib:$LD_LIBRARY_PATH` +（2）OpenCV版本不匹配：确保OpenCV版本与编译时一致 +（3）模型格式问题：确保使用正确的推理模型格式 +（4）编译问题：确保CMake配置正确，使用`cmake .. -DCMAKE_BUILD_TYPE=Release` + +#### Q: 服务性能优化建议？ + +**A**：可以通过以下方式优化： +（1）启用高性能推理：设置`enable_hpi=True` +（2）使用批处理：合理设置`batch_size` +（3）启用TensorRT：设置`use_tensorrt=True` +（4）使用异步处理：避免阻塞请求 +（5）负载均衡：使用多个服务实例 + #### Q: 怎么解决paddleOCR在T4卡上有越预测越慢的情况？ **A**： diff --git a/docs/version3.x/module_usage/text_detection.md b/docs/version3.x/module_usage/text_detection.md index c67253d47a..5be4a97435 100644 --- a/docs/version3.x/module_usage/text_detection.md +++ b/docs/version3.x/module_usage/text_detection.md @@ -114,14 +114,51 @@ comments: true > ❗ 在快速开始前，请先安装 PaddleOCR 的 wheel 包，详细请参考 [安装教程](../installation.md)。 +### 3.1 环境准备 + +#### 3.1.1 基础安装 + +```bash +# 安装基础版本（仅包含文本检测功能） +pip install paddleocr + +# 安装完整版本（包含所有功能） +pip install "paddleocr[all]" +``` + +#### 3.1.2 环境验证 + +```python +# 验证安装是否成功 +import paddleocr +print(f"PaddleOCR版本: {paddleocr.__version__}") + +# 验证GPU是否可用 +import paddle +print(f"Paddle版本: {paddle.__version__}") +print(f"GPU可用: {paddle.is_compiled_with_cuda()}") +print(f"GPU数量: {paddle.device.cuda.device_count()}") +``` + +### 3.2 命令行快速体验 + 使用一行命令即可快速体验： ```bash +# 使用默认模型进行文本检测 paddleocr text_detection -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_001.png + +# 指定模型进行检测 +paddleocr text_detection -i general_ocr_001.png --model_name PP-OCRv5_server_det + +# 批量处理本地图片 +paddleocr text_detection -i ./images/ --model_name PP-OCRv5_mobile_det ``` 注：PaddleOCR 官方模型默认从 HuggingFace 获取，如运行环境访问 HuggingFace 不便，可通过环境变量修改模型源为 BOS：`PADDLE_PDX_MODEL_SOURCE="BOS"`，未来将支持更多主流模型源； +### 3.3 Python API 使用 + 您也可以将文本检测的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载[示例图片](https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_001.png)到本地。 ```python @@ -503,7 +540,85 @@ python3 tools/export_model.py -c configs/det/PP-OCRv5/PP-OCRv5_server_det.yml -o ``` 至此，二次开发完成，该静态图模型可以直接集成到 PaddleOCR 的 API 中。 -## 五、FAQ +## 五、常见问题与解决方案 + +### 5.1 性能优化问题 + +#### Q: GPU推理速度慢怎么办？ + +**A**: 可以通过以下方式优化： +（1）启用高性能推理：设置`enable_hpi=True`，自动选择最优加速策略 +（2）启用TensorRT加速：设置`use_tensorrt=True`，需要CUDA 11.8+和TensorRT 8.6+ +（3）使用半精度：设置`precision="fp16"`，可以显著提升速度 +（4）调整批处理大小：根据显存大小设置合适的`batch_size` +（5）使用移动端模型：在精度要求不高时使用`PP-OCRv5_mobile`系列模型 + +#### Q: GPU内存不足（CUDA out of memory）怎么办？ + +**A**: 可以通过以下方式解决： +（1）减小批处理大小：将`batch_size`设置为1 +（2）减小图像尺寸：设置`det_limit_side_len=640` +（3）启用内存优化：设置`enable_memory_optim=True` +（4）限制GPU内存使用：设置`gpu_mem=200` +（5）使用移动端模型：切换到`PP-OCRv5_mobile`系列模型 + +### 5.2 检测精度问题 + +#### Q: 检测框不准确或漏检怎么办？ + +**A**: 可以通过以下方式优化： +（1）调整检测参数： +```python +model = TextDetection( + model_name="PP-OCRv5_server_det", + thresh=0.3, # 降低像素阈值 + box_thresh=0.5, # 降低检测框阈值 + unclip_ratio=2.0, # 增大扩张系数 + limit_side_len=1216 # 增大图像尺寸 +) +``` +（2）使用更精确的后处理模式：设置`det_db_score_mode="slow"` +（3）启用膨胀处理：设置`use_dilation=True` + +### 5.3 模型选择建议 + +#### Q: 如何选择合适的模型？ + +**A**: 根据应用场景选择： +- 服务器高精度场景：使用`PP-OCRv5_server_det`，精度最高 +- 移动端部署：使用`PP-OCRv5_mobile_det`，模型小速度快 +- 实时处理：使用`PP-OCRv5_mobile_det`，推理速度快 +- 批量处理：使用`PP-OCRv5_server_det`，精度高 + +### 5.4 参数调优建议 + +#### Q: 如何调优检测参数？ + +**A**: 通过参数`limit_type`和`limit_side_len`来对图片的尺寸进行限制，`limit_type`可选参数为[`max`, `min`]，`limit_side_len` 为正整数，一般设置为 32 的倍数，比如 960。 -- 通过参数`limit_type`和`limit_side_len`来对图片的尺寸进行限制，`limit_type`可选参数为[`max`, `min`]，`limit_side_len` 为正整数，一般设置为 32 的倍数，比如 960。 如果输入图形分辨率不大，建议使用`limit_type=min` 和 `limit_side_len=960` 节省计算资源的同时能获得最佳检测效果。如果输入图片的分辨率比较大，而且想使用更大的分辨率预测，可以设置 `limit_side_len` 为想要的值，比如 1216。 + +#### Q: 不同场景的参数配置建议？ + +**A**: +- **高精度配置**：`limit_side_len=1216`, `thresh=0.3`, `box_thresh=0.5`, `unclip_ratio=1.5` +- **高速度配置**：`limit_side_len=640`, `thresh=0.5`, `box_thresh=0.7`, `unclip_ratio=1.2` +- **平衡配置**：`limit_side_len=960`, `thresh=0.4`, `box_thresh=0.6`, `unclip_ratio=1.5` + +### 5.5 错误处理 + +#### Q: 模型加载失败怎么办？ + +**A**: +（1）检查模型路径是否正确 +（2）确保模型文件完整（inference.pdmodel, inference.pdiparams, inference.json） +（3）设置模型下载源：`os.environ['PADDLE_PDX_MODEL_SOURCE'] = 'BOS'` +（4）使用本地模型：指定`model_dir`参数 + +#### Q: 输入数据格式错误怎么办？ + +**A**: +（1）检查图像文件是否存在 +（2）确保图像格式正确（支持PNG、JPG、JPEG） +（3）验证图像尺寸（最小10x10像素） +（4）检查图像是否为3通道格式 diff --git a/docs/version3.x/pipeline_usage/OCR.md b/docs/version3.x/pipeline_usage/OCR.md index 534d0f3d84..16fcc42492 100644 --- a/docs/version3.x/pipeline_usage/OCR.md +++ b/docs/version3.x/pipeline_usage/OCR.md @@ -656,6 +656,58 @@ devanagari_PP-OCRv3_mobile_rec_infer.tar">推理模型/ + +## 5. 常见问题与解决方案 + +### 5.1 性能优化问题 + +#### Q: GPU推理速度慢怎么办？ + +**A**: 可以通过以下方式优化： +（1）启用高性能推理：设置`enable_hpi=True`，自动选择最优加速策略 +（2）启用TensorRT加速：设置`use_tensorrt=True`，需要CUDA 11.8+和TensorRT 8.6+ +（3）使用半精度：设置`precision="fp16"`，可以显著提升速度 +（4）调整批处理大小：根据显存大小设置合适的`batch_size` +（5）使用移动端模型：在精度要求不高时使用`PP-OCRv5_mobile`系列模型 + +#### Q: GPU内存不足（CUDA out of memory）怎么办？ + +**A**: 可以通过以下方式解决： +（1）减小批处理大小：将`batch_size`设置为1 +（2）减小图像尺寸：设置`det_limit_side_len=640` +（3）启用内存优化：设置`enable_memory_optim=True` +（4）限制GPU内存使用：设置`gpu_mem=200` +（5）使用移动端模型：切换到`PP-OCRv5_mobile`系列模型 + +### 5.2 模型选择问题 + +#### Q: 如何选择合适的模型？ + +**A**: 根据应用场景选择： +- 服务器高精度场景：使用`PP-OCRv5_server`系列，精度最高 +- 移动端部署：使用`PP-OCRv5_mobile`系列，模型小速度快 +- 实时处理：使用`PP-OCRv5_mobile`系列，推理速度快 +- 批量处理：使用`PP-OCRv5_server`系列，精度高 +- 多语言识别：使用`PP-OCRv5_multi_languages`，支持37种语言 + +### 5.3 最佳实践 + +#### Q: 生产环境部署建议？ + +**A**: +（1）使用高性能推理配置 +（2）启用TensorRT加速 +（3）合理设置批处理大小 +（4）监控GPU内存使用情况 +（5）做好错误处理和日志记录 + +## 6. 总结 + +通用OCR产线是PaddleOCR的核心功能，通过合理选择模型和配置参数，可以在不同场景下获得最佳的识别效果。建议根据部署环境选择合适的模型，根据应用需求调整参数，充分利用GPU加速和批处理优化。