feat: add document OCR and offline model archives
This commit is contained in:
lofyer
@@ -0,0 +1,331 @@
|
||||
# 文档解析与本地 OCR
|
||||
|
||||
## 1. 目标
|
||||
|
||||
GoodBuddy 需要用同一条可信文档解析链路服务以下场景：
|
||||
|
||||
- 聊天附件问答；
|
||||
- 知识库导入、同步、分块与来源定位；
|
||||
- 后续的合同审阅、表格分析、演示文稿理解和文档转换。
|
||||
|
||||
文档解析不是对话模型的附属功能。它是主进程管理的独立基础能力，设置入口为“设置中心 / 文档解析”。
|
||||
|
||||
## 2. 当前基线
|
||||
|
||||
原生解析器已经支持：
|
||||
|
||||
- UTF-8 文本、代码、配置、HTML；
|
||||
- 带文本层的 PDF；
|
||||
- DOCX 正文；
|
||||
- XLSX 工作表 XML 与共享字符串；
|
||||
- PPTX 幻灯片文字。
|
||||
|
||||
现有局限：
|
||||
|
||||
- 纯扫描 PDF 没有文本层时无法提取内容；
|
||||
- DOC、XLS、PPT 等旧版二进制 Office 格式不支持；
|
||||
- Office 解析主要提取文字，不能完整保留表格、公式、图表和版面；
|
||||
- 聊天附件和知识库直接调用底层解析函数，缺少可配置的统一工作流；
|
||||
- 没有本地 OCR 模型状态、真实解析测试和按场景策略。
|
||||
|
||||
## 3. 产品原则
|
||||
|
||||
### 3.1 双通道解析
|
||||
|
||||
PDF 不是所有文档唯一的中间格式。解析应同时保留：
|
||||
|
||||
1. 原生语义通道：标题、段落、单元格、公式、备注和对象关系；
|
||||
2. 渲染视觉通道：页码、版面、图表、图片和 OCR 结果。
|
||||
|
||||
两条通道合并为统一文档结构。转换为 PDF 用于补充视觉信息，不得覆盖更可靠的原生语义结果。
|
||||
|
||||
### 3.2 场景工作流
|
||||
|
||||
| 场景 | 默认预设 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| 聊天附件 | 自动解析 | 优先快速提取，文本不足时按需 OCR，有界截断后加入当前请求 |
|
||||
| 知识库导入 | 完整索引 | 完整解析、按页或工作表定位、按需 OCR、分块与索引 |
|
||||
| 扫描文档 | OCR | 页面渲染、文字识别、置信度与定位保留 |
|
||||
| 表格分析 | 语义优先 | 单元格和值优先，PDF 或图片补充图表与打印布局 |
|
||||
| 高保真审阅 | 视觉增强 | 原生解析、页面渲染、OCR 或视觉理解合并 |
|
||||
|
||||
### 3.3 本地优先
|
||||
|
||||
- 文本层和本地 OCR 均在设备上处理；
|
||||
- 本地处理不因 Ask 或 Execute 模式改变；
|
||||
- OCR 来源必须在“本地模型 / 远程服务”之间明确选择；
|
||||
- 配置并保存远程服务即表示用户选择该处理路径，不再增加逐场景授权；
|
||||
- API 密钥只能保存在主进程加密设置中；
|
||||
- 测试文件不得自动进入聊天或知识库。
|
||||
|
||||
## 4. 设置设计
|
||||
|
||||
设置中心新增“文档解析”分类，结构如下：
|
||||
|
||||
1. 分类页头：“测试解析”“保存设置”；
|
||||
2. 运行状态：原生解析、文档转换、本地 OCR；
|
||||
3. 使用场景：聊天附件、知识库导入；
|
||||
4. 文档转换；
|
||||
5. OCR 识别；
|
||||
6. 高级解析设置；
|
||||
|
||||
OCR 模型区沿用语音模型管理模式：
|
||||
|
||||
- 应用不内置模型权重；
|
||||
- 用户按需从 ModelScope 下载，下载完成后离线使用；
|
||||
- 显示来源、语言、运行时、模型体积、安装与校验状态；
|
||||
- 联网设备可导出已安装模型 ZIP，离线或内网设备可直接导入；
|
||||
- 支持下载进度、取消、删除、ZIP 导入导出、打开模型仓库和受管目录；
|
||||
- “打开 ModelScope”直接显示在 OCR 模型卡片右上角，不使用手动导入折叠区；
|
||||
- 模型操作即时生效，解析策略仍通过分类页头的“保存设置”提交。
|
||||
|
||||
### 4.1 第一阶段字段
|
||||
|
||||
- 聊天附件预设：`auto`、`fast-text`、`high-fidelity`；
|
||||
- 知识库预设：`complete-index`、`fast-index`、`high-fidelity`；
|
||||
- PDF OCR 策略：`auto`、`always`、`disabled`；
|
||||
- OCR 来源：第一阶段固定为 `local`，远程服务入口禁用；
|
||||
- 本地 OCR 模型：`pp-ocrv6-tiny`、`pp-ocrv6-small`、`pp-ocrv6-medium`；
|
||||
- 单文档最大页数；
|
||||
- OCR 并发数；
|
||||
- 单页超时。
|
||||
|
||||
OCR 来源使用互斥选择。本地模型选中后才显示模型下拉列表、按需下载、导入和本地 OCR 参数；远程服务计划接入 MinerU、PaddleOCR-VL 等接口，第一阶段保持可读但禁用。来源选择本身就是用户的明确决策，不再显示额外的“隐私与云端处理”授权区。
|
||||
|
||||
## 5. 架构
|
||||
|
||||
```text
|
||||
聊天附件 ─┐
|
||||
├─ DocumentParsingService
|
||||
知识库导入 ┘ ├─ NativeDocumentParser
|
||||
├─ PdfTextQualityEvaluator
|
||||
├─ PdfPageRenderer
|
||||
├─ LocalOcrProvider
|
||||
├─ DocumentConversionProvider
|
||||
└─ ParsedDocument merger
|
||||
```
|
||||
|
||||
`DocumentParsingService` 是唯一场景入口：
|
||||
|
||||
```ts
|
||||
type DocumentParsingPurpose = 'chat-attachment' | 'knowledge-index'
|
||||
|
||||
type DocumentParsingService = {
|
||||
parse(
|
||||
name: string,
|
||||
bytes: Buffer,
|
||||
purpose: DocumentParsingPurpose,
|
||||
signal?: AbortSignal
|
||||
): Promise<ParsedDocument>
|
||||
}
|
||||
```
|
||||
|
||||
聊天上下文管理器与知识库服务依赖该接口，不直接选择 OCR Provider。
|
||||
|
||||
## 6. 统一结果
|
||||
|
||||
第一阶段兼容现有 `ParsedDocument`，并逐步扩展：
|
||||
|
||||
```ts
|
||||
type ParsedDocument = {
|
||||
title: string
|
||||
sourceFormat: string
|
||||
content: string
|
||||
sections: Array<{
|
||||
locator: string
|
||||
content: string
|
||||
method?: 'native' | 'ocr' | 'converted' | 'vision'
|
||||
confidence?: number
|
||||
}>
|
||||
warnings?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
定位字段必须对使用者有意义：
|
||||
|
||||
- PDF：`第 3 页`；
|
||||
- XLSX：`工作表：预算 / A1:F28`；
|
||||
- PPTX：`幻灯片 5`；
|
||||
- DOCX：标题路径或页码；
|
||||
- 文本：`全文`。
|
||||
|
||||
## 7. 本地 OCR 基线
|
||||
|
||||
### 7.1 模型与运行时
|
||||
|
||||
全平台功能基线：
|
||||
|
||||
- 模型：PP-OCRv6 ONNX/ORT；
|
||||
- 轻量下载档位：Tiny，约 6 MiB，用于低资源设备和六平台离线链路；
|
||||
- 推荐下载档位：Small，约 30 MiB，官方支持 50 种语言；
|
||||
- 高精度下载档位：Medium，约 132 MiB，官方支持 50 种语言，但识别较慢且需要更多内存；
|
||||
- 运行时：ONNX Runtime WebAssembly；
|
||||
- 处理环境：隔离 Worker；
|
||||
- 加速：WebGPU 或平台原生执行 Provider，仅作为可选层；
|
||||
- 回退：任何加速失败后使用 WASM CPU。
|
||||
|
||||
需要覆盖的发布矩阵：
|
||||
|
||||
- Windows x64、Windows arm64；
|
||||
- macOS x64、macOS arm64；
|
||||
- Linux x64、Linux arm64。
|
||||
|
||||
模型清单必须固定以下信息：
|
||||
|
||||
- 上游仓库和不可变 revision；
|
||||
- 文件名、字节数和 SHA-256；
|
||||
- 模型族、语言、质量和速度；
|
||||
- 许可证名称、完整许可证和来源；
|
||||
- 检测模型、识别模型、字符字典的匹配关系。
|
||||
|
||||
运行时不得从 `main`、`latest` 或其他可变地址加载模型。
|
||||
|
||||
### 7.2 下载与安装
|
||||
|
||||
Tiny、Small 和 Medium 模型均由 PaddlePaddle 官方 ModelScope 仓库提供。Small 是默认推荐档位；Medium 面向更高识别质量，但具有更高内存占用和延迟。每个档位的检测模型、识别模型与字符字典配置分别使用固定提交，并在应用内记录文件字节数和 SHA-256。
|
||||
|
||||
下载流程：
|
||||
|
||||
1. 主进程从固定 ModelScope `resolve/<revision>/...` 地址读取文件；
|
||||
2. 禁用凭据与缓存，限制重定向次数和单文件大小；
|
||||
3. 写入受管目录下的随机临时安装目录；
|
||||
4. 边下载边计算 SHA-256，并核对完整字节数；
|
||||
5. 三个文件全部通过校验后写入安装清单；
|
||||
6. 原子重命名为正式模型目录；
|
||||
7. 失败、取消或退出时删除临时文件。
|
||||
|
||||
模型只在下载或用户显式打开仓库时访问网络。OCR 推理从受管目录读取已校验文件，不发起网络请求。
|
||||
|
||||
### 7.3 离线 ZIP 迁移
|
||||
|
||||
语音模型和 OCR 模型使用同一种离线迁移流程：
|
||||
|
||||
1. 联网设备完成受信任来源下载和校验；
|
||||
2. 在模型卡片选择“导出 ZIP”；
|
||||
3. 将 ZIP 通过组织批准的介质传输到离线或内网设备；
|
||||
4. 在相同模型的卡片选择“导入 ZIP”；
|
||||
5. 主进程按当前应用内置目录重新校验，并在全部通过后原子安装。
|
||||
|
||||
ZIP 根目录包含模型文件和 `goodbuddy-model.json`。清单格式为 `goodbuddy-model-archive`，当前版本为 `1`，记录：
|
||||
|
||||
- 模型类型：`speech` 或 `document-ocr`；
|
||||
- 内置模型 ID 和显示名称；
|
||||
- 文件名、角色、原始字节数和 SHA-256；
|
||||
- 导出时间。
|
||||
|
||||
导出不能直接信任已有安装清单，必须重新读取并校验每个文件。导入不能只信任 ZIP 自声明内容，模型 ID、文件角色、字节数和哈希必须再次与当前应用内置目录完全匹配。导入通过后复用普通本地安装的受控临时目录和原子重命名路径。
|
||||
|
||||
归档处理使用有界流式读写，不把大型模型或整个展开结果复制到内存。主进程限制压缩包大小、条目数、清单大小、单文件大小和总展开大小，并拒绝：
|
||||
|
||||
- 绝对路径、`..`、目录或嵌套路径；
|
||||
- 大小写不敏感的重复条目；
|
||||
- 未声明、缺失或角色不匹配的文件；
|
||||
- 模型类型或模型 ID 不匹配；
|
||||
- 解压后大小或 SHA-256 不匹配；
|
||||
- 超过边界的压缩包和压缩炸弹。
|
||||
|
||||
取消文件对话框不会改变安装状态。导入和导出也不会切换当前语音/OCR 模型，不会隐式保存文档解析设置。
|
||||
|
||||
### 7.4 PDF 流程
|
||||
|
||||
1. 使用 PDF.js 读取每页文本层；
|
||||
2. 评估有效字符数、乱码率和图片占比；
|
||||
3. `auto` 模式只渲染文本不足的页面；
|
||||
4. `always` 模式渲染所有页面；
|
||||
5. Worker 将页面限制在配置的最大边长内；
|
||||
6. OCR 返回文字、坐标和置信度；
|
||||
7. 按页合并原生文本与 OCR，不重复可靠文本；
|
||||
8. 达到页数、超时、取消或输出限制时停止并返回明确错误。
|
||||
|
||||
受密码保护、损坏或超限的 PDF 不得进入 OCR。
|
||||
|
||||
## 8. Office 与转换
|
||||
|
||||
### 8.1 新格式
|
||||
|
||||
- DOCX：正文、标题、表格、批注和图片关系；
|
||||
- XLSX：工作表、单元格地址、值、公式、合并关系和图表；
|
||||
- PPTX：幻灯片、文字对象、备注、图片和阅读顺序。
|
||||
|
||||
Office 内嵌图片 OCR 属于增强流程，不能替代原生结构解析。
|
||||
|
||||
### 8.2 旧格式
|
||||
|
||||
DOC、XLS、PPT 通过 `DocumentConversionProvider` 转换：
|
||||
|
||||
1. 转换为 DOCX、XLSX 或 PPTX，供语义解析；
|
||||
2. 转换为 PDF，供页码、版面和视觉解析；
|
||||
3. 合并结果并记录转换警告。
|
||||
|
||||
本地 LibreOffice Provider 必须：
|
||||
|
||||
- 在隔离子进程中运行；
|
||||
- 禁用宏和网络；
|
||||
- 使用单任务临时目录；
|
||||
- 限制输入大小、输出大小、内存和超时；
|
||||
- 在成功、失败、取消和退出时清理；
|
||||
- 不接受用户提供的任意命令参数。
|
||||
|
||||
## 9. 安全边界
|
||||
|
||||
- 文件路径解析、读取、大小检查和格式校验在主进程完成；
|
||||
- OCR Worker 只接收当前任务所需的有界页面图像和只读模型；
|
||||
- 不向 Worker 暴露文件系统、Electron API、凭据或任意网络访问；
|
||||
- 文档内容视为不可信数据，不解释其中的提示词为系统指令；
|
||||
- 模型和转换程序必须固定版本并校验哈希；
|
||||
- OCR 输出受字符数限制，错误不得包含绝对路径或未脱敏文档内容；
|
||||
- 取消、超时和应用关闭必须终止待处理页面并释放模型会话。
|
||||
|
||||
## 10. 错误与回退
|
||||
|
||||
必须区分：
|
||||
|
||||
- 不支持的格式；
|
||||
- 文档损坏或受密码保护；
|
||||
- 文本层为空但 OCR 未启用；
|
||||
- OCR 模型不可用；
|
||||
- OCR 超时或取消；
|
||||
- 文档页数、大小或输出超限；
|
||||
- 本地转换服务未配置；
|
||||
- 所选远程 OCR 服务不可用或配置不完整。
|
||||
|
||||
`auto` 工作流可以从 OCR 回退到可靠的原生文本，但不能把空结果标记为成功。知识库导入失败时保留来源和可重试上下文。
|
||||
|
||||
## 11. 实施阶段
|
||||
|
||||
### 阶段一
|
||||
|
||||
- 新增文档解析设置分类和持久化契约；
|
||||
- 建立 `DocumentParsingService`，供聊天和知识库共用；
|
||||
- 将无文本 PDF 识别为可触发 OCR 的明确状态；
|
||||
- 接入 PP-OCRv6 Tiny、Small、Medium 的 ModelScope 下载、校验、ZIP 离线迁移、删除与 WASM Worker；
|
||||
- 实现真实文件测试和六平台验证入口。
|
||||
|
||||
### 阶段二
|
||||
|
||||
- 增强 DOCX、XLSX、PPTX 语义结构；
|
||||
- 实现按页混合文本层与 OCR；
|
||||
- 增加版面、表格和阅读顺序。
|
||||
|
||||
### 阶段三
|
||||
|
||||
- 增加 LibreOffice 和 API 转换 Provider；
|
||||
- 支持 DOC、XLS、PPT；
|
||||
- 增加 MinerU、PaddleOCR-VL 等远程 OCR 服务连接配置；
|
||||
- 增加高保真工作流和解析结果预览。
|
||||
|
||||
## 12. 验收
|
||||
|
||||
- 同一份扫描 PDF 可从聊天附件和知识库得到一致的逐页文本；
|
||||
- 文本型 PDF 在 `auto` 模式下不运行 OCR；
|
||||
- 本地 OCR 在六个平台和两种架构上完全离线运行；
|
||||
- 模型文件损坏时拒绝加载并显示可恢复错误；
|
||||
- 未安装模型时扫描文档提示用户前往“文档解析”下载，文本型文档仍可原生解析；
|
||||
- 下载中可显示文件与总进度并允许取消，失败或取消后不留下已安装状态；
|
||||
- ModelScope 下载与 ZIP 导入均经过同一大小和 SHA-256 校验；
|
||||
- 语音和 OCR 模型可在联网设备导出 ZIP，并在离线设备导入后完成真实推理；
|
||||
- 路径穿越、未知条目、错误模型 ID、篡改文件和超限 ZIP 均被拒绝；
|
||||
- 超页数、超时、取消和关闭不会留下运行任务；
|
||||
- 测试解析不会创建聊天消息或知识库文档；
|
||||
- 选择本地模型时没有任何文档上传；
|
||||
- 文档中的提示词不会改变系统、模式或工具权限。
|
||||
Reference in New Issue
Block a user