由大语言模型驱动的 PDF 转 Markdown 工具。它使用视觉模型真正“阅读”您的文档——包括表格、标题和混合布局——并输出干净、结构化的 Markdown，而非传统的 OCR 技术。

curl -X POST "http://localhost:8000/ocr" -F "file=@document.pdf"

---

演示

https://github.com/user-attachments/assets/6b39f3ea-248e-4c29-ac2e-b57de64d5d65

NASA 阿波罗 17 号飞行文档——包含多种方向和杂乱布局——被转换为结构化的 Markdown。

---

功能特点

• 视觉模型 OCR — 理解上下文，而不仅仅是字符形状
• 并行处理 — 50 页的 PDF 只需几秒即可完成，而非几分钟
• 表格保留 — 自动检测并格式化为标准的 Markdown 表格
• 智能批处理 — 可配置每请求处理的页数，以在速度与准确度之间取得平衡
• 带退避重试 — 有效应对速率限制和超时，不会导致程序崩溃
• 灵活输入 — 支持文件上传或 URL 输入，任您选择
• 图像描述 — 非文本元素会添加 [Image: description] 注释

成本

以 OpenAI 为例（平均每页约 1,500 个 token）：

模型	每 1,000 页成本
GPT-4o	~$15
GPT-4o mini	~$8
批量 API	~$4

可与任何兼容 OpenAI 的视觉 API 配合使用。只需在配置中更换端点和模型即可。

安装

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

配置

创建一个 .env 文件：

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

# 可选
OPENAI_API_VERSION=gpt-4o
BATCH_SIZE=1
MAX_CONCURRENT_OCR_REQUESTS=5
MAX_CONCURRENT_PDF_CONVERSION=4

运行

# 任选其一
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

API 的地址为 http://127.0.0.1:8000，自动生成的文档可在 /docs 访问。

使用方法

上传文件

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

从 URL 处理

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

响应

{
  "text": "# 文档标题\n\n## 第一节\n\n提取的文本...",
  "status": "success",
  "pages_processed": 5,
  "processing_time_ms": 1234
}

健康检查

curl http://127.0.0.1:8000/health

错误代码

代码	含义
200	成功
400	请求错误（未提供文件/URL，或两者都提供了）
422	验证错误
429	速率限制 — 请使用退避重试
500	处理错误
504	下载 PDF 超时

配置项

变量	默认值	描述
OPENAI_API_KEY	—	API 密钥
AZURE_OPENAI_ENDPOINT	—	端点 URL
OPENAI_DEPLOYMENT_ID	—	视觉模型部署 ID
OPENAI_API_VERSION	gpt-4o	API 版本
BATCH_SIZE	1	每次 OCR 请求处理的页数（1–10）。数值越大，速度越快，但准确度可能降低
MAX_CONCURRENT_OCR_REQUESTS	5	并发 OCR 请求数
MAX_CONCURRENT_PDF_CONVERSION	4	并发页面渲染数。建议与您的 CPU 核心数匹配

调优

• 高精度模式： BATCH_SIZE=1
• 平衡模式： BATCH_SIZE=5，MAX_CONCURRENT_OCR_REQUESTS=10
• 最大吞吐量模式： BATCH_SIZE=10，MAX_CONCURRENT_OCR_REQUESTS=20（请注意速率限制）

项目结构

swift_ocr/
  __init__.py           — 包初始化文件
  __main__.py           — CLI 入口点
  app.py                — FastAPI 应用工厂
  config/
    settings.py         — Pydantic 配置（类型安全的配置）
  core/
    exceptions.py       — 自定义异常层次结构
    logging.py          — 结构化日志记录
    retry.py            — 指数退避机制
  schemas/
    ocr.py              — Pydantic 请求/响应模型
  services/
    ocr.py              — 视觉模型 OCR 服务
    pdf.py              — PDF 转换服务
  api/
    deps.py             — 依赖注入
    exceptions.py       — FastAPI 异常处理器
    router.py           — 路由聚合
    routes/
      health.py         — 健康检查端点
      ocr.py            — OCR 端点

故障排除

问题	解决方法
环境变量缺失	检查 .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/

许可证

AGPL v3 — 由 PyMuPDF 依赖所要求。

如果您希望采用 MIT 许可证，可以将 PyMuPDF 替换为 pdf2image + Poppler。其余代码归您所有。

api-llm-ocr 快速上手指南

api-llm-ocr 是一个基于视觉大模型（Vision LLM）的 PDF 转 Markdown 工具。与传统 OCR 不同，它能理解文档上下文、识别复杂表格和混合布局，并输出结构清晰的 Markdown 文件。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：3.8 或更高
• 前置依赖：
  • Git
  • OpenAI API Key 或兼容的 Azure OpenAI 端点（需支持视觉模型，如 GPT-4o）
  • （可选）国内用户若访问 GitHub 或 PyPI 较慢，建议配置镜像源加速。

安装步骤

1. 克隆项目代码

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

2. 创建并激活虚拟环境

   python3 -m venv venv
   source venv/bin/activate
   # Windows 用户使用: venv\Scripts\activate
   

3. 安装依赖包 注：国内用户推荐使用清华或阿里镜像源加速安装

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

4. 配置环境变量 在项目根目录创建 .env 文件，填入你的 API 密钥和端点信息：

   # 必填项
   OPENAI_API_KEY=your_api_key
   AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
   OPENAI_DEPLOYMENT_ID=your_vision_model_deployment
   
   # 选填项（可根据需求调整并发和批次）
   OPENAI_API_VERSION=gpt-4o
   BATCH_SIZE=1
   MAX_CONCURRENT_OCR_REQUESTS=5
   MAX_CONCURRENT_PDF_CONVERSION=4
   

基本使用

1. 启动服务

运行以下命令启动本地 API 服务（默认端口 8000）：

uvicorn main:app --reload

服务启动后，自动生成的 API 文档可通过 http://127.0.0.1:8000/docs 查看。

2. 调用接口转换 PDF

使用 curl 上传本地 PDF 文件进行转换：

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

响应示例：

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

3. 通过 URL 处理（可选）

如果 PDF 位于公网可访问的 URL，可直接发送 JSON 请求：

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