RapidOCR OCR Docker 部署避坑指南亲测 3 个致命问题与完整调优清单【免费下载链接】RapidOCR Awesome OCR multiple programing languages toolkits based on ONNX Runtime, OpenVINO, MNN, PaddlePaddle, TensorRT and PyTorch.项目地址: https://gitcode.com/GitHub_Trending/ra/RapidOCRRapidOCR OCR 识别 API 容器化后我踩了三个坑内存上涨、依赖缺失、启动失败。本文按排障时间顺序复盘附可直接套用的部署清单。RapidOCR Docker 部署前如何检查环境排障前先锁定基线我遇到的不符合预期基本都源于下表没对齐。检查项基线值检查方式rapidocr_api 版本≥0.1.10.0.9 修复依赖0.1.1 优化启动pip show rapidocr_apiPython3.10仓库基础镜像为 python:3.10-slimpython -VDocker / Compose20.10 / Compose v2docker version资源预算≥1 核、4GB 内存端口 9003 空闲部署前规划模型缓存默认首次运行自动下载单模型数十 MB预留磁盘RapidOCR API 容器排障实录从内存泄漏到导入报错容器内存悄悄上涨、CPU 单核打满先怀疑 uvicorn 的 reload现象。 同一镜像在包安装目录下运行内存平稳换到别的目录后一小时内内存上涨数百 MB单核 CPU 打满容器最终被内核强杀OOM即内存耗尽。根因。我一开始怀疑是模型反复加载排查后确认是 uvicorn 的 reload 参数工作目录不在安装目录时watcher 持续重扫并拉起常驻进程内存只涨不降。解法。两条路① 把服务跑在 rapidocr_api 安装目录下② 升级到 0.1.1启动方式已优化。⚠️ 旧版本不要随意改 working_dir。验证。docker stats rapidocr --no-stream连续采样三次内存曲线应走平CPU 回落到个位数。python-multipart 依赖缺失一行命令补齐现象。服务能起但上传图片接口报 500日志指向缺少 multipart 解析依赖。根因。早期包版本依赖声明不完整不是环境问题。解法。0.0.9 已修复老版本补一句pip install python-multipart即可。验证。重传样例图响应返回识别结果日志不再出现 missing dependency。Could not import module apiASGI 入口路径写错现象。启动时 uvicorn 报Error loading ASGI app. Could not import module api进程立刻退出。ASGI异步服务器接口是 Web 服务器与应用间的协议这里找不到的是应用入口。根因。入口写成api:app而安装包真实模块路径是rapidocr_api.api。解法。入口改为rapidocr_api.api:app0.0.9 已内置修复。验证。docker logs出现启动成功日志9003 默认端口处于监听服务不再退出。RapidOCR Docker 部署清单Dockerfile 与资源限制一表核对项配置说明基础镜像python:3.10-slim与仓库官方基础一致依赖装 rapidocr_apiOpenCV 换成 headless 版headless 无 GUI 组件省体积、避开缺显示库报错端口-p 9003:9003默认端口 9003CPU--cpus.9单核级容器场景内存--memory4g --memory-swap4g防 OOM 失控重启--restart always配合资源限制使用模型-v挂载 det_model_path/rec_model_path环境变量可选headless 替换仅无头环境报缺库时需要pip uninstall -y opencv-python pip install --no-cache-dir opencv-python-headless作用是卸掉带 GUI 依赖的 OpenCV、装上精简版我实测最终镜像能瘦不少。最小 DockerfileFROM python:3.10-slim RUN pip install --no-cache-dir rapidocr_api \ pip uninstall -y opencv-python \ pip install --no-cache-dir opencv-python-headless EXPOSE 9003 CMD [rapidocr_api]部署顺序docker build -t rapidocr .构建镜像带资源限制运行容器见下方命令可选追加模型挂载与环境变量用下一节的三步验证健康docker run -d --name rapidocr --restart always \ --cpus.9 --memory4g --memory-swap4g \ -p 9003:9003 rapidocr想用自己的模型追加挂载与环境变量即可。注意 PaddleOCR 官方工具转换的模型不带字典建议通过 RapidAI 转换工具获取完整模型docker run -d --name rapidocr -p 9003:9003 \ -v /opt/models:/models \ -e det_model_path/models/ch_PP-OCRv3_det_infer.onnx \ -e rec_model_path/models/ch_PP-OCRv3_rec_infer.onnx \ rapidocrRapidOCR OCR 服务验证与调优健康检查与报错速查健康检查三步docker logs rapidocr无报错调用一次 API 返回 JSONdocker stats --no-stream内存平稳。✅ 三步全过才算真正可用。报错速查表报错大概率原因处理Could not import module apiASGI 入口路径错改rapidocr_api.api:app或升级 0.0.9No module named multipart依赖声明不全pip install python-multipart或升级 0.0.9OOMKilled / Exit 137无内存上限 reload 常驻加资源限制 升级 0.1.1libGL.so.1 找不到非 headless OpenCV替换 opencv-python-headless模型每次重新下载开发镜像未挂载模型缓存卷确认 rapidocr-models 卷见 docker/README.md进阶调优小文字识别走三步裁出文字区域 → 超分辨率放大ESRGAN 等→ 再识别适合截图、漫画、电影内嵌字幕场景。线程数python/rapidocr/config.yaml 中intra_op_num_threads默认 -1自动取全部核容器限到 0.9 核时显式设为 1避免线程超额争抢。引擎与开发镜像仓库在 docker/ 提供 onnxruntime-cpu、paddle、openvino 等各引擎开发镜像只跑 CPU 服务选 onnxruntime-cpu 即可。收尾。三个坑本质是同一课先锁版本与资源基线再谈调优。下一步值得把健康检查与资源限制写进 CI让容器不用跑一段时间来证明稳定。【免费下载链接】RapidOCR Awesome OCR multiple programing languages toolkits based on ONNX Runtime, OpenVINO, MNN, PaddlePaddle, TensorRT and PyTorch.项目地址: https://gitcode.com/GitHub_Trending/ra/RapidOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考