

LocalOCR · 功能说明
我不需要每次从模型名开始选择。先指定原件和想拿到的结果,普通图片、扫描 PDF 与文件夹就能进入相应本机路线;明确要求具体模型时保留我的选择,处理过程会说明实际使用了什么。
当前情况:已有图片、扫描 PDF 和文件夹的本地识别入口;9 月 24 日起现役版本换了更稳的 Windows 路径传递,并拒收别的网站借浏览器发来的请求。会按要求说明实际路线,具体文字仍以本次原件核对。10 月 26 日起的现役版本还能选用显卡还是 CPU:默认自动时显卡被占,普通文字识别会把这次剩下的文件改在 CPU 上读完;截图或视频帧可以整个文件夹一次送进去,默认只交回每个文件的简要结果。
项目现状截至 2026-10-11 14:00(北京时间),于同日 16:30–16:48 只读核对;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库

LocalOCR · 功能说明
我不需要每次从模型名开始选择。先指定原件和想拿到的结果,普通图片、扫描 PDF 与文件夹就能进入相应本机路线;明确要求具体模型时保留我的选择,处理过程会说明实际使用了什么。
当前情况:已有图片、扫描 PDF 和文件夹的本地识别入口;9 月 24 日起现役版本换了更稳的 Windows 路径传递,并拒收别的网站借浏览器发来的请求。会按要求说明实际路线,具体文字仍以本次原件核对。10 月 26 日起的现役版本还能选用显卡还是 CPU:默认自动时显卡被占,普通文字识别会把这次剩下的文件改在 CPU 上读完;截图或视频帧可以整个文件夹一次送进去,默认只交回每个文件的简要结果。
项目现状截至 2026-10-11 14:00(北京时间),于同日 16:30–16:48 只读核对;具体测试保留各自日期,页面不实时探测运行状态。
项目源码:公开仓库


用途与实际影响
一律使用重模型会增加等待,一律使用普通提字又可能丢掉复杂页面结构。这个入口把输入范围、结果要求和模型选择分开,并让模型不足时的增强有迹可查,而不是用“智能识别”掩盖真实判断方式。
我可以说:“把这份扫描版多栏 PDF 的文字读出来并保留版面,文件留在本机。”系统会固定这一个输入并选择合适路线;如果给的是文件夹,也只处理本次明确要求的范围。要是这份 PDF 本来就是电子版、能直接选中文字,AI 会先直接读它自带的文字,不必交给 LocalOCR。
返回对应文件的结果路径、实际引擎与模型、选择原因,以及是否发生增强。遇到不支持的文件、模型冲突、活跃任务或服务身份不符,会说明原因,不交回来自另一条未知路线的结果。
输入范围与路线明确,按请求执行并返回实际模型和输出。
自动提字不足时可以本地增强;增强失败保留首轮初步证据,但不标完成。
原件不可读、模型冲突或服务不是 LocalOCR 时停止相应请求,不抢端口、不换云服务;别的网页想借浏览器调用本机服务,或请求格式不对,服务直接拒收。

用途与实际影响
一律使用重模型会增加等待,一律使用普通提字又可能丢掉复杂页面结构。这个入口把输入范围、结果要求和模型选择分开,并让模型不足时的增强有迹可查,而不是用“智能识别”掩盖真实判断方式。
我可以说:“把这份扫描版多栏 PDF 的文字读出来并保留版面,文件留在本机。”系统会固定这一个输入并选择合适路线;如果给的是文件夹,也只处理本次明确要求的范围。要是这份 PDF 本来就是电子版、能直接选中文字,AI 会先直接读它自带的文字,不必交给 LocalOCR。
返回对应文件的结果路径、实际引擎与模型、选择原因,以及是否发生增强。遇到不支持的文件、模型冲突、活跃任务或服务身份不符,会说明原因,不交回来自另一条未知路线的结果。
输入范围与路线明确,按请求执行并返回实际模型和输出。
自动提字不足时可以本地增强;增强失败保留首轮初步证据,但不标完成。
原件不可读、模型冲突或服务不是 LocalOCR 时停止相应请求,不抢端口、不换云服务;别的网页想借浏览器调用本机服务,或请求格式不对,服务直接拒收。

