Folio-OCR 三栏文档 OCR 工作台

博主： admin
发布时间：2026 年 03 月 17 日
0 次浏览
暂无评论
7753字数
分类： Docker python 技术文档工具箱

# Folio-OCR 三栏文档 OCR 工作台

# 一、概述

## 1. 简介
### A. 是什么
Folio-OCR 是一款基于 GLM-OCR 和 Ollama 的三栏文档 OCR 工作台，专为书籍和文档的日常批量识别设计。它提供了一个现代化的 Web 界面，支持图片和 PDF 文件的批量光学字符识别，并具备智能版面分析、实时编辑和多种格式导出功能。

### B. 为什么学
- 解决文档数字化过程中的人工识别效率问题
- 利用本地化 OCR 方案保护数据隐私
- 学习 FastAPI 前后端分离架构和版面分析技术
- 了解如何将大型语言模型集成到实际应用中

### C. 学完能做什么
- 搭建本地化的 OCR 识别服务
- 批量处理 PDF 和图片文档
- 使用版面分析技术提高识别准确率
- 将识别结果导出为 Markdown、TXT 或 Word 文档

## 2. 前置知识
### A. 必备技能
- 基础的 Linux 命令行操作
- 了解 Docker 基础概念

### B. 推荐知识
- Python 基础编程知识
- Web 开发基础概念
- OCR 和版面分析基础

# 二、环境准备

## 1. 系统要求
- 操作系统：Linux、macOS、Windows 10/11
- Docker：20.10+（推荐使用 Docker 部署）
- Python：3.10+（本地部署）
- Ollama：已安装（本地部署）
- 硬件：建议 8GB+ 内存，有 NVIDIA 显卡可获得更好性能

## 2. 安装步骤

### Docker 部署（推荐）

```bash
# 1. 克隆项目
git clone https://github.com/vorojar/Folio-OCR.git
cd Folio-OCR

# 2. 启动服务
docker compose up -d

# 3. 下载 OCR 模型（约 2GB，只需执行一次）
docker compose exec ollama ollama pull glm-ocr
```

### 本地部署

```bash
# 安装依赖
pip install -r requirements.txt

# 拉取模型
ollama pull glm-ocr

# 启动服务
python server.py

# Windows 一键启动
start.bat
```

## 3. 验证安装
打开浏览器访问 http://localhost:3000，若能看到界面则表示安装成功。

```bash
# 检查 Ollama 状态
curl http://localhost:11434/api/tags

# 检查服务状态
curl http://localhost:3000/api/status
```

# 三、核心概念

## 1. 基本术语
- **GLM-OCR**：智谱 AI 开发的 OCR 模型，用于图像文字识别
- **Ollama**：本地化大模型运行平台，提供 GLM-OCR 的推理服务
- **FastAPI**：Python Web 框架，用于构建后端 API
- **PP-DocLayoutV3**：PaddlePaddle 的文档版面分析模型
- **SQLite**：轻量级数据库，用于持久化存储文档和 OCR 结果
- **版面分析**：自动检测文档中的标题、正文、表格、图片等区域

## 2. 工作原理

```mermaid
graph LR
    User[用户] --> FE[前端界面]
    FE --> API[FastAPI 后端]
    API --> DB[(SQLite 数据库)]
    API --> Layout[版面分析模型]
    API --> Ollama[Ollama OCR 服务]
    Layout --> API
    Ollama --> API
    API --> FE
    API --> Storage[文件存储]
```

