RapidOCR+FastAPI部署实战：5分钟搭建轻量级OCR API服务

为什么我放弃了PaddleOCR，改用RapidOCR搭建API服务

做过OCR项目的同学应该都有类似的痛苦经历：PaddleOCR精度确实不错，但部署起来太重了。PaddlePaddle框架体积大、依赖多、CPU推理慢，搭一个简单的API服务要折腾半天。直到我发现了RapidOCR——一个基于PaddleOCR模型但用ONNX推理的轻量级方案，单图CPU识别只需200ms左右，打包部署干净利落。

本文不是泛泛而谈的"OCR工具推荐"，而是一份从零到生产的完整实战记录：用RapidOCR+FastAPI搭建一个支持批量识别、健康检查、日志记录的生产级OCR API服务。我会分享踩过的坑和实际性能数据，帮你避开我走过的弯路。

RapidOCR vs PaddleOCR：到底差在哪

先说结论：RapidOCR本质上是PaddleOCR的"瘦身版"。它把PaddleOCR训练好的模型转成ONNX格式，用ONNXRuntime做推理，完全抛弃了PaddlePaddle框架。

我在实际项目中做过A/B测试：同一批200张发票图片，PaddleOCR处理耗时3分12秒，RapidOCR只需1分05秒，准确率差异不到0.3%。对于大多数业务场景，这点精度换来的速度提升绝对值得。

环境准备：干净利落地装好RapidOCR

建议用虚拟环境，避免污染全局Python：

python -m venv ocr-env
ocr-envScriptsactivate  # Windows
# source ocr-env/bin/activate  # Linux/Mac

pip install rapidocr-onnxruntime fastapi uvicorn python-multipart

注意：rapidocr-onnxruntime是CPU版本，如果需要GPU加速，安装rapidocr-onnxruntime-gpu。安装完成后验证一下：

from rapidocr_onnxruntime import RapidOCR
ocr = RapidOCR()
result, elapse = ocr("test.jpg")
print(result)  # [([[x1,y1],[x2,y2],...], "识别文字", 置信度), ...]

如果能正常输出，说明环境OK。遇到报错大多是onnxruntime版本问题，指定onnxruntime==1.17.0一般能解决。

FastAPI服务搭建：从最简到生产级

最简版本：30行代码跑起来

from fastapi import FastAPI, UploadFile, File
from rapidocr_onnxruntime import RapidOCR
import numpy as np
from PIL import Image
import io

app = FastAPI(title="RapidOCR API")
ocr_engine = RapidOCR()

@app.post("/ocr")
async def recognize(file: UploadFile = File(...)):
    img_bytes = await file.read()
    img = np.array(Image.open(io.BytesIO(img_bytes)))
    result, _ = ocr_engine(img)
    texts = [item[1] for item in result] if result else []
    return {"code": 200, "data": texts}

@app.get("/health")
async def health():
    return {"status": "ok"}

启动服务：uvicorn main:app --host 0.0.0.0 --port 8000，访问http://localhost:8000/docs就能看到自动生成的Swagger文档。用curl测试：

curl -X POST "http://localhost:8000/ocr" -F "file=@invoice.jpg"

生产级版本：加上日志、限流和错误处理

最简版本能跑，但上生产还差得远。下面是我实际在用的版本核心逻辑：

from fastapi import FastAPI, UploadFile, File, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from rapidocr_onnxruntime import RapidOCR
import numpy as np
from PIL import Image
import io
import time
import logging
from collections import defaultdict

logger = logging.getLogger("ocr-api")
logging.basicConfig(level=logging.INFO)

app = FastAPI(title="RapidOCR API", version="2.0")
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"])

ocr_engine = RapidOCR()

# 简易限流：每IP每分钟最多30次
request_counts = defaultdict(list)

def rate_limit(client_ip: str):
    now = time.time()
    request_counts[client_ip] = [t for t in request_counts[client_ip] if now - t < 60]
    if len(request_counts[client_ip]) >= 30:
        raise HTTPException(429, "请求过于频繁，请稍后再试")
    request_counts[client_ip].append(now)

@app.post("/ocr")
async def recognize(file: UploadFile = File(...)):
    import asyncio
    rate_limit("default")  # 简化示例，实际应取client_ip

    if not file.content_type or not file.content_type.startswith("image/"):
        raise HTTPException(400, "仅支持图片文件")

    img_bytes = await file.read()
    if len(img_bytes) > 10 * 1024 * 1024:
        raise HTTPException(400, "图片不能超过10MB")

    start = time.time()
    try:
        img = np.array(Image.open(io.BytesIO(img_bytes)))
        result, elapse = ocr_engine(img)
        texts = []
        if result:
            for item in result:
                texts.append({
                    "text": item[1],
                    "confidence": round(float(item[2]), 4),
                    "box": item[0]
                })
        cost_ms = round((time.time() - start) * 1000, 2)
        logger.info(f"OCR done: {len(texts)} texts, {cost_ms}ms")
        return {"code": 200, "data": texts, "cost_ms": cost_ms}
    except Exception as e:
        logger.error(f"OCR error: {e}")
        raise HTTPException(500, f"识别失败: {str(e)}")