输入范围与路线明确,按请求执行并返回实际模型和输出。
自动提字不足时可以本地增强;增强失败保留首轮初步证据,但不标完成。
原件不可读、模型冲突或服务不是 LocalOCR 时停止相应请求,不抢端口、不换云服务。

输入范围与路线明确,按请求执行并返回实际模型和输出。
自动提字不足时可以本地增强;增强失败保留首轮初步证据,但不标完成。
原件不可读、模型冲突或服务不是 LocalOCR 时停止相应请求,不抢端口、不换云服务。

在本机已接入 LocalOCR 的 AI 对话中指定原件,或用“日常本机入口” ocr_smart.ps1 传入明确路径。截图或视频帧可以把整个文件夹一次传入。
- 图片、扫描 PDF 或目录
- 递归范围(要不要连子文件夹一起读)
- 想要文字、复杂版面还是指定模型;要不要限定只用显卡或只用 CPU(不说就是自动)


在本机已接入 LocalOCR 的 AI 对话中指定原件,或用“日常本机入口” ocr_smart.ps1 传入明确路径。截图或视频帧可以把整个文件夹一次传入。
- 图片、扫描 PDF 或目录
- 递归范围(要不要连子文件夹一起读)
- 想要文字、复杂版面还是指定模型;要不要限定只用显卡或只用 CPU(不说就是自动)



- router.py 枚举支持的图片和 PDF;是否递归由 recursive 参数决定,不默认扩大目录范围。
- Smart Router v5 预先选路,让 auto 先走 OCR(光学字符识别);difficulty.py 结合逐页空结果、低置信度及表格/公式内容信号,service.py 只增强对应问题页。10 月 26 日起(提交 985d750)表格线判断只认细线,先去掉字幕条、标题栏和暗角这类整块深色区域,视频帧和截图不再因此被当成表格整批交给 VL;普通平面截图也不默认开文档矫正(UVDoc)。
- 同一任务保留增强前文字与几何;显式模型不参加自动替换,Structure(结构化版面)不是自动流程的隐含第三层。
- model_registry.py 解析 profile(具体模型配置),核对引擎匹配;显式模型不被自动选择覆盖。设备另由 device=auto|gpu|cpu 选(命令行 --device,Windows 脚本 -Device,也可写 gpu:N 指定某张显卡);目前只有普通文字识别的 ppocrv6-medium 配置带 CPU 参数,VL 和 Structure 不走 CPU。


- router.py 枚举支持的图片和 PDF;是否递归由 recursive 参数决定,不默认扩大目录范围。
- Smart Router v5 预先选路,让 auto 先走 OCR(光学字符识别);difficulty.py 结合逐页空结果、低置信度及表格/公式内容信号,service.py 只增强对应问题页。10 月 26 日起(提交 985d750)表格线判断只认细线,先去掉字幕条、标题栏和暗角这类整块深色区域,视频帧和截图不再因此被当成表格整批交给 VL;普通平面截图也不默认开文档矫正(UVDoc)。
- 同一任务保留增强前文字与几何;显式模型不参加自动替换,Structure(结构化版面)不是自动流程的隐含第三层。
- model_registry.py 解析 profile(具体模型配置),核对引擎匹配;显式模型不被自动选择覆盖。设备另由 device=auto|gpu|cpu 选(命令行 --device,Windows 脚本 -Device,也可写 gpu:N 指定某张显卡);目前只有普通文字识别的 ppocrv6-medium 配置带 CPU 参数,VL 和 Structure 不走 CPU。

