Paper Burner-X开发者指南：从API集成到自定义OCR引擎配置

【免费下载链接】Burner-X Paper Burner - PDF文档OCR与翻译工具 项目地址: https://gitcode.com/gh_mirrors/pap/Burner-X

Paper Burner-X（简称pap）是一款功能强大的PDF文档OCR与翻译工具，为开发者提供了丰富的API接口和灵活的OCR引擎配置选项。本指南将帮助开发者快速掌握从API集成到自定义OCR引擎配置的全过程，轻松构建属于自己的文档处理解决方案。

快速部署与环境配置

前置要求

• Docker 和 Docker Compose
• 或者 Node.js 20+ 和 PostgreSQL 16+

Docker Compose部署（推荐）

1. 克隆项目仓库

git clone https://gitcode.com/gh_mirrors/pap/Burner-X
cd Burner-X

2. 配置环境变量

cp .env.example .env

编辑.env文件，修改关键配置：

# 数据库密码（必改）
DB_PASSWORD=your_secure_password_here

# JWT 密钥（必改，至少32字符）
JWT_SECRET=your_super_secret_jwt_key_min_32_chars

# API Keys 加密密钥（必改，至少32字符）
ENCRYPTION_SECRET=your_encryption_secret_min_32_chars

3. 启动服务

docker-compose up -d

4. 验证部署 访问以下地址验证服务是否正常运行：

• 应用主页：http://localhost:3000
• 管理面板：http://localhost:3000/admin
• API 健康检查：http://localhost:3000/api/health

API集成详解

认证机制

所有需要认证的API端点都需要在请求头中包含JWT Token：

Authorization: Bearer <token>

核心API接口

文档管理API

• 获取文档列表

GET /api/documents?page=1&limit=20&status=COMPLETED

• 创建文档记录

POST /api/documents
Content-Type: application/json

{
  "fileName": "paper.pdf",
  "fileSize": 1024000,
  "fileType": "pdf",
  "status": "PENDING"
}

• 获取文档详情

GET /api/documents/:id

用户设置API

• 更新用户设置

PUT /api/user/settings
Content-Type: application/json

{
  "ocrProvider": "mineru",
  "translationModel": "deepseek",
  "targetLanguage": "chinese",
  ...
}

API Keys管理

• 添加API Key

POST /api/user/api-keys
Content-Type: application/json

{
  "provider": "deepseek",
  "keyValue": "sk-...",
  "remark": "备用密钥",
  "order": 1
}

API使用示例

JavaScript示例

// 登录
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});
const { token } = await loginResponse.json();

// 创建文档
const createResponse = await fetch('/api/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fileName: 'paper.pdf',
    fileSize: 1024000,
    fileType: 'pdf',
    status: 'PENDING'
  })
});
const newDoc = await createResponse.json();

cURL示例

# 登录
TOKEN=$(curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@paperburner.local","password":"admin123456"}' \
  | jq -r '.token')

# 创建API Key
curl -X POST http://localhost:3000/api/user/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"deepseek","keyValue":"sk-...","remark":"主密钥"}'

OCR引擎配置指南

支持的OCR服务提供商

Paper Burner-X支持多种OCR服务提供商，包括：

• MinerU
• Doc2X
• 本地OCR适配器

配置OCR引擎

1. 通过API配置默认OCR提供商

PUT /api/user/settings
Content-Type: application/json

{
  "ocrProvider": "mineru",
  ...
}

2. 添加OCR服务API Key

POST /api/user/api-keys
Content-Type: application/json

{
  "provider": "mineru",
  "keyValue": "your-mineru-api-key",
  "remark": "OCR服务密钥",
  "order": 0
}

自定义OCR引擎开发

Paper Burner-X提供了OCR适配器接口，允许开发者集成自定义OCR引擎。相关代码位于：js/process/ocr-adapters/

1. 创建自定义OCR适配器，继承BaseAdapter

// 参考本地适配器实现: [js/process/ocr-adapters/local-adapter.js](https://link.gitcode.com/i/f7b7b27a23428884a03edf50e6dd8c9c)
class CustomOCRAdapter extends BaseAdapter {
  async process(imageData) {
    // 实现自定义OCR处理逻辑
  }
}

2. 注册自定义适配器

// 在OCR管理器中注册: [js/process/ocr-manager.js](https://link.gitcode.com/i/e57b30f5dc45361f96a2d8d8cdc0ae36)
ocrManager.registerAdapter('custom', CustomOCRAdapter);

3. 在设置中选择自定义OCR引擎

PUT /api/user/settings
Content-Type: application/json

{
  "ocrProvider": "custom",
  ...
}

高级功能与最佳实践

术语库管理

创建和管理专业术语库，提高翻译准确性：

POST /api/user/glossaries
Content-Type: application/json

{
  "name": "医学术语",
  "enabled": true,
  "entries": [
    {"source": "protein", "target": "蛋白质"},
    {"source": "cell", "target": "细胞"}
  ]
}

文档标注功能

为处理后的文档添加标注和注释：

POST /api/documents/:id/annotations
Content-Type: application/json

{
  "type": "highlight",
  "color": "#ffff00",
  "startIndex": 100,
  "endIndex": 200,
  "text": "高亮文本",
  "note": "我的笔记"
}

性能优化建议

• 使用语义分组功能提高翻译效率：js/chatbot/core/semantic-groups-manager.js
• 配置缓存策略减少重复处理：server/src/utils/cache.js
• 调整分块大小优化大文件处理：js/processing/sub_block_segmenter.js

常见问题与故障排除

数据库连接失败

问题: Error: connect ECONNREFUSED

解决:

• 检查PostgreSQL是否运行
• 检查DATABASE_URL配置是否正确
• 确认数据库端口没有被占用

OCR处理失败

解决:

• 检查API Key是否有效
• 验证OCR提供商服务状态
• 查看日志文件：server/src/utils/logger.js

配额管理

查看和更新用户配额：

# 获取用户配额
GET /api/admin/users/:userId/quota

# 更新用户配额
PUT /api/admin/users/:userId/quota
Content-Type: application/json

{
  "maxDocumentsPerMonth": 200,
  "maxStorageSize": 2048
}

总结

Paper Burner-X为开发者提供了强大而灵活的PDF文档OCR与翻译解决方案。通过本指南，您已经了解了如何部署系统、集成API以及配置自定义OCR引擎。更多高级功能和详细文档，请参考：

• 完整API文档：tests/API_REFERENCE.md
• 部署指南：deploy/DEPLOYMENT_GUIDE.md
• 性能优化计划：docs/PERFORMANCE_OPTIMIZATION_PLAN.md

通过这些工具和资源，您可以轻松构建满足特定需求的文档处理应用，提升工作效率并拓展更多可能性。

【免费下载链接】Burner-X Paper Burner - PDF文档OCR与翻译工具 项目地址: https://gitcode.com/gh_mirrors/pap/Burner-X