zyt/server/scripts/clinical_image_ocr.README.md

本地图片文字核对

本服务给现有 Dify 图片请求补充 OCR 原文、置信度和来源位置。原始图片仍提交给同一模型；OCR 不作诊断，也不将自己的输出标为已经核实的事实。原图与文字读数冲突时，提示模型并列标明待核实，不能擅自选择数值。

运行环境

使用独立 Python 3.11 环境，不在桌面客户端的 app/.venv 内安装依赖。安装固定版本：

python -m venv <本机专用OCR环境路径>
& <本机专用OCR环境路径>/Scripts/python.exe -m pip install -r server/scripts/clinical_image_ocr.requirements.txt
& <本机专用OCR环境路径>/Scripts/python.exe -m pip check

依赖从官方 PyPI 安装。运行时使用 RapidOCR 包内的固定本地模型，不自动下载模型，不访问网络。PHP 必须允许 proc_open，并能运行配置的解释器。缺少依赖、模型、权限或可用时间时，辅助识别明确不可用，保留原图请求。

在后端 .env 的 [prescription_ai] 段配置以下非敏感项：

LOCAL_OCR_ENABLED = true
LOCAL_OCR_PYTHON = <解释器绝对路径>
LOCAL_OCR_TIMEOUT = 15

默认未启用，不能只部署 PHP 文件就宣称 OCR 已生效。不要将开发机解释器路径复制到其他主机。本次本地测试已在独立环境安装并启用，不涉及正式后端部署。

资源、取消和真实性

• 单批最多使用配置的 15 秒；整次分批请求累计最多约 30 秒（按实际耗时扣减），并为原图模型请求预留 8 秒和进程清理 0.8 秒。时间不足时跳过辅助识别，不重新获得整单超时预算。
• OCR 原文通过请求私有文件描述符传递，清理后不保留。患者内容、源地址、令牌不放在进程参数或日志中。CPU 线程受限；文件字节、像素、尺寸、行数、输出量有界。此机制不是操作系统级硬内存配额。
• 取消后终止本地子进程，取消成立时不继续调用模型。上游停止接口的“接受停止”与“已经停止运行”须区分。
• 客户端仅收到安全状态：processed 是“已附带文字供模型核对”，不是“数字必然正确”；unreadable/unavailable 不阻断原图分析；withheld 表示可选 OCR 文本超出本轮容量而未附加。
• 超过模型单次附件上限时，逐批提取观察，再带完整原任务综合。每个原始来源使用稳定序号；缺失、不可判读、未返回唯一观察或综合容量不足，必须明确列入缺口。不能把附件“已上传”当作内容“已读取并综合”。
• 新增证据的字节预算是应用侧保护，不是上游 token 容量承诺。任意数量、任意长度素材都完整综合的能力不作保证。

验证

PHP 离线测试分别执行，避免命名空间桩互相污染：

php server/tests/ClinicalImageTextServiceTest.php
php server/tests/DifyOcrBudgetTest.php
php server/tests/DifyImageTextEvidenceTest.php
php server/tests/DifyLargeAttachmentContractTest.php

Python worker 测试需要 Pillow，使用上面的 OCR 环境或另一个安装了 Pillow 的测试环境，不能使用未安装这些依赖的桌面应用环境：

& <含Pillow的测试解释器> -m unittest discover -s server/tests -p test_clinical_image_ocr.py -v

显式本地进程测试只使用预先生成的合成 PNG，检查实际子进程、取消、超时与清理；不读取病例：

php server/tests/ClinicalImageTextBridgeProcessTest.php <OCR解释器绝对路径> <合成PNG绝对路径>

模型内容验收须另外核对最终正文的数值、小数点、正负号、单位与原始来源。不能用上传成功、HTTP 200 或 OCR processed 单独代替内容正确性验收。