方案简介

api-llm-ocr 是一个基于大语言模型视觉能力的 PDF 转 Markdown 服务。它与传统 OCR 的核心区别在于：不识别字符形状，而是让视觉模型（如 GPT-4o）真正“阅读”文档，从而理解上下文、混合排版、页眉页脚和表格，并输出干净的结构化 Markdown。

该项目将 PDF 页面渲染为图像后调用 OpenAI 兼容的视觉 API，通过 FastAPI 暴露 HTTP 接口，支持文件上传和 URL 两种输入方式。得益于并行处理与可配置的批处理大小，50 页 PDF 可在秒级完成转换。适合需要批量数字化复杂文档（如 NASA Apollo 17 飞行文档这类混合方向、混乱排版的资料）并保留表格结构的开发者与团队。

亮点与能力

• vision model OCR — 理解上下文，而非仅识别字符形状
• parallel processing — 50 页 PDF 秒级完成，而非分钟级
• table preservation — 表格被检测并格式化为规范的 Markdown 表格
• smart batching — 可配置每请求页数，在速度与精度间权衡
• retry with backoff — 优雅处理速率限制和超时，不崩溃
• flexible input — 支持文件上传或 URL
• image descriptions — 非文本元素以 [Image: description] 标注
• 自动生成的 API 文档位于 /docs

组成与分工

• OpenAI / GPT-4o 视觉模型：实际阅读 PDF 页面图像，理解上下文并生成结构化 Markdown；也支持任意 OpenAI 兼容视觉 API（含 Azure OpenAI 端点）
• FastAPI：Web 框架，提供 /ocr、/health 等端点，app 工厂在 swift_ocr/app.py
• uvicorn：ASGI 服务器，用于启动服务，支持多 worker
• PyMuPDF：PDF 转换服务，负责将 PDF 页面渲染为图像（AGPL 许可来源）
• pydantic：类型安全的配置与请求/响应模型
• 指数退避重试模块：处理速率限制与超时

前置要求

需要 Python 3 环境（使用 venv），以及 OpenAI/Azure OpenAI 视觉模型的 API 密钥。安装：

bash
git clone https://github.com/yigitkonur/api-llm-ocr.git
cd api-llm-ocr

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

许可证说明：项目采用 AGPL v3，由 PyMuPDF 依赖要求；若需 MIT，可将 PyMuPDF 换成 pdf2image + Poppler。

实施步骤

1. 克隆并安装依赖

bash
git clone https://github.com/yigitkonur/api-llm-ocr.git
cd api-llm-ocr

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. 配置环境变量

创建 .env 文件：

env

required

OPENAI_API_KEY=your_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
OPENAI_DEPLOYMENT_ID=your_vision_model_deployment

optional

OPENAI_API_VERSION=gpt-4o
BATCH_SIZE=1
MAX_CONCURRENT_OCR_REQUESTS=5
MAX_CONCURRENT_PDF_CONVERSION=4

3. 启动服务

bash

pick one

uvicorn main:app --reload
uvicorn swift_ocr.app:app --reload
python -m swift_ocr
python -m swift_ocr --host 0.0.0.0 --port 8080 --workers 4

4. 验证

API 运行在 http://127.0.0.1:8000，可用健康检查确认服务正常：

bash
curl http://127.0.0.1:8000/health

使用与配置要点

上传文件转换

bash
curl -X POST "http://127.0.0.1:8000/ocr" \
-F "file=@/path/to/document.pdf"

通过 URL 处理

bash
curl -X POST "http://127.0.0.1:8000/ocr" \
-H "Content-Type: application/" \
-d '{"url": "https://example.com/document.pdf"}'

响应结构

{
"text": "# document title\n\n## section 1\n\nextracted text...",
"status": "success",
"pages_processed": 5,
"processing_time_ms": 1234
}

调优建议

• 高精度：BATCH_SIZE=1
• 均衡：BATCH_SIZE=5, MAX_CONCURRENT_OCR_REQUESTS=10
• 最大吞吐：BATCH_SIZE=10, MAX_CONCURRENT_OCR_REQUESTS=20（注意限流）

MAX_CONCURRENT_PDF_CONVERSION 默认 4，建议匹配 CPU 核心数。成本参考：GPT-4o 约 $15/千页，GPT-4o mini 约 $8/千页，batch API 约 $4/千页。

注意事项与常见问题

• 缺少环境变量：检查 .env 是否包含 OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、OPENAI_DEPLOYMENT_ID
• 429 限流：降低 MAX_CONCURRENT_OCR_REQUESTS 或 BATCH_SIZE
• 超时：大 PDF 耗时较长，内置退避机制
• 输出乱码：确保 PDF 未加密或损坏
• 表格错乱：复杂表格尝试 BATCH_SIZE=1
• 客户端初始化失败：核对端点格式 https://your-resource.openai.azure.com/
• 错误码：400（无文件/URL 或两者都提供）、429（限流，需退避重试）、504（下载 PDF 超时）

优缺点

• ✓ 50页PDF秒级完成，表格保留为Mark
• ✓ 支持任意OpenAI兼容视觉API，可换
• ✕ AGPL v3 许可证受 PyMuPDF
• ✕ 高并发需注意429限流

出处

本方案挖掘自开源项目 yigitkonur/api-llm-ocr，方案内容与实施命令均来自其 README 原文。