# OCR Server 基于 FastAPI 和 PaddleOCR **PP-OCRv5** 的图片文字识别服务,支持 Windows 和 Ubuntu 22.04(CPU;GPU 需要额外安装对应的 PaddlePaddle GPU 版本)。 ## 目录结构 ```text ocr-server/ ├── config.yaml # 项目配置文件(启动前修改) ├── http/ocr-server.http # IDEA / IntelliJ HTTP Client 测试请求 ├── models/ # 可随发布包分发的 PP-OCRv5 模型(约 166 MB) │ └── official_models/ │ ├── PP-OCRv5_server_det/ │ └── PP-OCRv5_server_rec/ ├── data/uploads/ # 上传图片运行时目录 ├── src/ocr_server/ ├── scripts/download_models.py # 下载或补齐缺少的模型 └── scripts/benchmark_ocr.py # 测量当前配置的 OCR 耗时 ``` ## 模型位置和下载策略 当前已经预下载并放入项目目录: ```text models/official_models/PP-OCRv5_server_det models/official_models/PP-OCRv5_server_rec ``` 当前分发包内的模型是 PP-OCRv5 中文服务模型,总大小约 166 MB。模型文件只读使用,服务不会修改模型目录中的权重文件。 服务启动后不会立即加载模型。上传接口会立即把图片放入等待队列;第一次有工作线程开始识别时: 1. 优先检查 `model_dir/official_models/` 下的检测模型和识别模型; 2. 模型文件完整时,直接使用项目内模型,不访问网络; 3. 缺少任意模型时,只下载缺少的模型,并保存到同一个 `model_dir`; 4. 后续请求继续复用同一个进程内的 OCR 实例。 默认模型目录是项目根目录下的 `models`,可以直接修改项目根目录的 `config.yaml`: ```yaml model_dir: /opt/ocr-server/models ``` 配置文件中的路径支持绝对路径,也支持相对于项目根目录的路径。服务启动时读取一次配置,修改后需要重启服务。 也可以手动提前下载或补齐模型: ```powershell uv run python scripts/download_models.py ``` 脚本会读取 `config.yaml`,把模型下载到 `model_dir` 指定的目录。模型下载需要联网;完整分发包可以直接携带整个 `models/` 目录,从而不依赖首次启动联网。下载时不会覆盖已有完整模型目录。 ## 不同速度档位和模型选择 当前项目默认使用 PP-OCRv5 中文服务模型: ```yaml det_model_name: PP-OCRv5_server_det rec_model_name: PP-OCRv5_server_rec ``` PaddleOCR 还提供更小的移动端模型,但 PP-OCRv5 中文识别模型当前默认映射为 `PP-OCRv5_server_rec`;不要只把检测模型替换成其他版本而保持识别模型不变,模型版本和配套模型应成套切换。 | 档位 | 检测模型 | 识别模型 | 特点 | | --- | --- | --- | --- | | 速度优先 | PP-OCRv4_mobile_det | PP-OCRv4_mobile_rec | 体积和 CPU 推理开销更小,但不是 PP-OCRv5,中文准确率可能下降 | | 当前默认 | PP-OCRv5_server_det | PP-OCRv5_server_rec | 中文准确率优先,模型约 166 MB | | 新版模型 | PP-OCRv6_medium_det | PP-OCRv6_medium_rec | 需要单独下载并验证,模型版本不是 PP-OCRv5 | 切换前建议: 1. 先把当前 `models/` 完整复制成独立备份,例如 `models.backup-ppocrv5/`; 2. 将新模型下载到另一个目录,例如 `models-ppocrv4-mobile/`; 3. 只修改 `config.yaml` 的 `model_dir` 和两个模型名称; 4. 用 `scripts/benchmark_ocr.py` 和真实业务图片对比耗时、漏检率和准确率; 5. 验证不满意时,把 `model_dir` 改回原目录即可,不改动原模型。 当前没有自动下载或替换任何小模型,也没有修改现有 PP-OCRv5 权重。服务只读加载模型;若要切换模型,必须使用新的模型目录或先制作备份。 ### 不换模型的加速方式 先尝试以下配置,不会修改模型文件: ```yaml text_det_limit_side_len: 640 text_recognition_batch_size: 1 ocr_workers: 1 ``` `text_det_limit_side_len` 从 `960` 调到 `640` 通常可以降低检测耗时,但小字可能漏检。`text_recognition_batch_size` 主要影响单张图片包含很多文本框时的吞吐;增大到 `2` 或 `4` 会增加内存,单张简单图片不一定更快。 ### 如何测速 ```powershell uv run python scripts/benchmark_ocr.py ``` 修改 `config.yaml` 后重新执行,比较输出的 `elapsed_ms`。建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数。 ## Python 版本说明 本项目的 Python 版本约束是 `>=3.10,<3.14`,当前项目固定为 Python 3.12: ```text .python-version = 3.12 ``` 这次切换**没有修改系统全局 Python,也没有卸载 Python 3.15**。`uv python pin 3.12` 只修改了当前项目的 `.python-version` 文件;项目使用的 Python 3.12 是 uv 管理的独立解释器,位置是: ```text C:\Users\zimoyin\AppData\Roaming\uv\python\cpython-3.12-windows-x86_64-none\python.exe ``` 机器上原有的 Python 3.15 仍在: ```text C:\Users\zimoyin\AppData\Local\Python\pythoncore-3.15-64\python.exe ``` 项目虚拟环境位于: ```text D:\code\work\ocr-server\.venv\Scripts\python.exe ``` 在 Ubuntu 上,建议使用系统 Python 3.10–3.12 或 uv 创建项目虚拟环境,不会影响系统其他 Python 项目。 ## Windows 安装和启动 ```powershell cd D:\code\work\ocr-server uv sync uv run ocr-server ``` 启动前修改项目根目录的 `config.yaml`: ```yaml host: 0.0.0.0 port: 8000 device: cpu ocr_workers: 1 ``` 然后启动: ```powershell uv run ocr-server ``` 也可以: ```powershell uv run python -m uvicorn ocr_server.app:app --host 0.0.0.0 --port 8000 ``` ## Ubuntu 22.04 安装和启动 适用于 Ubuntu 22.04 x86_64 CPU 环境(PaddlePaddle 官方 wheel 通常不覆盖 ARM 架构): ```bash sudo apt-get update sudo apt-get install -y curl libgl1 libglib2.0-0 cd /opt/ocr-server curl -LsSf https://astral.sh/uv/install.sh | sh # 重新打开 shell,或按安装提示加载 ~/.local/bin uv python install 3.12 uv sync --python 3.12 # 按需修改项目根目录 config.yaml,然后启动 uv run ocr-server ``` 如果服务器不能访问模型下载源,请在联网机器上执行 `scripts/download_models.py`,将完整项目的 `models/` 目录复制到 Ubuntu 服务器,再启动服务。依赖安装仍需要提前完成;完全离线安装还需要准备本地 Python wheel 缓存。 如果 Ubuntu 已经安装了兼容的 Python 3.10–3.12,也可以使用系统 Python(以实际可用的 `python3.10`、`python3.11` 或 `python3.12` 命令替换下面示例): ```bash python3.10 -m venv .venv .venv/bin/python -m pip install -U pip .venv/bin/python -m pip install -e . .venv/bin/ocr-server ``` GPU 部署不使用当前 CPU 依赖作为判断依据,请按照 PaddlePaddle 官方文档安装与 CUDA、cuDNN、驱动匹配的 GPU 版本,然后再安装本项目依赖。 ## API ### 1. 上传图片 ```bash curl -X POST http://127.0.0.1:8000/api/v1/upload \ -F "file=@./receipt.jpg" ``` 返回示例(所有接口统一使用 `code`、`message`、`data`): ```json { "code": 0, "message": "success", "data": { "file_id": "b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51", "filename": "receipt.jpg", "size": 123456, "width": 1600, "height": 1200, "status": "queued", "progress": 0, "queue_position": 1 } } ``` ### 2. 图片转文字 上传成功后图片会进入内存等待队列,默认由 1 个 OCR 工作线程按 FIFO 顺序识别。调用 `/api/v1/i2t` 时: - `queued`:任务还在等待,返回 `progress` 和 `queue_position`; - `processing`:任务正在识别,返回当前 `progress`; - `completed`:返回 JSON 识别结果; - `failed`:返回错误信息。 ```bash curl -X POST http://127.0.0.1:8000/api/v1/i2t \ -H "Content-Type: application/json" \ -d '{"file_id":"b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51"}' ``` 未完成时返回示例: ```json { "code": 0, "message": "success", "data": { "file_id": "b5a1e99c-9d7d-46f0-9e1e-1caa1fdc4e51", "status": "processing", "progress": 20, "queue_position": null, "ocr_started_at": "2026-10-11T10:20:30.123456Z", "ocr_finished_at": null, "ocr_elapsed_ms": null, "result": null, "error": null } } ``` 完成时 `result` 使用紧凑的 JSON 对象映射: ```json { "text": "BOARDING PASS", "polygon": { "text1": { "text": "BOARDING", "confidence": 0.9841, "Location": { "xtop": 420, "ytop": 20, "xbottom": 660, "ybottom": 66 }, "line": 1, "paragraphs": 1 } } } ``` - 不再返回 `segments` 数组、`lines` 数组和 `paragraphs` 数组; - 每个 `textN` 对象包含文字、置信度、矩形坐标、行编号和段编号; - 同一行的 `line` 值相同; - 同一自然段的 `paragraphs` 值相同; - `Location` 包含 `xtop`、`ytop`、`xbottom`、`ybottom`。 两个检测框在同一文本行时会分配相同的 `line` 编号;相邻文本行属于同一自然段时会分配相同的 `paragraphs` 编号。可选 `min_confidence`(0–1)过滤低置信度片段,服务会重新计算行编号和段编号。 ## IDEA HTTP Client 测试 已提供: ```text http/ocr-server.http ``` 在 IDEA 中打开文件,项目已附带 PaddleOCR 官方示例图片: ```text http/fixtures/general_ocr_002.png ``` 然后按顺序执行: 1. 健康检查; 2. 上传图片; 3. IDEA 自动保存上传响应中的 `file_id`; 4. 立即调用图片转文字接口,观察 `queued` / `processing` 进度; 5. 重复调用直到返回 `completed` 和 JSON 识别结果。 该测试图片来源于 PaddleOCR 官方示例。也可以把自己的图片复制到 `http/fixtures/`,再修改 `.http` 文件中的文件路径。 ## 配置 配置统一写在项目根目录的 `config.yaml`,服务启动时读取一次,修改后重启生效: ```yaml host: 127.0.0.1 port: 8000 upload_dir: data/uploads model_dir: models det_model_name: PP-OCRv5_server_det rec_model_name: PP-OCRv5_server_rec ocr_workers: 1 device: cpu lang: ch max_upload_mb: 10 max_image_pixels: 20000000 text_det_limit_side_len: 960 text_det_limit_type: max text_det_thresh: 0.3 text_det_box_thresh: 0.6 text_det_unclip_ratio: 1.5 text_rec_score_thresh: 0.0 text_recognition_batch_size: 1 ``` | 配置项 | 默认值 | 说明 | | --- | --- | --- | | `host` | `127.0.0.1` | 监听地址 | | `port` | `8000` | 监听端口 | | `upload_dir` | `data/uploads` | 图片存储目录 | | `model_dir` | `models` | PaddleOCR 模型下载和缓存目录 | | `det_model_name` | `PP-OCRv5_server_det` | 文本检测模型名称 | | `rec_model_name` | `PP-OCRv5_server_rec` | 文本识别模型名称 | | `ocr_workers` | `1` | OCR 工作线程数;每个线程独立加载一份模型 | | `max_upload_mb` | `10` | 单文件大小上限 | | `max_image_pixels` | `20000000` | 图片像素上限 | | `device` | `cpu` | `cpu` 或 GPU 设备配置 | | `lang` | `ch` | PaddleOCR 语言 | | `text_det_limit_side_len` | `960` | 检测图像最长边;调小可加速,可能漏检小字 | | `text_det_limit_type` | `max` | 检测缩放限制类型 | | `text_det_thresh` | `0.3` | 检测二值化阈值 | | `text_det_box_thresh` | `0.6` | 检测框置信度阈值 | | `text_det_unclip_ratio` | `1.5` | 检测框扩张比例 | | `text_rec_score_thresh` | `0.0` | 识别结果阈值 | | `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 | 接口文档:启动后访问 。 ## 测试 ```bash uv run pytest -q uv pip check ```