本地发票 OCR 部署、选型与运维手册
版本：1.0 · 整理日期：2026-09-08 · 适用对象：实施、运维、财务管理员、客户技术人员。
当前交付状态
本次按用户要求，以适配代码及本手册归档收尾，不再启动 OCR 或执行推理测试。用户反馈启动 OCR 后电脑疑似重启，原因尚未确认。历史识别测试通过不代表本机稳定性验收通过；当前环境不得标注“生产验收通过”。
本文安装、启动、测试命令仅供后续获准的隔离测试机或客户验收环境参考，不要在当前疑似故障电脑上直接执行。不得配置无限重试或自动启动来反复复现重启。
1. 结论与适用范围
- 当前实际模型是 PP-OCRv4 中文检测 + 中文识别 + 文本方向分类，运行于独立 Python HTTP 服务，不是通用聊天大模型。
- 当前没有部署 PP-OCRv5、PP-StructureV3 或 PaddleOCR-VL。它们仍是后续评估路线，不能用其名称宣传当前能力。
- 当前只有一套 GPU 服务实现和可切换的 CPU 执行模式，不是已经发布三套 8G、16G、22G 模型。
- 本地服务地址约定为
http://127.0.0.1:18081，Java 后端调用该服务，浏览器不直接调用模型。 - 无独显的电脑可以考虑 CPU 路线；当前适配器没有 Intel/AMD 核显加速后端。CPU 模式的性能与稳定性尚未完成验收。
- 优先保证号码、购销方、税号、金额与明细正确，再优化吞吐。不能为了“识别成功”填入猜测值。
- OCR 是录入辅助，不是发票真伪查验，也不能代替财务审核。
本手册提供实际配置、历史测量、资源选型建议、部署流程、故障处理和验收清单。所有“建议档位”均为工程预算建议，不是官方最低配置，也不是采购性能保证。
2. 当前实现清单
| 项目 | 当前实现或状态 |
|---|---|
| HTTP 应用 | FastAPI，应用版本 1.1.0，Uvicorn |
| Python | 本机已安装 Python 3.11 |
| Paddle | 历史成功运行环境为 PaddlePaddle GPU 3.3.0、CUDA 11.8 路线 |
| OCR 包 | PaddleOCR 2.9.1 |
| OCR 权重 | ch_PP-OCRv4_det_infer、ch_PP-OCRv4_rec_infer、ch_ppocr_mobile_v2.0_cls_infer |
| NumPy | 1.26.4；历史安装出现过 NumPy 2.x 与旧依赖冲突 |
| PyMuPDF 1.28.2；优先读文字层，不满足检查时走图片 OCR | |
| 明细解析 | 按表头和坐标提取，包含少量单元格补识别；不是 PP-StructureV3 |
| 识别设备 | 默认 gpu；代码可选择 cpu |
| 同时推理 | 单进程、单推理锁，1 个请求执行；忙碌时返回 503 |
| 自动降级 | 未启用，不自动切云 OCR 或通用 VLM |
| 常驻与自恢复 | 当前未交付经过验证的系统服务、自启动及故障恢复机制 |
| 稳定性 | 有电脑重启反馈，未定位，阻止生产放行 |
2.1 文件职责
以下路径以项目仓库为根，便于客户按自己的安装目录定位。
| 文件或类 | 作用 |
|---|---|
ruoyi-office/ocr-service/gpu-windows/app.py | Windows GPU：模型加载、文件解码、HTTP 接口、推理和并发控制 |
ruoyi-office/ocr-service/gpu-windows/invoice_parser.py | 字段定位、表头解析、金额一致性告警 |
ruoyi-office/ocr-service/gpu-windows/start.ps1 | Windows 前台启动入口 |
ruoyi-office/ocr-service/gpu-windows/requirements.txt | GPU 应用依赖版本；不包含 Paddle 引擎安装项 |
ruoyi-office/ocr-service/gpu-windows/test_parser.py | 合成文字框解析测试，不调用 OCR 模型 |
ruoyi-office/ocr-service/gpu-windows/benchmark.py | 特定样本回归、热延迟与整卡 GPU 采样 |
ruoyi-office/ocr-service/cpu-yidong/ | 移动云 Linux CPU 节点（48082 + Token），与 GPU 目录隔离 |
AiOcrApiImpl | 根据 AI 模型及关联 API 配置调用本地服务 |
ModelInvoiceOcrClient | 本地返回映射成统一 InvoiceOcrResult |
FinanceInvoiceOcrServiceImpl | 识别记录和结构化返回留痕 |
ocr-recognize.vue | 前端上传和点击识别 |
invoice/input/modules/form.vue | 当前进项发票主表回填 |
2.2 已知实现边界
必须随交付说明一起保留，避免客户把配置项误认为已生效能力：
ocrLevel只表示显存档位信息，不会预留显存、加载更大模型或提高并发。ocrTableEnabled会由 Java 传入，但 Python 当前没有按该开关切换引擎；不代表启用了专业表格模型。- AI 模型 DO 和前端已有 OCR 扩展字段，但当前
AiModelSaveReqVO、AiModelRespVO未包含ocrLevel、ocrTableEnabled、ocrTimeoutMs。不能承诺这些字段经管理页面保存后能完整往返；需要后续补齐并验收。 model参数必须匹配服务实际加载标识；改一个名字不会下载或部署另一套模型。- 当前
AiOcrApiImpl的 OCR 平台分支只接受PaddleOCR。OpenAI 兼容 OCR、专业云 OCR、VLM 统一路由不是已完成能力。 - 当前前端进项发票表单回填主表部分字段，没有把返回的购方和明细全字段展示、保存的完整闭环。
- 金额检查现在由 Python 解析层产生告警；不是独立 Java 业务校验模块。当前告警不能等同于“已强制阻止错误入账”。
- Java HTTP 调用当前未严格检查上游状态码和返回契约，错误 JSON 存在被当作空识别结果解析的风险。客户端异常提示及拒绝空结果仍需专项修复验收。
- 识别记录中的原始返回会截取到约 60,000 字符；不能承诺所有文字框原始 JSON 完整保留。
- 失败阶段目前主要记为
recognize，没有完成下载、解码、推理、解析、校验的精细分阶段记录。
3. 请求链路与连接配置
财务页面上传文件
-> 系统文件服务 / 对象存储
-> POST /admin-api/finance/ocr/recognize
-> ModelInvoiceOcrClient
-> AI OCR 模型配置 + API 连接配置
-> 文件服务读取已上传文件内容
-> POST 本地OCR地址/ocr/invoice
-> 文件解码 / 文本提取 / 模型识别 / 字段解析
-> InvoiceOcrResult + OCR识别记录
-> 前端主表回填
-> 用户核对后保存“本地模型”表示推理在本地，不表示文件一定只存本机。若系统文件服务使用对象存储，发票影像仍会进入该存储系统。客户必须确认文件实际存储位置和访问权限。
3.1 AI 模型配置
| 配置项 | GPU 实例 | CPU 实例规划 |
|---|---|---|
| 模型名称 | 本地发票 OCR（GPU） | 本地发票 OCR（CPU） |
| 模型类型 | OCR，枚举值 7 | OCR，枚举值 7 |
| 平台 | PaddleOCR | PaddleOCR |
| 模型标识 | pp-ocrv4-gpu | pp-ocrv4-cpu |
| 关联 API 地址，同机 | http://127.0.0.1:18081 | 独立实例地址，例 http://127.0.0.1:18082 |
| 默认 Java 调用超时 | 120,000 ms | 120,000 ms；需按实际性能评估 |
| 状态 | 启用后才可选用 | 验收完成后启用 |
历史本机使用过模型 ID 69。该 ID 是数据库记录编号，不是客户通用值；新环境以实际创建的记录 ID 为准。
当前 API 配置记录需要关联，但 Java 没有发送其密钥，Python 也没有校验密钥。填写一个 API Key 不等于完成鉴权。同机保持回环监听；跨机部署必须另行实现网络限制和鉴权，不能直接开放公网端口。
3.2 财务配置
示例仅表示本机历史配置：
yudao:
finance:
ocr:
provider: model
model-id: 69客户环境将 69 改为实际 OCR 模型 ID。不得把模型字符串写到 model-id。
- 单体运行：配置应放入 yudao-server 实际生效 的配置文件、环境变量或启动参数。
- 微服务运行：放入 finance-server 实际使用的配置来源，并检查配置覆盖优先级。
- 仅修改 finance 模块 JAR 内的
application.yaml，不能证明单体主应用已经使用该值。 - 未配置模型 ID 时，代码会查找默认 OCR 模型；为避免选择漂移，客户环境建议明确指定 ID。
- 运行参数示例：
--yudao.finance.ocr.provider=model --yudao.finance.ocr.model-id=69。
3.3 网络部署方式
| 方式 | 地址规则 | 注意事项 |
|---|---|---|
| Java 与 OCR 同一 Windows 主机 | 127.0.0.1:18081 | 默认方式，限制外部访问 |
| Java 和 OCR 不同主机 | Java 使用 OCR 主机内网地址 | OCR 需要指定监听地址；只允许业务服务器访问 |
| Java 在容器、OCR 在宿主机 | 使用容器能到达的宿主地址 | 容器的 127.0.0.1 不是宿主机 |
| 客户多台电脑访问系统 | 只访问统一财务页面 | 每台财务电脑不必安装模型 |
推荐将 OCR 放在独立服务节点，避免与客户办公主机互相影响。但独立部署不能代替驱动、硬件和负载稳定性验收。
3.4 移动云 CPU 节点（与 GPU 验证并行）
2026-09-14 在 36.140.151.10 另外部署 PP-OCRv4 CPU，源码目录 ruoyi-office/ocr-service/cpu-yidong/，不改 GPU 目录与开发库模型 69 / Key 27。
| 项 | 值 |
|---|---|
| 地址 | http://36.140.151.10:48082 |
| 模型标识 | pp-ocrv4-cpu |
| 鉴权 | 识别接口必须带 X-OCR-Token，与 AI API Key 相同 |
| 运行账户 / 内存 | ocr / systemd MemoryMax=4G |
| 权重 | /data/ocr/.paddleocr |
| demo-a / demo-b | 已停（restart=no），给 OCR 让内存；官网备用仍常开 |
本机验证：在 AI 管理选用 CPU 模型，或启动参数覆盖 yudao.finance.ocr.model-id，不要改仓库默认 69。AiOcrApiImpl 在 Key 非空时发送 X-OCR-Token；GPU 本机服务不校验该头。
未做与 GPU 等价的延迟/稳定性验收，不得标生产放行。公网走安全组已放行的 TCP 48082（18082 控制台加不了，不要再等新规则）。后续演示容器请走宿主机内网 192.168.0.2:48082 或 172.17.0.1:48082，不要从容器绕公网 EIP。Token 只放 /data/ocr/.env，泄漏即轮换。
4. 模型规格与硬件对应关系
4.1 当前服务实际规格
| 参数 | 当前默认值 | 含义 |
|---|---|---|
OCR_DEVICE | gpu | 只支持 gpu 或 cpu，不支持 intel_gpu 等设备名 |
OCR_HOST | 127.0.0.1 | 监听地址 |
OCR_PORT | 18081 | HTTP 端口 |
OCR_MAX_SIDE | 1920 | 检测阶段长边限制，不是所有输入必须达到的分辨率 |
OCR_CPU_THREADS | 4 | CPU 推理线程参数，不是 CPU 核心预留 |
OCR_PYTHON | 当前用户 Python311 路径 | start.ps1 使用的 Python 可执行文件 |
rec_batch_num | 6 | 一次文字识别批中的裁剪文本数量，不是同时处理 6 张发票 |
| Uvicorn workers | 1 | 当前服务为一个工作进程 |
| 推理并发 | 1 | 锁被占用时拒绝新识别，不存在已实现的持久队列 |
| 文件大小 | 最大 20 MiB | 还受浏览器、代理、Java 上传限制共同约束 |
| 像素数量 | 最大 30,000,000 | 解码后的图像面积限制 |
| 页数 | 单页、单帧 | 多页 PDF、多帧图片明确拒绝 |
当前检测、识别和方向分类权重是小型专用 OCR 组件，不是 8B/16B 参数的大语言模型。“8G/16G/22G”指显存预算档位，不是参数量，也不是 OCR 权重体积。
4.2 客户选型建议
下表是 OCR 节点本身 的起步预算，不包含 Java、数据库、Redis、对象存储等完整业务系统资源。未实测的档位不得直接写入性能 SLA。
| 档位 | CPU / 主内存建议 | GPU 建议 | 适用方向 | 当前验证状态 |
|---|---|---|---|---|
| CPU 轻量评估 | 4 核起、8 GB 起，建议 16 GB；SSD | 不要求独显 | 低频录入、以带文字层 PDF 为主 | 代码可切 CPU；整套性能及稳定性未完成测试 |
| 8G 独显 | 4~8 核、16 GB；SSD | 兼容所选 CUDA/Paddle 构建的 NVIDIA 8 GB | 单实例中文票据 OCR 起步 | 未在独立 8 GB 卡上验收；不能从 22 GB 卡推导等价性能 |
| 16G 独显 | 8 核起、32 GB；SSD | NVIDIA 16 GB，具体卡及软件组合需验证 | 为较高分辨率、后续表格模型预留空间 | PP-StructureV3 未部署，不能保证组合能装下或达到特定吞吐 |
| 22/24G 独显 | 8~12 核起、32~64 GB；SSD | NVIDIA 22/24 GB，具体卡需验收 | 本地专业 OCR 节点及后续模型对比实验 | 本机 2080 Ti 22 GB 有历史识别结果，但存在重启反馈 |
| 多实例服务节点 | 按每实例实测资源累加并留余量 | 一张或多张经验证的 GPU | 多部门峰值负载与可用性建设 | 需新增排队、限流、路由、健康摘除；当前未交付 |
磁盘可先为运行环境、模型缓存和日志预留 20~40 GB 可用 SSD 空间，再为发票存储单独计算容量。该值是实施预算，不是当前权重大小；不要把历史影像无限写入 OCR 临时盘。
显存更大不必然更快。准确率主要取决于模型、输入质量、检测尺寸和字段解析；当前配置把 ocrLevel 从 8 改成 22，不会改善识别结果。
4.3 核显是否能部署
应向客户分三种情况解释：
| 客户环境 | 当前适配能否使用 | 说明 |
|---|---|---|
| 只有 Intel/AMD 核显，CPU 指令集和 Python/Paddle 安装条件满足 | 可作为 CPU 路线候选 | 设置 OCR_DEVICE=cpu，使用 CPU 执行，不是核显加速 |
| 要求调用 Intel 核显加速 | 当前不支持 | 需要另做推理后端与模型转换适配及精度回归 |
| 要求 AMD 核显、NPU 或其他加速器 | 当前不支持 | 不能沿用 NVIDIA CUDA 配置直接交付 |
本机硬件采样为 Ryzen 9 5900X + RTX 2080 Ti，系统视频控制器查询只列出该独显。因此本次没有核显加速实测证据。
CPU 模式也不是当前电脑的“安全重试办法”：此前尝试计划使用的仍是 GPU 版 Paddle 安装目录，即使选择 CPU，也不能据此排除底层运行库风险。后续 CPU 验证应在隔离环境安装独立 CPU 版引擎，避免与 GPU 包混装。本轮按用户要求停止测试。
4.4 PP-OCRv5 与其他模型路线
| 路线 | 定位 | 本次状态 |
|---|---|---|
| PP-OCRv4 | 当前已适配专用文字 OCR | 已有样本识别证据，稳定性未放行 |
| PP-OCRv5 | 后续专用 OCR 候选 | 需另建适配和独立环境，不能只改模型名 |
| PP-OCRv5 + PP-StructureV3 | 后续版面、表格候选 | 显存、准确率、延迟、2080 Ti 兼容性均待实测 |
| PaddleOCR-VL 等文档视觉模型 | 复杂版式候选 | 未部署；不得承诺 2080 Ti 可用或特定显存下可运行 |
| 专业云 OCR | 本地无法满足时的备选 | 需完成服务商适配、费用评估、数据出境/外发授权及回归 |
| 通用 VLM | 补充路线 | 不是默认 OCR，不自动回退，避免未经同意外发发票 |
5. GPU 占用和历史测试数据
5.1 如何理解“占用”
- 显存已用量：整张卡上的所有进程和图形桌面共同占用的内存。
- GPU 利用率：采样窗口内 GPU 的繁忙程度；不能与显存占比混为一谈。
- Python 工作集：进程驻留的系统内存，不是显存。
- 进程私有内存：另一种系统内存口径，不能直接加到工作集上当作物理内存总占用。
未取得可靠的逐进程 GPU 显存分摊，以下数值全部明确按整卡统计。不同测试时桌面、浏览器和其他程序状态不同，不应将它们相减后宣称是精确模型显存。
5.2 本机采样
采样日期为 2026-09-08，数据是历史快照，不是阅读本文时的实时状态。
| 阶段 | 整卡已用显存 | GPU 利用率 | 含义 |
|---|---|---|---|
| 23:21 左右，OCR 端口不可达时 | 725 MiB / 22,528 MiB，约 3.2% | 20% | 说明其他负载本身会使用 GPU |
| 随后启动就绪、请求前的只读采样 | 980 MiB / 22,528 MiB，约 4.4% | 18% | 包含桌面和其他进程，不是 OCR 独占 |
| 21:36 历史回归过程采样峰值 | 1,802 MiB，约 1.76 GiB | 44% 峰值 | 采样峰值，非硬件瞬时最大值 |
| 23:13 已保存回归报告采样峰值 | 1,470 MiB，约 1.44 GiB | 45% 峰值 | 另一轮背景负载不同的测量 |
同次就绪进程采样：Python 工作集约 940 MiB，私有内存约 2.25 GiB。主机可见物理内存约 64 GB。
用户报告启动后疑似导致重启后，已停止本轮启动与测试操作。不再为补“当前占用”而启动服务；不能据较低显存占用排除稳定性问题。
5.3 历史识别回归
报告位置位于 OCR 服务目录的 test-output/，默认不进入 Git，也不应随客户公开手册传播原始发票数据。
| 报告 | 用例结果 | 原 JPG 热推理均值 | 热请求 P95 估计 |
|---|---|---|---|
benchmark.json，21:36 | 22/22 | 606.3 ms | 645 ms |
benchmark-gpu-handbook.json，23:13 | 22/22 | 642.2 ms | 716 ms |
统计口径：
- 只有 1 张独立发票，22 个用例包含五种图片编码、旋转、留白、2°倾斜、变暗、压缩、PDF，以及十次原图热请求。
- 样本为电子专票，包含一条明细；核对主表 10 项和第一条明细 6 项。
- 十次热请求样本量很小；脚本 P95 使用排序后最大值作为小样本近似，不能据此承诺长期生产 P95。
- 延迟是本地 HTTP 客户端请求耗时，包含请求传输与服务处理，不包含前端上传、对象存储读取、Java 留痕和最终保存。
- PDF 文字层通过时走
pdf-text，不能算作 GPU 图片识别速度或图片准确率。 - 6 项解析单元测试曾通过，覆盖合成的左右/上下布局、多明细、坐标缩放、竖排标签、数字和金额校验；这不是纸票图像实测。
- 没有完成真实多票种大样本验收、长时间稳定性测试、人工修正率统计或客户环境压测。
- CPU 性能测试未完成，不提供虚构的 CPU 耗时、核显耗时或 CPU/GPU 加速比。
5.4 容量规划方式
当前单实例不会自动排队，峰值请求超过 1 个就可能返回 OCR_BUSY。平均 0.6 秒不能直接换算成承诺的每小时产能。
后续容量评估应分别统计上传、文件读取、推理、数据库和表单交互耗时，按实际票种混合比例测量成功率、P95/P99、拒绝率和重试量。多实例需验证每个实例的内存/显存增量与并发稳定性，不能按“总显存除以某次峰值”直接决定实例数。
6. 文件格式与票种支持
6.1 文件载体
| 输入 | 当前处理 | 验证情况 |
|---|---|---|
| JPG/JPEG、PNG、WEBP、BMP | 解码为 RGB 后 OCR | 同一样本编码回归通过 |
| 单帧 TIFF | 解码后 OCR | 同一样本编码回归通过 |
| 单页、带文字层 PDF | 优先抽取文字和坐标，校验后返回 | 用户样本历史回归通过 |
| 单页扫描 PDF | 渲染成图片后 OCR | 有实现路径，独立扫描件未验收 |
| 多页 PDF、多帧 TIFF/动画 | 明确拒绝，要求拆分 | 不是自动批量识别功能 |
| 加密 PDF | 明确拒绝 | 需业务人员提供获准读取的文件 |
| OFD、XML 发票 | 当前未适配 | 需要专门解析器，不能改扩展名冒充 PDF |
| HEIC、GIF、Office 文档、压缩包 | 当前不在支持列表 | 应提示转换或提供支持格式，不保证自动处理 |
文件扩展名与载体解码不同。服务会检查实际数据；前端允许选择某扩展名不代表已完成所有相关票种的识别。
6.2 发票业务类型
解析器有专票/普票、电子/纸质的分类规则，以及购销方左右或上下排列的提取逻辑。但独立图像验收目前仅覆盖用户提供的电子专票。
纸质增值税专票、纸质普票、电子普票、多明细/跨页清单、免税/不征税、红字、差额征税、机动车、二手车、通行费、火车票、航空票据等必须分别收样验收。不得将“能打开文件”写成“支持该票种全字段”。
7. 安装与迁移流程
以下为后续部署步骤，不是本轮执行记录。当前故障主机保持停测。先在隔离环境完成版本、驱动、硬件稳定性和许可证检查，再进入客户部署。
7.1 准备与目录
准备 Python 3.11、待验证的 Paddle 安装包、应用依赖、OCR 权重、应用源码及适配后的 Java/前端发布包。运行环境与权重都应形成版本清单和校验和。
推荐独立目录示例：
D:\services\invoice-ocr\
app.py
invoice_parser.py
start.ps1
requirements.txt
runtime-packages\
logs\
test-output\start.ps1 当前通过 PYTHONPATH 加载 runtime-packages，不再依赖旧 .venv。历史 .venv 曾不完整，不应作为交付虚拟环境复制。脚本依赖目录已安装，不会自动安装引擎或修复依赖。
7.2 引擎与应用依赖
应新建独立安装目录，不在混有其他业务依赖的 Python 环境中覆盖升级。
GPU 历史复现步骤示例，仅用于后续隔离验证；该组合有重启反馈，不属于稳定版本推荐：
$Root = 'D:\services\invoice-ocr'
$Python = 'C:\Python311\python.exe'
$Packages = Join-Path $Root 'runtime-packages'
& $Python -m pip install --target $Packages `
--index-url https://www.paddlepaddle.org.cn/packages/stable/cu118/ `
paddlepaddle-gpu==3.3.0
& $Python -m pip install --target $Packages --upgrade `
-r (Join-Path $Root 'requirements.txt')注意：
requirements.txt没有引擎安装项，只执行它不足以启动 OCR。- 固定 NumPy 1.26.4，避免重现旧 OCR 依赖与 NumPy 2.x 的冲突。
- Python 包、驱动、CUDA/cuDNN 的匹配需在目标机器重新检查；不能认为 pip 成功即推理稳定。
- 当前日志曾出现 cuDNN 兼容性警告，即便历史识别成功也不应忽略。
- 新客户建议在验证通过后制作完整依赖锁定和离线 wheel 清单；现有 requirements 只锁定部分直接依赖，不是完整可复现锁文件。
- 离线部署需同时携带权重缓存，不能只复制 Python 包。默认权重目录为运行账户的
%USERPROFILE%\.paddleocr\whl。 - 换成系统服务账户后，用户目录会变化，应将权重放到该运行账户可读取的缓存目录，并避免每次启动联网下载。
CPU 路线应在另一套干净目录中安装适用于目标系统的 CPU 版 paddlepaddle，不安装 paddlepaddle-gpu，再安装同一应用依赖。具体可用 wheel 和兼容版本由目标机安装验证确定；本轮未验证干净 CPU 安装，不将其描述成“一键部署已通过”。
7.3 后续允许启动时
GPU 实例示例：
Set-Location 'D:\services\invoice-ocr'
$env:OCR_PYTHON = 'C:\Python311\python.exe'
$env:OCR_DEVICE = 'gpu'
$env:OCR_HOST = '127.0.0.1'
$env:OCR_PORT = '18081'
$env:OCR_MAX_SIDE = '1920'
.\start.ps1CPU 实例示例，应使用独立 CPU 安装目录与解释器：
Set-Location 'D:\services\invoice-ocr-cpu'
$env:OCR_PYTHON = 'C:\Python311\python.exe'
$env:OCR_DEVICE = 'cpu'
$env:OCR_PORT = '18082'
$env:OCR_CPU_THREADS = '4'
.\start.ps1这些是前台调试启动方式，不是已经注册好的 Windows 服务。改变端口或设备后必须同步检查 AI 模型关联地址和模型标识。
7.4 健康检查与冒烟
仅在获准测试的环境执行：
Invoke-RestMethod 'http://127.0.0.1:18081/health'应包含 status=UP、ready=true、model=pp-ocrv4-gpu、device=gpu。服务启动会初始化模型并做一次预测；health 成功仍不等于全天稳定或字段准确。
脱敏样本接口冒烟示例：
$File = 'D:\samples\invoice.jpg'
$Body = @{
fileName = [IO.Path]::GetFileName($File)
imageBase64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes($File))
model = 'pp-ocrv4-gpu'
} | ConvertTo-Json -Compress
$Result = Invoke-RestMethod `
-Uri 'http://127.0.0.1:18081/ocr/invoice' `
-Method Post -ContentType 'application/json' -Body $Body -TimeoutSec 120
$Result.invoice成功标准是返回字段与标注一致、金额与明细校验符合业务规则，而不是只看 HTTP 200。
8. Java、前端和数据库交付
8.1 数据结构迁移
已归档脚本：
ruoyi-office-db/update/202609/20260907_update/01_apply_必跑/
210000_finance_ocr_add_model_metadata.sql
210010_ai_ocr_dict.sql新增内容涉及 AI OCR 元信息、OCR 识别记录的模型/耗时/失败信息，以及模型类型和平台字典。脚本并不为每个客户自动创建正确模型连接。
迁移前备份数据库、确认目标库、检查已有字段。DDL 脚本按每组首列判断是否存在，若数据库处于“部分列存在”的中间状态，不应直接认为重新执行可以自动补齐其余列。
8.2 模型管理与发布
- 迁移目标库并检查字典、列结构。
- 创建或选择 PaddleOCR API 连接配置。
- 创建类型为 OCR 的模型，指定正确标识并启用。
- 指定财务
provider=model和实际model-id。 - 核对第 2.2 节的 VO 字段往返缺口，不能仅凭前端有控件就认为保存成功。
- 发布包含 OCR 适配的 Java 与前端版本，验证最终生效配置。
- 通过系统上传入口验证，不只调用 Python。
8.3 页面验收步骤
财务页面路径为 /finance/invoice/input-invoice。历史本机开发地址为 http://127.0.0.1:5800/finance/invoice/input-invoice，这不是客户生产地址，也不代表当前服务在线。
每个验收样本执行：
- 新建进项发票并上传文件，确认文件服务保存成功。
- 点击 OCR，核对实际模型、识别记录、主表金额及日期。
- 确认失败时未把空响应或错误字段当作成功回填。
- 核对告警；金额不一致必须由财务确认，后续应补齐强制阻止机制。
- 保存测试单据后重新打开，检查数据库保存值，而不是仅截取回填画面。
- 明细、购方全字段若属于客户交付范围，须先补齐当前表单闭环再验收。
本轮文档收尾未执行上述完整浏览器保存验收，不应在客户签字单中预勾选通过。
9. 运维与安全基线
9.1 日常检查
部署稳定后再建立监控，分别检查进程、模型就绪、合成脱敏样本识别和 Java 链路。
建议监测：成功率、无字段返回、金额告警、请求耗时、忙碌拒绝数、队列长度（后续实现）、Python 内存、GPU 显存、驱动错误、主机重启与磁盘余量。
当前故障机禁止自动探针反复初始化模型。 服务未启动时，不要用启动脚本替代只读健康检查。
9.2 系统服务与自动恢复
稳定性验收后再由运维配置 Windows 服务或计划任务，要求：
- 使用专用低权限运行账户和明确工作目录。
- 固定 Python、依赖目录、模型缓存目录、监听地址和端口。
- stdout/stderr 写入受控日志目录并轮转；保留版本与启动时间。
- 有限次重试、退避、失败告警；发生整机重启后禁止继续自动拉起。
- 停止服务时先停止入口请求并等待当前任务结束。
- 防止同一端口或同一 GPU 被重复拉起多个未规划实例。
本次没有注册自启动、守护进程或定时拉起任务；这些要求是未来部署规范。
9.3 数据与接口安全
- 默认只监听
127.0.0.1，禁止直接公网暴露。 - 跨机部署需专用网络和经验证的接口鉴权；当前代码没有 API Key 校验闭环。
- 不让终端用户任意指定服务 URL、模型地址或服务器文件路径。
- 上传文件按实际类型、大小和页数校验；代理层也要限制请求体大小。
- Base64 会增加 HTTP 请求体体积，20 MiB 文件不等于 20 MiB JSON。
- 当前解码发生在推理锁之前，锁只限制推理，不是完整的内存防护；生产还需入口并发限制。
- OCR 原始文字、影像、税号、银行账户与调试报告均按财务敏感数据管理。
- 不把真实发票、密钥、内网连接串写入公开手册；本手册不附原样本内容。
- 第三方组件与模型许可证，尤其 PDF 解析组件及其商业分发条件，应在客户交付前由负责人核验，不因能够安装就默认可自由再分发。
10. 常见故障处理
| 现象 | 首先检查 | 处置原则 |
|---|---|---|
Connection refused | OCR 进程、监听端口、地址视角 | 不等于模型识别失败；当前故障机不要反复启动 |
paddle.utils 找不到 | Paddle 安装是否完整、Python 路径 | 历史残缺目录问题；隔离环境重新准备引擎，不混用旧目录 |
NumPy / np.sctypes 报错 | NumPy 是否被升级到 2.x | 按验证版本重建环境，不在线随意升级 |
| CUDA/cuDNN DLL 或兼容性警告 | 实际加载库、驱动和引擎版本 | 不以一次成功忽略警告，重新做稳定性评估 |
| 模型名不匹配，HTTP 400 | model 与 /health 的 model | pp-ocrv5-gpu 不能调用当前 v4 实例 |
| HTTP 400 文件错误 | 实际类型、页数、加密、尺寸 | 使用支持且完整的单页文件 |
| HTTP 422 | 请求结构或没有可识别 VAT 发票 | 查看返回详情，检查样本质量，不能直接标识别成功 |
HTTP 503 / OCR_BUSY | 当前是否已有推理任务 | 人工稍后重试；未来建设排队与退避，不能无限并发轰击 |
| HTTP 502 | 推理异常和服务日志 | 保存失败上下文，隔离处理，不静默切通用模型 |
| Python 200，但字段错误 | 原始文字框、解析锚点、金额检查 | 精度问题与网络问题分开分析，保留样本回归 |
| Python 正常，页面失败 | Java 文件读取、模型 ID、HTTP 处理、数据库列 | 按链路逐段定位 |
| 页面有 OCR 扩展项但保存无效 | AI 模型 Save/Resp VO | 当前存在字段缺口，需代码修复后验证 |
| 图片慢、PDF 快 | 返回的 source | pdf-text 与 image-ocr 必须分开统计 |
11. 启动后疑似整机重启
11.1 已知与未知
已知：用户报告启动 OCR 后电脑疑似重启；此前 OCR 启动会加载 Paddle 和运行一次预测，日志存在 cuDNN 兼容性警告。
未知：是否为驱动崩溃、系统故障、供电、温度、硬件稳定性、运行库组合或其他同时运行任务引起。没有证据将原因锁定为某个组件，也不能把“显存还很空”作为排除依据。
11.2 当前措施
- 停止启动与推理测试，不自动恢复服务。
- 本次仅交付文档及已有适配成果，不更改驱动、BIOS、功耗或系统安全设置。
- 不继续 CPU 模式复现，不运行 GPU 压测，不通过反复启动“试好为止”。
- 保留已有源码、依赖版本、日志、历史报告和用户描述。
11.3 后续获准后的调查顺序
- 记录重启时间、是否蓝屏、是否断电式重启、当时运行程序与硬件调整记录。
- 先读取 Windows 系统事件、可靠性历史和已有转储，不先复现推理。
- 区分“发生非正常关机”的事件和能解释具体原因的证据，避免仅凭一条电源事件归因。
- 由有权限的运维或硬件负责人检查驱动、散热、供电和硬件稳定性，变更须可回滚。
- 在隔离机分别验证纯 CPU 环境和匹配的 GPU 环境，每次只改变一个变量。
- 先完成模型加载，再单张、重复、有限并发、长时间运行，任何整机异常立即停止。
- 确认稳定后才开启常驻、自动恢复和业务端调用。
本节是排查方案，不表示这些调查已经执行或已得出诊断结论。
12. 回归、验收与客户交付
12.1 样本集
建议按客户业务采集独立脱敏发票，而不是把一张票反复换格式当作大样本。至少包含纸质专票、纸质普票、电子专票、电子普票、客户常用全电票、不同明细行数及异常图像。
单独增加免税、红字、特殊票种、裁切、严重阴影、透视拍照和扫描 PDF；未通过的类型明确列为不支持或必须人工录入。
标注字段包括号码、代码、日期、购销方与税号、金额/税额/总额、每一条明细。双人复核标注，识别结果不能反过来充当标准答案。
12.2 测试工具
test_parser.py 是不依赖模型推理的解析测试；benchmark.py 当前内置了特定发票的预期字段，不能随便换一张图片就拿通过率当作有效测试。新样本应先建立独立标注，再扩展测试驱动。
GPU 采样只得到整卡信息，CPU 路线跑相同脚本时即使出现 GPU 利用率，也不能证明 CPU OCR 使用了 GPU。
12.3 待验收门槛
| 检查项 | 放行标准 |
|---|---|
| 稳定性 | 不发生主机重启、驱动重置或持续资源泄漏，完成约定时长运行 |
| 字段 | 按独立样本集分别统计主字段、号码税号、金额和明细准确率 |
| 安全失败 | 服务断开、错误 JSON、无字段结果、忙碌及解码失败不能伪装成功 |
| 金额 | 不一致需要人工确认，并按业务要求强制限制保存或入账 |
| 界面 | 上传、识别、回填、保存、重开核对完整闭环 |
| 可追溯 | 样本、模型、版本、参数、原始返回、结构化结果和修正记录可关联 |
| 性能 | 在客户约定的文件质量、峰值负载下测 P95/P99 和拒绝率 |
| 数据保护 | 文件、日志、测试报告的存储权限与保留周期符合客户要求 |
本轮只完成手册归档，不将上述待验收项勾选为通过。
13. 升级、备份与回滚
- 发布包包括服务源码、依赖清单、权重清单及校验和、Java/前端版本、数据库迁移和脱敏测试报告。
- 配置与密钥单独管理，不随源码公共分发。
- 新版本安装到独立目录和测试端口，不覆盖正在运行的依赖。
- 先做模型及解析回归，再做 Java 链路和浏览器保存回归；不能只比较模型排行榜。
- 保留上一版发布包及配置快照。切换失败时，回滚模型地址、ID 和应用版本。
- 数据库新增列一般先保留，不应在回滚时直接删除财务历史记录或识别留痕。
- 本次历史环境未通过稳定性放行，不能把它视为可直接恢复生产的“安全版本”。
14. 交接登记模板
客户 / 环境：
用途：测试 / 生产
负责人 / 联系方式：
OS / CPU / 内存 / GPU / 驱动：
Python / Paddle / PaddleOCR / NumPy：
模型标识 / 权重校验和：
服务版本 / 代码版本：
AI 模型 ID / 关联连接 ID：
Java 生效配置来源：
OCR 地址 / 端口 / 监听范围：
运行账户 / 权重目录 / 日志目录：
支持文件类型 / 已验收票种：
输入尺寸 / 请求限制 / 并发策略：
独立样本数 / 字段准确率 / 人工修正率：
时延口径 / P95 / 失败与拒绝率：
主机稳定性验收记录：
鉴权 / 备份 / 保留周期 / 回滚版本：
已知限制 / 未关闭问题：
实施签字 / 财务签字 / 验收日期：15. 本次归档结论
本次已保留本地 OCR 适配、图片解析优化及历史样本测试成果，并整理客户选型、连接、安装、运维、故障处理和验收手册。
按用户最新要求停止继续启动和验证，以文档收尾结束本次适配任务。任务收尾不等于生产认证：整机重启风险、全票种验收、完整字段保存及实现缺口仍保留为后续事项。