![Folio-OCR 系统架构](https://static.op123.ren/static/b6/b65e30cf99bdfc8f.svg)

系统采用三层架构设计：
1. 前端层：提供三栏式用户界面，负责文件上传、结果显示和用户交互
2. 后端层：FastAPI 提供 RESTful API，处理版面分析、OCR 调用和数据持久化
3. 服务层：Ollama 提供 OCR 推理服务，PP-DocLayoutV3 提供版面分析能力

# 四、快速上手

## 1. 基本使用流程

```mermaid
graph TD
    A[启动服务] --> B[上传文档]
    B --> C[自动拆页处理]
    C --> D[版面分析]
    D --> E[OCR 识别]
    E --> F[编辑校对]
    F --> G[导出文档]
```

![Folio-OCR 使用流程](https://static.op123.ren/static/69/69864702e13b48f7.svg)

## 2. 上传文档
支持以下文件格式：
- 图片：PNG、JPG、GIF、BMP
- 文档：PDF

支持多文件混合上传，系统会自动将所有文件合并为一个文档，并按页码顺序排列。

## 3. OCR 识别
系统提供两种 OCR 模式：
- 单页识别：对选中的页面进行 OCR
- 批量识别：点击 OCR All Pages 一键处理全部页面

识别过程中会显示实时进度条和 ETA 时间估算，用户可以随时点击 Stop 按钮中断处理。

## 4. 编辑与导出
识别结果支持：
- Edit 模式：纯文本编辑，便于手动修正
- Preview 模式：实时渲染 HTML 表格和 Markdown 格式
- 段落重排：自动合并因换行断开的段落

导出格式：
- Markdown（.md）
- 纯文本（.txt）
- Word 文档（.docx）

# 五、核心功能

## 1. OCR 引擎
### A. 版面分析
使用 PP-DocLayoutV3 模型进行智能版面分析，自动识别以下区域：
- 标题（title）
- 正文（text）
- 表格（table）
- 图片（figure）
- 页眉页脚、脚注、页码（自动跳过）

### B. 智能合并
相邻文本区域会自动合并，减少 OCR 调用次数。例如 11 个文本区域可合并为 3 组，实现约 2.5 倍加速。

### C. LaTeX 处理
自动将模型输出的 LaTeX 符号转换为 Unicode 字符：
- `$\textcircled{1}$` → `①`
- `$\frac{1}{2}$` → `½`
- 其他常见数学符号

### D. 清理处理
自动清理模型输出的 Markdown 围栏标记。

## 2. 数据持久化
使用 SQLite 数据库存储以下信息：
- 文档元数据（ID、文件名、创建时间）
- 页面信息（页码、文件名、OCR 结果、版面区域、处理时间）
- 自动保存编辑内容（800ms 防抖）

## 3. 界面交互
### A. 三栏布局
- 左栏：页面缩略图，支持快速切换页面
- 中栏：图片预览，显示版面分析区域框
- 右栏：OCR 结果，支持编辑和预览

### B. 双向高亮
点击图片中的区域框会高亮对应的文本块，点击文本块会高亮对应的图片区域。

### C. 全文搜索
支持 Ctrl+F 全文搜索，跨页高亮显示匹配内容并统计命中次数。

### D. 键盘导航
使用 ↑↓ 方向键快速切换页面。

## 4. 网络容错
所有网络请求都带有超时保护：
- 状态检查：5 秒
- OCR 调用：180 秒
- 其他请求：30 秒

Ollama 断开后 UI 不会冻结，超时后会自动恢复可操作状态并通过 Toast 弹窗通知用户。

# 六、技术架构

## 1. 后端架构

```mermaid
graph TB
    subgraph 后端服务
        API[FastAPI Server]
        DB[(SQLite)]
        Layout[PP-DocLayoutV3]
        Uploads[uploads/ 目录]
    end

subgraph 外部服务
        Ollama[Ollama GLM-OCR]
    end

API --> DB
    API --> Layout
    API --> Uploads
    API --> Ollama
```

![Folio-OCR 后端架构](https://static.op123.ren/static/f0/f066a55bbc617247.svg)

## 2. 版面分析流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant API as FastAPI
    participant L as Layout 模型
    participant O as Ollama

U->>API: 上传图片
    API->>L: 版面分析
    L-->>API: 返回区域列表
    API->>API: 合并相邻区域
    loop 对每个合并区域
        API->>O: OCR 调用
        O-->>API: 返回识别文本
    end
    API->>U: 返回完整结果
```

![版面分析流程](https://static.op123.ren/static/5d/5d31b9fc67386583.svg)

## 3. 数据库设计

```mermaid
erDiagram
    documents ||--o{ pages : 包含
    documents {
        string doc_id PK
        string filename
        string created_at
    }
    pages {
        string doc_id FK
        integer num
        string filename
        text ocr_text
        text ocr_regions
        real ocr_time
    }
```

![数据库结构](https://static.op123.ren/static/9e/9e7edf9cfd7fd80a.svg)

## 4. 主要依赖

| 依赖 | 版本 | 用途 |
|-----|------|------|
| fastapi | >=0.100.0 | Web 框架 |
| uvicorn | >=0.23.0 | ASGI 服务器 |
| httpx | >=0.25.0 | 异步 HTTP 客户端 |
| pymupdf | >=1.23.0 | PDF 处理 |
| Pillow | >=10.0.0 | 图像处理 |
| transformers | >=4.40.0 | 版面分析模型 |
| torch | >=2.0.0 | 深度学习框架 |
| python-docx | >=1.1.0 | Word 文档生成 |

# 七、部署架构

## 1. Docker Compose 配置

```mermaid
graph LR
    Host[宿主机] --> LB[Nginx/Proxy]
    LB --> App[App 容器]
    LB --> Ollama[Ollama 容器]
    App --> DB[(SQLite 数据卷)]
    App --> Files[uploads 数据卷]
```

![Docker 部署架构](https://static.op123.ren/static/b9/b951a961b921a63a.svg)

## 2. GPU 加速
若有 NVIDIA 显卡，可编辑 docker-compose.yml 取消 deploy 段落的注释以启用 GPU 加速。

```yaml
services:
  ollama:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
```

## 3. 常用 Docker 命令

```bash
docker compose down           # 停止服务
docker compose up -d          # 重新启动（数据不会丢失）
docker compose logs -f app    # 查看应用日志
docker compose logs -f ollama # 查看 Ollama 日志
```

# 八、性能参考

| 操作 | 时间 | 说明 |
|-----|------|------|
| 模型冷启动首次请求 | ~50 秒 | 需加载模型到内存 |
| 后续单页识别 | ~0.5 秒 | 版面分析 + OCR |
| PDF 渲染 | 取决于页数 | 2x 缩放矩阵渲染 |
| 整体加速比 | 2.5x | 相比逐区域 OCR |

# 九、常见问题

## 1. 安装问题

### Ollama 未找到
错误信息：Ollama not found
解决方法：先安装 Ollama 并确保其在 PATH 中

```bash
# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# 从 https://ollama.com/download 下载安装包
```

### 模型下载失败
解决方法：检查网络连接，手动执行模型拉取

```bash
ollama pull glm-ocr
```

## 2. 运行问题

### OCR 超时
可能原因：图片过大或网络问题
解决方法：
- 系统已设置 180 秒超时，等待即可
- 检查 Ollama 服务是否正常运行
- 尝试重启服务

### 版面分析失败
可能原因：模型未正确加载
解决方法：
- 确保已安装 torch 和 transformers
- 检查服务器日志查看具体错误

## 3. 使用问题

### PDF 拆页不清晰
说明：系统使用 2x 缩放矩阵渲染 PDF 以保证 OCR 质量
解决方法：如需更高分辨率，可修改 server.py 中的 mat 参数

### 导出的 Word 文档格式问题
说明：DOCX 导出基于 python-docx，解析 OCR 结果中的表格和标题
解决方法：识别时确保版面分析正确检测到表格区域

# 十、项目结构

```
Folio-OCR/
├── server.py            # FastAPI 后端（单文件）
├── index.html           # HTML 页面
├── script.js            # 前端逻辑
├── style.css            # 样式
├── latex_unicode.json   # LaTeX → Unicode 映射表
├── requirements.txt     # Python 依赖
├── Dockerfile           # Docker 镜像构建
├── docker-compose.yml   # Docker Compose 编排
├── start.bat            # Windows 启动脚本
├── folio_ocr.db         # SQLite 数据库（运行时生成）
└── uploads/             # 上传文件目录（运行时生成）
```

# 十一、API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | / | 前端页面 |
| GET | /api/status | 服务状态、Ollama 连通性 |
| POST | /api/load-model | 启动 Ollama 并预热模型 |
| POST | /api/upload | 上传文件，返回 SSE 页面流 |
| GET | /api/images/{doc_id}/{filename} | 获取页面图片 |
| POST | /api/ocr/{doc_id}/{page_num} | 单页 OCR |
| POST | /api/ocr/{doc_id}/all | 批量 OCR 全部页面 |
| GET | /api/documents | 列出所有文档 |
| GET | /api/documents/{doc_id} | 获取文档详情 |
| DELETE | /api/documents/{doc_id} | 删除文档 |
| PUT | /api/pages/{doc_id}/{page_num}/text | 保存编辑后的文本 |
| POST | /api/export/{doc_id} | 导出 DOCX |

***

## 参考资料

1. [Folio-OCR GitHub 仓库](https://github.com/vorojar/Folio-OCR)
2. [GLM-OCR 模型](https://huggingface.co/zai-org/GLM-OCR)
3. [Ollama 官方文档](https://ollama.com/)
4. [FastAPI 官方文档](https://fastapi.tiangolo.com/)
5. [PP-DocLayoutV3 模型](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors)

最后修改：2026 年 03 月 17 日

如果觉得我的文章对你有用，请随意赞赏

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

Folio-OCR 三栏文档 OCR 工作台

admin • 2026 年 03 月 17 日

# Folio-OCR 三栏文档 OCR 工作台

# 一、概述

## 2. 前置知识
### A. 必备技能
- 基础的 Linux 命令行操作
- 了解 Docker 基础概念

### B. 推荐知识
- Python 基础编程知识
- Web 开发基础概念
- OCR 和版面分析基础

# 二、环境准备

## 2. 安装步骤

### Docker 部署（推荐）

```bash
# 1. 克隆项目
git clone https://github.com/vorojar/Folio-OCR.git
cd Folio-OCR

# 2. 启动服务
docker compose up -d

# 3. 下载 OCR 模型（约 2GB，只需执行一次）
docker compose exec ollama ollama pull glm-ocr
```

### 本地部署

```bash
# 安装依赖
pip install -r requirements.txt

# 拉取模型
ollama pull glm-ocr

# 启动服务
python server.py

# Windows 一键启动
start.bat
```

## 3. 验证安装
打开浏览器访问 http://localhost:3000，若能看到界面则表示安装成功。

```bash
# 检查 Ollama 状态
curl http://localhost:11434/api/tags

# 检查服务状态
curl http://localhost:3000/api/status
```

# 三、核心概念

## 2. 工作原理

![Folio-OCR 系统架构](https://static.op123.ren/static/b6/b65e30cf99bdfc8f.svg)

# 四、快速上手

## 1. 基本使用流程

```mermaid
graph TD
    A[启动服务] --> B[上传文档]
    B --> C[自动拆页处理]
    C --> D[版面分析]
    D --> E[OCR 识别]
    E --> F[编辑校对]
    F --> G[导出文档]
```

![Folio-OCR 使用流程](https://static.op123.ren/static/69/69864702e13b48f7.svg)

## 2. 上传文档
支持以下文件格式：
- 图片：PNG、JPG、GIF、BMP
- 文档：PDF

支持多文件混合上传，系统会自动将所有文件合并为一个文档，并按页码顺序排列。

## 3. OCR 识别
系统提供两种 OCR 模式：
- 单页识别：对选中的页面进行 OCR
- 批量识别：点击 OCR All Pages 一键处理全部页面

识别过程中会显示实时进度条和 ETA 时间估算，用户可以随时点击 Stop 按钮中断处理。

导出格式：
- Markdown（.md）
- 纯文本（.txt）
- Word 文档（.docx）

# 五、核心功能

### B. 智能合并
相邻文本区域会自动合并，减少 OCR 调用次数。例如 11 个文本区域可合并为 3 组，实现约 2.5 倍加速。

### C. LaTeX 处理
自动将模型输出的 LaTeX 符号转换为 Unicode 字符：
- `$\textcircled{1}$` → `①`
- `$\frac{1}{2}$` → `½`
- 其他常见数学符号

### D. 清理处理
自动清理模型输出的 Markdown 围栏标记。

## 3. 界面交互
### A. 三栏布局
- 左栏：页面缩略图，支持快速切换页面
- 中栏：图片预览，显示版面分析区域框
- 右栏：OCR 结果，支持编辑和预览

### B. 双向高亮
点击图片中的区域框会高亮对应的文本块，点击文本块会高亮对应的图片区域。

### C. 全文搜索
支持 Ctrl+F 全文搜索，跨页高亮显示匹配内容并统计命中次数。

### D. 键盘导航
使用 ↑↓ 方向键快速切换页面。

## 4. 网络容错
所有网络请求都带有超时保护：
- 状态检查：5 秒
- OCR 调用：180 秒
- 其他请求：30 秒

Ollama 断开后 UI 不会冻结，超时后会自动恢复可操作状态并通过 Toast 弹窗通知用户。

# 六、技术架构

## 1. 后端架构

```mermaid
graph TB
    subgraph 后端服务
        API[FastAPI Server]
        DB[(SQLite)]
        Layout[PP-DocLayoutV3]
        Uploads[uploads/ 目录]
    end

subgraph 外部服务
        Ollama[Ollama GLM-OCR]
    end

API --> DB
    API --> Layout
    API --> Uploads
    API --> Ollama
```

![Folio-OCR 后端架构](https://static.op123.ren/static/f0/f066a55bbc617247.svg)

## 2. 版面分析流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant API as FastAPI
    participant L as Layout 模型
    participant O as Ollama

![版面分析流程](https://static.op123.ren/static/5d/5d31b9fc67386583.svg)

## 3. 数据库设计

![数据库结构](https://static.op123.ren/static/9e/9e7edf9cfd7fd80a.svg)

## 4. 主要依赖

# 七、部署架构

## 1. Docker Compose 配置

```mermaid
graph LR
    Host[宿主机] --> LB[Nginx/Proxy]
    LB --> App[App 容器]
    LB --> Ollama[Ollama 容器]
    App --> DB[(SQLite 数据卷)]
    App --> Files[uploads 数据卷]
```

![Docker 部署架构](https://static.op123.ren/static/b9/b951a961b921a63a.svg)

## 2. GPU 加速
若有 NVIDIA 显卡，可编辑 docker-compose.yml 取消 deploy 段落的注释以启用 GPU 加速。

```yaml
services:
  ollama:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
```

## 3. 常用 Docker 命令

# 八、性能参考

# 九、常见问题

## 1. 安装问题

### Ollama 未找到
错误信息：Ollama not found
解决方法：先安装 Ollama 并确保其在 PATH 中

```bash
# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# 从 https://ollama.com/download 下载安装包
```

### 模型下载失败
解决方法：检查网络连接，手动执行模型拉取

```bash
ollama pull glm-ocr
```

## 2. 运行问题

### OCR 超时
可能原因：图片过大或网络问题
解决方法：
- 系统已设置 180 秒超时，等待即可
- 检查 Ollama 服务是否正常运行
- 尝试重启服务

### 版面分析失败
可能原因：模型未正确加载
解决方法：
- 确保已安装 torch 和 transformers
- 检查服务器日志查看具体错误

## 3. 使用问题

### PDF 拆页不清晰
说明：系统使用 2x 缩放矩阵渲染 PDF 以保证 OCR 质量
解决方法：如需更高分辨率，可修改 server.py 中的 mat 参数

### 导出的 Word 文档格式问题
说明：DOCX 导出基于 python-docx，解析 OCR 结果中的表格和标题
解决方法：识别时确保版面分析正确检测到表格区域

# 十、项目结构

# 十一、API 端点

***

## 参考资料

Folio-OCR 三栏文档 OCR 工作台

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

搭建国内LabHub

CentOS 7.9 编译并使用rpm方式升级openssh9.6p1（包括后续更新9.8p1等）

一天从 redis 大 key 开始

安装eve-ng

重装ensp

Cloudflare Radar 2025 互联网发展回顾技术分析

MacType Windows 字体渲染增强工具技术分析

frp

更新Jumpserver版本到v3.10.4

升级openssh报错 PAM unable to dlopen(/usr/lib64/security/pam_stack.so)

Folio-OCR 三栏文档 OCR 工作台

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

Folio-OCR 三栏文档 OCR 工作台

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款