PDF 转 Markdown 自动化工具（基于 GPT-4o）

LLM 驱动的 PDF 到 Markdown 转换

由视觉模型驱动的 PDF 到 markdown 工具。使用视觉模型真正阅读你的文档——表格、标题、混合布局——并输出干净的结构化 markdown。不是传统的 OCR。

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

NASA Apollo 17 飞行文档——混合方向、混乱的布局——转换成结构化 markdown。

视觉模型 OCR —— 理解内容，而不仅仅是字符形状

并行处理 —— 50 页 PDF 秒级完成，不是分钟级

表格保留 —— 检测并格式化为适当的 markdown 表格

智能批处理 —— 可配置的每请求页数，速度与准确度之间的权衡

重试和退避 —— 处理速率限制和超时，不会崩溃

灵活输入 —— 文件上传或 URL，由你选择

图像描述 —— 非文本元素获得 [Image: description] 注解

使用 OpenAI 作为示例

（平均每页约 1,500 tokens）：

适用于任何 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

# 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

# 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

API 位于 http://127.0.0.1:8000。自动生成的文档在 /docs。

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

curl -X POST "http://127.0.0.1:8000/ocr" \
  -H "Content-Type: application/json" \
  -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
}

curl http://127.0.0.1:8000/health

性能配置

高精度：BATCH_SIZE=1

均衡：BATCH_SIZE=5, MAX_CONCURRENT_OCR_REQUESTS=10

最大吞吐量：BATCH_SIZE=10, MAX_CONCURRENT_OCR_REQUESTS=20（注意速率限制）

项目结构

swift_ocr/
  __init__.py           — package init
  __main__.py           — CLI entry point
  app.py                — FastAPI app factory
  config/
    settings.py         — pydantic settings (type-safe config)
  core/
    exceptions.py       — custom exception hierarchy
    logging.py          — structured logging
    retry.py            — exponential backoff
  schemas/
    ocr.py              — pydantic request/response models
  services/
    ocr.py              — vision model OCR service
    pdf.py              — PDF conversion service
  api/
    deps.py             — dependency injection
    exceptions.py       — FastAPI exception handlers
    router.py           — route aggregation
    routes/
      health.py         — health check endpoints
      ocr.py            — OCR endpoints

许可证

AGPL v3 —— 由 PyMuPDF 依赖要求。

如果你需要 MIT 许可证，用 pdf2image + Poppler 替换 PyMuPDF。其余代码由你掌控。