ocrbase

大规模将 PDF 转换为结构化数据。由前沿的开源 OCR 模型驱动。

快速入门

试用 Playground

在 ocrbase.dev 上，您可以免费解析和提取最多 1000 页的文档数据。

云 API

1. 在 ocrbase.dev 生成一个 API 密钥。

2. 将其添加到您的 .env 文件中：

   OCRBASE_API_KEY=sk_xxx
   

3. 安装 SDK：

   npm install ocrbase-sdk
   

4. 解析文档：

   import { parse } from 'ocrbase-sdk';
   
   const { text } = await parse('./invoice.pdf');
   console.log(text);
   

或者直接使用 curl 调用 API：

curl -X POST https://api.ocrbase.dev/v1/parse \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@document.pdf"

自托管

先决条件：Bun、Docker Desktop

git clone https://github.com/majcheradam/ocrbase
cd ocrbase
bun install
cp .env.example .env     # 然后编辑 .env — 将 PADDLE_OCR_URL 设置为您的 PaddleOCR 实例
docker compose up -d     # 启动 postgres、redis、minio
bun run db:push          # 初始化数据库
bun run dev              # 启动 API 服务器 + 工作进程

API 将在 http://localhost:3000 提供服务。有关 PaddleOCR 的设置、GPU 配置以及所有环境变量，请参阅 自托管指南。

工作原理

ocrbase 有两个核心操作。两者都是异步的——您提交请求，获取作业 ID，并在结果准备好时检索。

解析 (POST /v1/parse)

将 PDF 转换为 Markdown 格式。上传文件后，ocrbase 会 OCR 每一页，并返回干净的 Markdown 文本。

curl -X POST https://api.ocrbase.dev/v1/parse \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@document.pdf"

提取 (POST /v1/extract)

将 PDF 转换为结构化的 JSON 数据。您提供文件和模式 ID，ocrbase 会对文档进行 OCR 处理，然后使用 LLM 提取符合您模式的数据。

curl -X POST https://api.ocrbase.dev/v1/extract \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@invoice.pdf" \
  -F "schemaId=inv_schema_123"

检查结果

轮询——不断查询作业状态，直到完成：

curl https://api.ocrbase.dev/v1/jobs/job_xxx \
  -H "Authorization: Bearer sk_xxx"

WebSocket——订阅实时状态更新，无需轮询：

wscat -c "wss://api.ocrbase.dev/v1/realtime?job_id=job_xxx" \
  -H "Authorization: Bearer sk_xxx"

功能

• 一流的 OCR——使用 PaddleOCR-VL-1.5 0.9B 从 PDF 中准确提取文本。
• 结构化提取——定义 JSON 模式，即可从任何文档中获取结构化数据。
• 为规模化设计——基于队列的任务处理，采用 BullMQ，可处理数千份文档。
• 实时更新——通过 WebSocket 通知作业进度，无需轮询。
• 可自托管——使用 Docker 在您自己的基础设施上运行整个堆栈。

SDK

从 npm 安装 TypeScript SDK：

npm install ocrbase-sdk

ocrbase-sdk 在 npm 上 | GitHub 源代码

SDK 提供类型安全的方法，用于解析、提取、模式管理以及实时 WebSocket 订阅。

API 参考

• 交互式 OpenAPI UI：https://api.ocrbase.dev/openapi
• OpenAPI JSON：https://api.ocrbase.dev/openapi/json

LLM 集成

在将文档发送给 LLM 之前，先使用 ocrbase 进行解析。原始 PDF 二进制数据会浪费 token 并导致较差的结果——而使用 ocrbase 提供的干净 Markdown 格式，则可以在成本大幅降低的情况下获得更好的 LLM 输出。

架构

技术栈

层级	技术
运行时	Bun
API 框架	Elysia
SDK	Eden Treaty
数据库	PostgreSQL + Drizzle ORM
队列	Redis + BullMQ
存储	S3/MinIO
OCR	PaddleOCR-VL 1.5
认证	Better-Auth
构建	Turborepo