- start.bat 使用 pwsh,start.ps1 声明 PowerShell 7.3+,Git 固定 start.bat 为 CRLF,避免中文批处理被异常解析。9 月 24 日(提交 cd2e1b9)起,scripts/windows_paths.ps1 用所选 Ubuntu 发行版的
wslpath -a -u换算路径,非默认挂载位置也能认;start、start_server、stop_server 都从脚本自身所在目录($PSScriptRoot)找项目,不再写死项目位置;输入参数作为独立参数传给 WSL,不拼bash -c字符串。其后的 localocr.cli 继续共用 OCRService、增强与输出合同,模型路线没有改变。
- ocr_smart.ps1 预览路线并验证服务健康,以 active_jobs 作为忙碌依据;缺字段为 readiness_unknown,不能当空闲。ocr_smart.ps1 和 ocr_once.ps1 默认只返回每个文件的精简摘要(覆盖与质量状态、路线、输出路径),加 -Full 才给完整 JSON;视频帧建议整个文件夹一次送入,复用同一个温热进程。服务端 server.py 从 9 月 24 日起逐个检查请求:Host 只认 localhost 或 127.0.0.1;带 Origin(浏览器标明的来源网站)的请求必须同源,否则返回 403,上传和取消也一样;/ocr/path 只收 JSON,/ocr/file 只收表单上传,格式不对返回 415。命令行等原生客户端不带 Origin,照常可用。


- start.bat 使用 pwsh,start.ps1 声明 PowerShell 7.3+,Git 固定 start.bat 为 CRLF,避免中文批处理被异常解析。9 月 24 日(提交 cd2e1b9)起,scripts/windows_paths.ps1 用所选 Ubuntu 发行版的
wslpath -a -u换算路径,非默认挂载位置也能认;start、start_server、stop_server 都从脚本自身所在目录($PSScriptRoot)找项目,不再写死项目位置;输入参数作为独立参数传给 WSL,不拼bash -c字符串。其后的 localocr.cli 继续共用 OCRService、增强与输出合同,模型路线没有改变。
- ocr_smart.ps1 预览路线并验证服务健康,以 active_jobs 作为忙碌依据;缺字段为 readiness_unknown,不能当空闲。ocr_smart.ps1 和 ocr_once.ps1 默认只返回每个文件的精简摘要(覆盖与质量状态、路线、输出路径),加 -Full 才给完整 JSON;视频帧建议整个文件夹一次送入,复用同一个温热进程。服务端 server.py 从 9 月 24 日起逐个检查请求:Host 只认 localhost 或 127.0.0.1;带 Origin(浏览器标明的来源网站)的请求必须同源,否则返回 403,上传和取消也一样;/ocr/path 只收 JSON,/ocr/file 只收表单上传,格式不对返回 415。命令行等原生客户端不带 Origin,照常可用。



| 名词 | 意思 |
|---|---|
| auto(自动选择) | 按当前可解释规则选 ocr(光学字符识别) 或 vl;不是无条件选择最重模型,也不包含 structure(结构化版面)。 |
| explicit model(明确模型) | 用户明确指定某个配置时按它执行;冲突要说明,不能静默改写。 |
| route(实际识别路线) | 记录最终引擎、原因、信号与增强过程,方便解释与复核。 |

明确读哪个文件、要文字还是结构;普通内容先提字,不够再本地增强。



明确读哪个文件、要文字还是结构;普通内容先提字,不够再本地增强。

- 输入不支持或不可读: 返回明确的输入或读取错误,不制造空白成功结果。
- 显式引擎与模型不匹配: 拒绝该组合,让调用方修正配置;不私自换模型。
- 本地增强失败: 保留首轮 partial(初步结果)与失败原因,整体仍为失败,不能写入成功缓存。
- 显卡被占或显卡调度器不可用: 默认自动时,普通文字识别把这次剩下的文件改在 CPU 上读完;需要增强的页保留首轮结果,标明因显卡不可用跳过增强和页码,不算质量充分。明确要求只用显卡,或选了只支持显卡的 VL、Structure,则直接返回冲突(409 或 503);运行中途失去显卡资格仍算失败,不中途改用 CPU。
- 端口是另一个服务: 报告 non-LocalOCR service,停止提交;不把 18666 当自动后备。

- 输入不支持或不可读: 返回明确的输入或读取错误,不制造空白成功结果。
- 显式引擎与模型不匹配: 拒绝该组合,让调用方修正配置;不私自换模型。
- 本地增强失败: 保留首轮 partial(初步结果)与失败原因,整体仍为失败,不能写入成功缓存。
- 显卡被占或显卡调度器不可用: 默认自动时,普通文字识别把这次剩下的文件改在 CPU 上读完;需要增强的页保留首轮结果,标明因显卡不可用跳过增强和页码,不算质量充分。明确要求只用显卡,或选了只支持显卡的 VL、Structure,则直接返回冲突(409 或 503);运行中途失去显卡资格仍算失败,不中途改用 CPU。
- 端口是另一个服务: 报告 non-LocalOCR service,停止提交;不把 18666 当自动后备。

