适用场景与安装思路
PaddleOCR 是广泛使用的开源 OCR 工具，适用于票据识别、表格文字提取、证件字段解析、文档数字化、工业质检读码等场景。相较于直接安装预编译包，源码编译更适合三类用户：一是需要在特定系统或硬件上运行；二是希望开启更细粒度的性能优化参数；三是需要修改源码、接入自研模型或定制推理流程。
源码编译的核心思路比较直接：先准备好 Python、编译器、PaddlePaddle 运行环境，然后获取 PaddleOCR 源码，安装依赖，最后进行功能验证和性能调参。实际部署时，建议先在测试环境完成验证，确认识别效果、速度、显存或内存占用符合预期后，再迁移到生产环境。
环境准备：版本匹配最关键
推荐使用 Linux 服务器或主流桌面系统进行安装，Python 建议选择 3.8 至 3.10 之间的稳定版本。若使用 GPU，需要提前确认显卡驱动、CUDA、cuDNN 与 PaddlePaddle 版本相互匹配；若仅使用 CPU，则重点关注编译器、OpenCV、MKL 或 OpenBLAS 等基础依赖。
建议新建独立虚拟环境，避免与其他 AI 项目依赖冲突。可使用 conda 创建环境：conda create -n paddleocr python=3.9，然后执行 conda activate paddleocr。系统侧建议安装 git、gcc/g++、cmake、make、libglib2.0、libgl1 等组件。Ubuntu 系统可执行 apt update 后安装相关依赖；其他系统需按对应包管理方式处理。
安装 PaddlePaddle 时要先确定运行方式。CPU 环境可安装 CPU 版 PaddlePaddle；GPU 环境需到 PaddlePaddle 官方安装页面选择与 CUDA 对应的命令。安装完成后可用 python -c "import paddle; print(paddle.utils.run_check())" 检查基础环境是否可用。若此处报错，不建议继续安装 PaddleOCR，应先解决底层运行环境问题。
获取 PaddleOCR 源码并安装依赖
进入计划存放项目的目录后，执行 git clone 获取 PaddleOCR 源码，再进入项目目录。为了保证教程可复现，建议优先选择稳定发布分支或指定版本标签，而不是直接使用最新主分支。最新代码功能多，但依赖变动也更频繁。
进入源码目录后，执行 pip install -r requirements.txt 安装依赖。若网络环境不稳定，可配置可信的软件源镜像，但要确保来源可靠。安装过程中如果出现 PyMuPDF、opencv-python、shapely、lmdb 等依赖构建失败，通常与 Python 版本、系统库缺失或编译工具不完整有关，可先升级 pip、setuptools、wheel，再补齐系统依赖。
完成依赖安装后，可执行 python -m pip list 检查 paddlepaddle、opencv-python、numpy、Pillow 等核心包是否存在。注意 numpy 版本过高或过低都可能引起兼容问题，若出现导入异常，可按 PaddleOCR 当前版本的依赖约束回退到推荐版本。
源码方式运行与本地验证
PaddleOCR 源码项目通常不需要像传统 C++ 项目那样完整编译才能运行，Python 侧可直接调用源码。但如果涉及 Paddle Inference、C++ 推理或自定义算子，则需要按官方说明编译对应模块。普通用户先完成 Python 推理验证即可。
可准备一张包含清晰文字的测试图片，放入项目目录，例如 test.jpg。执行推理命令时，常用参数包括 det_model_dir、rec_model_dir、cls_model_dir、image_dir、use_angle_cls、use_gpu、lang 等。若使用官方预训练模型，首次运行可能需要下载模型文件；生产部署建议提前下载并固定模型目录，避免运行时受网络状态影响。
一个常见验证方式是运行 tools/infer/predict_system.py，指定检测、识别和方向分类模型路径。如果识别结果能正常输出文本、置信度和坐标，说明基础安装成功。若只需要识别单行文本，可单独测试识别模型；若图片中存在倾斜文字，可开启方向分类，但会增加少量耗时。
性能优化参数：速度与精度要平衡
性能优化通常从四个方向入手：模型选择、输入尺寸、推理后端、批处理策略。轻量模型速度快、资源占用低，适合高并发和边缘设备；通用模型精度更稳，适合复杂文档和多字体场景。不要只看单张图片的速度，应结合真实图片尺寸、文字密度和并发量测试。
常用优化参数包括 use_gpu、use_tensorrt、precision、enable_mkldnn、cpu_threads、rec_batch_num、det_limit_side_len、det_db_thresh、det_db_box_thresh、det_db_unclip_ratio。GPU 环境下可开启 use_gpu，并在兼容时测试 use_tensorrt；precision 可尝试 fp32、fp16，若使用 fp16 需确认硬件支持且结果稳定。CPU 环境下可开启 enable_mkldnn，并根据机器核心数设置 cpu_threads，例如 4、8 或 16，不宜盲目拉满。
det_limit_side_len 会影响检测阶段输入图像的最长边，数值越大越容易保留细节，但耗时和显存占用也会上升。文档类图片可从 960、1216、1536 逐档测试；小票、标签、屏幕截图等场景可适当降低。rec_batch_num 控制识别阶段批量大小，GPU 上可适当增大，CPU 上过大反而可能拖慢。det_db_thresh 与 det_db_box_thresh 影响文本框筛选，漏检较多时可适当降低，误检较多时可适当提高。
实测调参建议
如果目标是“更快”，优先选择轻量检测模型和轻量识别模型，关闭不必要的方向分类，降低 det_limit_side_len，CPU 环境开启 MKL-DNN，GPU 环境测试半精度推理。如果目标是“更准”，优先使用较大的通用模型，保留方向分类，提高输入尺寸，并对低质量图片增加预处理，如裁边、去噪、提高对比度。
建议建立一组固定测试集，至少包含清晰图、模糊图、倾斜图、强反光图、长文本图和密集表格图。每次只修改一个参数，记录平均耗时、失败样例、识别准确率和资源占用。没有测试集的调参很容易产生错觉：某个参数在单张图上变快，并不代表整体业务收益更好。
常见问题与处理方法
问题一：import paddle 报错。通常是 PaddlePaddle 与 Python、CUDA 或系统环境不匹配。先确认 Python 版本，再重新安装对应版本的 PaddlePaddle。GPU 用户还要检查驱动与 CUDA 是否可被正确识别。
问题二：opencv 相关错误，例如缺少 libGL。可安装系统图形依赖，或在无界面服务器中改用 opencv-python-headless。若项目不需要显示图片，headless 版本更简洁。
问题三：识别中文效果差。需要确认使用的是中文识别模型，并检查字典文件是否匹配。模型、字典、配置不一致时，可能出现乱码、漏字或置信度异常。
问题四：GPU 显存不足。可降低 det_limit_side_len、减小 rec_batch_num、换用轻量模型，或分批处理大图。不要为了单次吞吐盲目增大批量，稳定性通常比峰值速度更重要。
问题五：结果框很多但文字不准。可能是检测阈值过低、图片噪声过多或识别模型不适配。可先提高 det_db_box_thresh，再对图片进行裁剪和增强，必要时使用业务数据微调模型。
安全边界与部署注意事项
OCR 常处理合同、证件、票据、内部资料等敏感图片，部署时要明确数据流向。若数据不能外传，应采用本地化部署，关闭非必要日志，避免把原图、识别结果和调试信息长期保存在公共目录。接口层要限制上传格式、文件大小和并发频率，防止异常文件拖垮服务。
模型文件和依赖包应来自官方仓库或可信渠道，不建议运行来源不明的安装脚本。生产环境要固定版本号，记录 Python、PaddlePaddle、PaddleOCR、CUDA、驱动和模型文件版本，方便回滚。升级前先在测试环境对同一批样例做对比，确认速度和准确率没有明显退化。
结语：先跑通，再优化，再固化
PaddleOCR 源码编译安装的关键不是命令本身，而是版本匹配、模型选择和参数验证。普通场景可先用 Python 源码方式快速跑通；对性能有要求时，再逐步开启 MKL-DNN、GPU、TensorRT、半精度和批处理等优化。最终部署前，应把环境、模型、参数和测试结果整理成固定方案，减少后续维护成本。