自托管

请参阅 自托管指南，了解完整的部署流程，包括 PaddleOCR 的设置、所有环境变量以及 API 端点参考。

要求： Bun、Docker Desktop

健康检查

• GET /v1/health/live——存活检查
• GET /v1/health/ready——就绪检查（确认所有依赖项已连接）

星标历史

许可证

MIT——详情请参阅 LICENSE。

联系方式

如需 API 访问权限、本地部署或有任何疑问，请联系：adammajcher20@gmail.com

ocrbase 快速上手指南

ocrbase 是一个基于前沿开源 OCR 模型的大规模 PDF 转结构化数据工具。它支持将 PDF 转换为 Markdown 或根据 Schema 提取结构化 JSON，适用于文档解析、发票处理及 LLM 预处理等场景。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux / macOS / Windows (需安装 Docker Desktop)
• 运行时依赖：
  • Bun (推荐用于本地开发和自托管)
  • Docker Desktop (用于运行数据库、缓存和存储组件)
• 网络要求：能够访问 ocrbase.dev (云端 API) 或拉取相关 Docker 镜像。

注意：国内开发者若使用云端 API，请注意网络连通性；若选择自托管，需确保能拉取 Docker Hub 镜像或配置国内镜像加速源。

安装步骤

您可以选择直接使用云端 API（最快上手）或本地自托管。

方案一：使用云端 API (推荐新手)

1. 获取 API Key 访问 ocrbase.dev 注册并生成 API Key。

2. 配置环境变量 在项目根目录创建 .env 文件：

   OCRBASE_API_KEY=sk_xxx
   

3. 安装 SDK 使用 npm 安装 TypeScript SDK：

   npm install ocrbase-sdk
   

方案二：本地自托管 (Self-hosted)

适合需要数据隐私保护或大规模离线处理的场景。

1. 克隆项目

   git clone https://github.com/majcheradam/ocrbase
   cd ocrbase
   

2. 安装依赖

   bun install
   

3. 配置环境 复制示例配置文件并编辑（需设置 PADDLE_OCR_URL 指向您的 PaddleOCR 实例）：

   cp .env.example .env
   # 请使用编辑器修改 .env 文件
   

4. 启动基础设施 使用 Docker Compose 启动 PostgreSQL, Redis 和 MinIO：

   docker compose up -d
   

5. 初始化数据库并启动服务

   bun run db:push
   bun run dev
   

   启动后，API 服务将运行在 http://localhost:3000。

基本使用

1. 使用 SDK 解析 PDF (Node.js/TypeScript)

这是最简单的用法，将 PDF 转换为干净的 Markdown 文本。

import { parse } from "ocrbase-sdk";

const { text } = await parse("./invoice.pdf");
console.log(text);

2. 直接使用 curl 调用 API

如果您不使用 SDK，可以直接通过 HTTP 请求调用。

解析为 Markdown：

curl -X POST https://api.ocrbase.dev/v1/parse \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@document.pdf"

提取结构化数据 (需预先定义 Schema)：

curl -X POST https://api.ocrbase.dev/v1/extract \
  -H "Authorization: Bearer sk_xxx" \
  -F "file=@invoice.pdf" \
  -F "schemaId=inv_schema_123"

3. 获取任务结果

ocrbase 的核心操作是异步的。提交请求后会返回一个 job_id，您可以通过以下方式获取结果：

轮询检查状态：

curl https://api.ocrbase.dev/v1/jobs/job_xxx \
  -H "Authorization: Bearer sk_xxx"

或使用 WebSocket 实时订阅：

wscat -c "wss://api.ocrbase.dev/v1/realtime?job_id=job_xxx" \
  -H "Authorization: Bearer sk_xxx"

---

更多高级功能（如自定义 Schema 管理、GPU 配置详解）请参考官方 Self-Hosting Guide。