文档处理与 OCR

系统提供 4 种文档处理选项：

• RapidOCR: CPU 友好，无需 GPU，适合基础文字识别
• MinerU: 本地化高精度 VLM 解析，适合复杂 PDF 和表格文档
• MinerU Official: 官方云服务 API，无需本地部署，开箱即用
• PaddleX: 结构化解析，适合表格、票据等特殊格式

支持的文件类型

常规文档格式

• 文本文档: .txt, .md, .html, .htm
• Word 文档: .doc, .docx
• PDF 文档: .pdf
• 电子表格: .csv, .xls, .xlsx
• JSON 数据: .json

图像格式（需要 OCR）

• 常见图片: .jpg, .jpeg, .png, .bmp, .tiff, .tif, .gif, .webp

ZIP 压缩包

• ZIP 文档: .zip - 支持包含 Markdown 文件和图片的压缩包
  • 自动提取和处理 ZIP 包中的 .md 文件
  • 自动处理 ZIP 包中的图片文件并上传到对象存储
  • 图片链接会自动替换为可访问的 URL
  • 优先处理名为 full.md 的文件，否则使用第一个 .md 文件
  • 支持图片目录的智能识别（images/、../images/ 等）

快速配置

1. 基础 OCR (RapidOCR)

# 下载模型
hf download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR

# 启动服务
docker compose up -d api

2. 高精度 OCR (MinerU)

需要在 .env 文件中配置：

MINERU_VL_SERVER=http://localhost:30000
MINERU_API_URI=http://localhost:30001

然后启动相关服务

# 需要 GPU，启动 MinerU 服务
docker compose up -d mineru-vllm-server mineru-api

# 启动主服务
docker compose up -d api

3. 官方云服务 (MinerU Official)

API 密钥可以从 MinerU 官网 申请。

然后在 .env 文件中添加

# 设置 API 密钥环境变量
MINERU_API_KEY="your-api-key-here"

然后使用 docker compose up -d api 重启后端服务。

4. 结构化解析 (PaddleX)

# 需要 GPU，启动 PaddleX 服务
docker compose up -d paddlex

# 启动主服务
docker compose up -d api

处理器选择

处理器	适用场景	硬件要求	特点
RapidOCR	基础文字识别	CPU	速度快，资源占用低
MinerU	复杂 PDF、表格、公式	GPU	精度高，版面分析好
MinerU Official	复杂文档解析（云服务）	无特殊要求	官方云服务，开箱即用，有 API 配额
PaddleX	表格、票据、结构化文档	GPU	专业版面解析

参数说明

enable_ocr 选项

• disable: 不启用 OCR（PDF 按文本提取，图片必须选择 OCR 方式）
• onnx_rapid_ocr: RapidOCR 处理
• mineru_ocr: MinerU HTTP API 处理
• mineru_official: MinerU 官方云服务 API 处理
• paddlex_ocr: PaddleX 处理

注意事项

• 图片文件必须启用 OCR，否则无法提取内容
• MinerU 和 PaddleX 需要 GPU 支持
• MinerU Official 需要设置 MINERU_API_KEY 环境变量
• RapidOCR 适合 CPU 环境和基础识别需求

故障排除

常见问题

1. RapidOCR 模型不存在

   # 下载模型
   huggingface-cli download SWHL/RapidOCR --local-dir ./models/SWHL/RapidOCR

2. GPU 服务连接失败

   # 检查服务状态
   docker compose ps
   
   # 查看日志
   docker compose logs mineru

3. 健康检查

   # 检查所有 OCR 服务状态
   curl http://localhost:5050/system/health/ocr-services

批量处理脚本

系统提供便捷的批量处理脚本，用于高效批量上传文档。

文件上传脚本

使用 scripts/batch_upload.py 批量上传文件到知识库：

# 批量上传文档（多种格式）
uv run scripts/batch_upload.py \
    --db-id kb_b2730ad6801b149694021106c7eddd38 \
    --directory data.nogit/农业农村局 \
    --pattern "*.docx" --pattern "*.txt" --pattern "*.html" \
    --base-url http://172.19.13.6:5050/api \
    --username admin \
    --password admin123 \
    --batch-size 20 \
    --wait-for-completion \
    --poll-interval 5 \
    --recursive \
    --enable-ocr mineru_ocr \ # mineru_official, paddlex_ocr, onnx_rapid_ocr
    --record-file scripts/tmp/batch_processed_files_1029.txt

参数说明:

• --db-id: 目标知识库 ID
• --directory: 文件目录路径
• --pattern: 文件匹配模式，可以多次指定以支持多种格式（例如：--pattern "*.docx" --pattern "*.pdf" --pattern "*.html"）
• --batch-size: 每批处理的文件数量（默认20）
• --wait-for-completion: 是否等待任务完成再处理下一批（默认开启）
• --poll-interval: 任务状态检查间隔，单位秒（默认5秒）
• --recursive: 递归处理子目录
• --record-file: 处理记录文件路径

注意事项:

• 系统按"内容哈希"进行去重；同一知识库已存在相同内容的文件会被拒绝（409）
• 建议根据系统性能调整批次大小
• 大量文件处理时建议开启分批等待功能
• 先上传后处理的机制更稳定，适合大批量文档导入