关键改进点：

• 文件类型校验：只接受image/*，防止恶意上传
• 文件大小限制：10MB上限，避免内存爆炸
• 请求限流：简单的滑动窗口限流，生产环境建议用Redis
• 详细返回：包含文本、置信度、位置框和耗时
• 异常捕获：识别失败不崩服务，返回友好错误

批量识别：一次请求处理多张图片

实际业务中，批量场景很常见（比如一次上传5张发票）。FastAPI支持多文件上传：

@app.post("/ocr/batch")
async def batch_recognize(files: list[UploadFile] = File(...)):
    if len(files) > 20:
        raise HTTPException(400, "单次最多20张图片")
    results = []
    for f in files:
        img_bytes = await f.read()
        img = np.array(Image.open(io.BytesIO(img_bytes)))
        result, _ = ocr_engine(img)
        texts = [item[1] for item in result] if result else []
        results.append({"filename": f.filename, "texts": texts})
    return {"code": 200, "data": results}

实测数据：5张发票图片批量处理，总耗时2.8秒（串行），用asyncio.gather并行可以压到1.5秒左右。不过要注意ONNXRuntime的线程安全性——建议用asyncio.to_thread把推理放到线程池，避免阻塞事件循环。

Docker部署：一行命令上线

写一个Dockerfile：

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

requirements.txt：

rapidocr-onnxruntime>=3.8
fastapi>=0.110
uvicorn>=0.29
python-multipart>=0.0.9

构建和运行：

docker build -t rapidocr-api .
docker run -d -p 8000:8000 --name ocr-service rapidocr-api

镜像大小约450MB，比PaddleOCR动辄2GB+的镜像轻量得多。启动时间不到5秒，内存占用稳定在300MB左右。

性能优化：让CPU推理飞起来

几个我实测有效的优化技巧：

• 图片预处理缩放：长边超过960px的图片先缩放再识别，速度提升40%+且精度几乎无损
• 指定识别语言：如果只需中文，初始化时RapidOCR(text_score=0.5)降低阈值可加速
• 多Worker部署：uvicorn启动2-4个worker，利用多核CPU并行处理
• 模型预热：服务启动时先跑一张测试图，避免首次请求冷启动慢

# 启动时预热
@app.on_event("startup")
async def warmup():
    import numpy as np
    dummy = np.zeros((100, 300, 3), dtype=np.uint8)
    ocr_engine(dummy)
    logger.info("Model warmup done")

我的压测数据：2个Worker，预热后单图平均耗时180ms，QPS约35（4核8G云服务器）。对大多数中小项目完全够用。

与AI Agent集成：让OCR成为自动化流水线的一环

OCR API搭好后，最值钱的用法是接入AI Agent做自动化。比如发票处理流水线：

1. 邮件附件自动下载发票图片
2. 调用OCR API提取文字
3. 大模型解析关键字段（金额、日期、公司名）
4. 自动写入财务系统

用OpenClaw等Agent框架可以快速搭建这条流水线，OCR服务就是其中一个Skill节点。这种架构的好处是：OCR服务独立部署、独立扩容，Agent层只管调度，职责清晰。

如果你也在做AI自动化的项目，可以参考AI操控电脑自动化入门和OpenClaw OCR自动化实战这两篇文章，里面有更多Agent+OCR的实战案例。

踩坑记录：这三个问题差点让我放弃

坑1：PIL读取带中文路径的图片报错

Windows下Image.open()不支持中文路径。解决方案是先用cv2.imdecode()读取：

import cv2
img_bytes = np.fromfile("中文路径.png", dtype=np.uint8)
img = cv2.imdecode(img_bytes, cv2.IMREAD_COLOR)

坑2：ONNX模型首次加载慢

首次调用RapidOCR()需要加载约150MB的ONNX模型，耗时2-5秒。一定要在服务启动时初始化，不要每次请求都new一个实例。

坑3：PNG透明通道导致识别异常

带Alpha通道的PNG图片转numpy后是4通道，RapidOCR期望3通道。预处理加一步转换：

if img.shape[2] == 4:
    img = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)

总结

RapidOCR+FastAPI的组合，是目前我见过最轻量、最干净的本地OCR API方案。5分钟搭建、450MB镜像、180ms单图延迟，对中小项目来说完全够用。相比PaddleOCR，牺牲了不到0.3%的精度，换来3-5倍的速度提升和十分之一的部署体积，这笔账怎么算都划算。

如果你正在做OCR相关的项目，尤其是需要私有化部署的场景，强烈建议试试这个方案。搭建过程中有任何问题，欢迎留言讨论。