- 支持类型与输入枚举
- 自动与显式路线
- 困难度依据
- 实际增强与统一执行
- Windows 有界入口与服务识别
- 2026-09-07,376a777 的 24 项 Windows 调用回归通过,4.210 秒;另经真实 start.bat、pwsh 与已确认 wsl.exe 替身验证中文空格路径完整传递,0.458 秒。这两个耗时是当时发表的记录,运行回执原件之后没有再找到;24 项测试定义和对应提交仍可核对。检查在模型执行前结束,没有重验 OCR(光学字符识别)效果或服务在线。
- 模型注册、分流与调用脚本行为有独立单元测试。9 月 24 日快照(当时现役)的验收回执记录 181 项单元测试 165 项通过、16 项按条件跳过、0 项失败;9 月 24 日加入的路径与请求检查已在那一版快照里(对应文件与开发源码一致)。现役已是 10 月 26 日快照,验收为 206 项、19 项按条件跳过、0 项失败,并带上 10 月 14—16 日的 Windows 入口修复(输出回传与临时路径、输出收集受同一期限约束、输入路径不存在时明确报失败);它同样没有新的 Windows 端到端演练回执。
- 9 月 17 日禁用缓存的九例质量回执包含 auto_table,实际表格关键单元格通过。9 月 24 日那版验收的同名案例里(10 月 16 日现役验收也一样升级到 VL),auto_table 确实由快模型升级到强模型 VL,起因是检测到表格线:快读 9 个文字块的平均把握分高达 0.999949,照样升级,最终满足门槛。真实使用中,9 月 26 日一份 16 页扫描 PDF 只把第 15 页交给强模型重读(表格信号,平均把握分 0.997081)。这些案例不证明任意版面都能正确选路。
这个模块决定如何进入任务;表格与版面模块解释结构需求,结果与复核模块解释如何读返回值,任务与运行模块处理复用和故障。

- 支持类型与输入枚举
- 自动与显式路线
- 困难度依据
- 实际增强与统一执行
- Windows 有界入口与服务识别
- 2026-09-07,376a777 的 24 项 Windows 调用回归通过,4.210 秒;另经真实 start.bat、pwsh 与已确认 wsl.exe 替身验证中文空格路径完整传递,0.458 秒。这两个耗时是当时发表的记录,运行回执原件之后没有再找到;24 项测试定义和对应提交仍可核对。检查在模型执行前结束,没有重验 OCR(光学字符识别)效果或服务在线。
- 模型注册、分流与调用脚本行为有独立单元测试。9 月 24 日快照(当时现役)的验收回执记录 181 项单元测试 165 项通过、16 项按条件跳过、0 项失败;9 月 24 日加入的路径与请求检查已在那一版快照里(对应文件与开发源码一致)。现役已是 10 月 26 日快照,验收为 206 项、19 项按条件跳过、0 项失败,并带上 10 月 14—16 日的 Windows 入口修复(输出回传与临时路径、输出收集受同一期限约束、输入路径不存在时明确报失败);它同样没有新的 Windows 端到端演练回执。
- 9 月 17 日禁用缓存的九例质量回执包含 auto_table,实际表格关键单元格通过。9 月 24 日那版验收的同名案例里(10 月 16 日现役验收也一样升级到 VL),auto_table 确实由快模型升级到强模型 VL,起因是检测到表格线:快读 9 个文字块的平均把握分高达 0.999949,照样升级,最终满足门槛。真实使用中,9 月 26 日一份 16 页扫描 PDF 只把第 15 页交给强模型重读(表格信号,平均把握分 0.997081)。这些案例不证明任意版面都能正确选路。
这个模块决定如何进入任务;表格与版面模块解释结构需求,结果与复核模块解释如何读返回值,任务与运行模块处理复用和故障。
复制 AI 续作说明
项目:从指定原件到合适的本地识别方式;仓库:wlyaaaaa/LocalOCR;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。








