Folio-OCR

基于 GLM-OCR + Ollama 的三栏文档 OCR 工作台，专为书籍和文档的日常批量识别设计。

2026-05-28 · v3.3.1 已发布：默认增大 Ollama OCR 请求上下文，规避 GLM-OCR 的 GGML_ASSERT 崩溃；v3.3.0 已修复表格导出并新增 EPUB。查看 Release Notes。

功能特性

OCR 核心

• 支持多种图片格式：PNG、JPG、GIF、BMP
• 支持 PDF 文件（PyMuPDF 2x 高分辨率拆页）
• 多文件混合上传（图片 + PDF 混选）
• 版面分析（Layout Detection）自动分区识别
• 相邻文本区域智能合并，减少 OCR 调用次数（11 区域 → 3 组，2.5x 加速）
• LaTeX 特殊字符自动转 Unicode（$\textcircled{1}$ → ①）
• 模型输出自动清理 ```markdown ``` 围栏

批量处理

• 一键「OCR All Pages」批量识别全部页面
• 实时进度条 + ETA 时间估算
• 随时可停（Stop 按钮立即中断当前请求）
• 选中页面时自动预识别下一页（Pre-OCR）

编辑与导出

• Edit / Preview 双模式切换
• Preview 模式原生渲染 HTML 表格和 Markdown
• 段落重排（Reflow）：合并因换行断开的段落
• 导出四种格式：.md（Markdown）、.txt（纯文本）、.docx（Word）、.epub（电子书）
• DOCX 导出基于 python-docx，真实 Word 文档，含分节符和页码
• 单页/全文一键复制

数据持久化

• SQLite 数据库（folio_ocr.db），文档和 OCR 结果服务重启不丢失
• 编辑内容 800ms 防抖自动保存
• 页面加载时自动恢复上次打开的文档
• 多文档管理：左侧面板上方文档列表，支持切换和删除

界面交互

• 三栏布局：页面缩略图 | 图片预览 | OCR 结果
• 右侧面板可拖拽调整宽度
• SSE 流式上传，逐页实时加载
• 版面区域双向高亮（点击图片框 ↔ 点击文本块）
• 全文搜索（Ctrl+F），跨页高亮 + 命中计数
• 键盘导航（↑↓ 切换页面）
• 暖色奶油/炭灰主题，中文字体适配

网络容错

• 所有网络请求带超时保护（按场景分档：5s ~ 180s）
• Toast 弹窗通知：保存失败、OCR 超时、加载错误等即时反馈
• Ollama 断开后 UI 不会冻住，超时后自动恢复可操作状态

快速开始（Docker 一键部署）

只需装好 Docker，三条命令搞定：

# 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

完成后打开浏览器访问 http://localhost:3000 即可使用。

有 NVIDIA 显卡？ 编辑 docker-compose.yml，取消 deploy: 段落的注释即可启用 GPU 加速。

常用 Docker 命令：

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

默认配置会让版面分析模型跑在 CPU 上，把 GPU 显存优先留给 Ollama。需要调整时可设置：

LAYOUT_DEVICE=cpu   # 默认值，最稳妥
LAYOUT_DEVICE=auto  # 有 CUDA 时自动把版面分析模型放到 GPU
LAYOUT_DEVICE=cuda  # 强制使用 CUDA，不可用时启动失败

Folio-OCR 默认会给 Ollama 请求传入 OLLAMA_NUM_CTX=16384，避免 GLM-OCR 处理图片时因上下文太小触发底层 RoPE / KV cache 错误。内存非常紧张时可以调小，复杂图片或高分辨率扫描件建议保持默认或调大。

本地部署（不用 Docker）

环境要求

• Python 3.10+
• Ollama 已安装且 ollama 在 PATH 中

安装和启动

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

# 拉取模型
ollama pull glm-ocr

# 启动服务
python server.py

# 或使用热重载开发
uvicorn server:app --reload --host 0.0.0.0 --port 3000

# Windows 一键启动
start.bat

服务启动后访问：http://localhost:3000

项目结构

glmocr/
├── 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 编排
├── .dockerignore        # Docker 构建排除列表
├── start.bat            # Windows 启动脚本
├── folio_ocr.db         # SQLite 数据库（运行时生成）
└── uploads/             # 上传文件目录（运行时生成）

API 端点

性能参考

• 模型冷启动首次请求：~50s
• 后续单页识别：~0.5s
• PDF 以 2x 缩放矩阵渲染，保证 OCR 质量

常见问题

Ollama 报 model failed to load

这通常是 Ollama 侧模型没有成功加载，常见原因是模型未拉取、内存/显存不足，或 GPU 资源被其他进程占用。

排查顺序：

docker compose exec ollama ollama pull glm-ocr
docker compose logs -f ollama

如果本地源码运行时遇到显存紧张，保持默认的 LAYOUT_DEVICE=cpu，让版面分析模型使用 CPU，把 GPU 留给 Ollama。若已经设置过 LAYOUT_DEVICE=auto 或 LAYOUT_DEVICE=cuda，可以改回：

LAYOUT_DEVICE=cpu python server.py

Ollama 报 GGML_ASSERT(a->ne[2] * 4 == b->ne[0]) failed

这是 GLM-OCR / Ollama 在图片 OCR 时可能触发的底层上下文错误。Folio-OCR 从 v3.3.1 起默认给 /api/chat 请求设置：

{
  "options": {
    "num_ctx": 16384
  }
}

如果仍然复现，可以尝试调大上下文或降低输入图片分辨率：

OLLAMA_NUM_CTX=24576 python server.py

单次最多能处理多少张图片？

Folio-OCR 没有写死单次页数上限；上传的图片和 PDF 页会按顺序写入 SQLite 和 uploads/，OCR 也是逐页执行。实际上限主要取决于磁盘空间、浏览器页面数量和 Ollama 的稳定性。大文档建议先按 20-50 页一批处理，确认环境稳定后再扩大批量。

License

MIT