pdf-ocr-skill

Name: pdf-ocr-skill
Author: yejinlei

github.com/yejinlei文档处理13439 次安装27 周前更新

代码仓库

关于 pdf-ocr-skill

PDF OCR Skill 为使用 AI IDE 或脚本处理文档的人提取扫描版 PDF 和图片中的文字。它提供四种可选引擎，从本地 OCR 到硅基流动 API，并可生成结构化识别结果。

主要功能

01识别扫描版 PDF 和图片
02支持 RapidOCR、RapidDoc、PaddleOCR、硅基流动四种引擎
03识别中文和英文文字
04转换 PDF 页面并批量处理
05RapidDoc 版面、表格和公式分析

适用场景

01提取扫描合同或报告中的文字
02识别截图和扫描图片中的文字
03批量处理扫描版 PDF
04比较本地与云端 OCR 结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/yejinlei/pdf-ocr-skill --skill pdf-ocr

安装后在 Claude Code 中输入/pdf-ocr确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.env.example

LICENSE.txt

.gitignore

setup.py

README.md

MANIFEST.in

发布指南.md

requirements.txt

发布检查清单.md

scripts/

__init__.py

pdf_ocr_processor.py

详细介绍

PDF OCR Skill

中文版本

PDF OCR技能用于从影印版PDF文件和图片文件中提取文字内容。该技能支持两种OCR引擎：

RapidOCR（本地引擎）：无需API密钥，免费使用，识别速度快
硅基流动大模型（云端引擎）：使用AI大模型进行高精度OCR识别

功能特性

支持影印版PDF文件的文字提取
支持多种图片格式的文字识别（JPG、PNG、BMP、GIF、TIFF、WEBP）
四引擎支持：RapidOCR（本地）、RapidDoc（增强）、PaddleOCR（本地）和硅基流动API（云端）
支持中文和英文文字识别
保持文字的顺序和结构
自动将PDF页面转换为图片进行识别
智能引擎切换：当RapidOCR初始化失败时自动切换到硅基流动API

安装

依赖要求

pip install pymupdf pillow requests python-dotenv

可选依赖（推荐）

安装RapidOCR以获得本地识别能力：

pip install rapidocr_onnxruntime

环境变量配置

复制 .env.example 文件并重命名为 .env
根据需要配置以下选项：

# OCR引擎选择
# - "rapid": 使用RapidOCR本地引擎（默认，无需API密钥）
# - "rapidoc": 使用RapidDoc增强引擎（无需API密钥）
# - "paddle": 使用PaddleOCR本地引擎（无需API密钥）
# - "siliconflow": 使用硅基流动API引擎（需要API密钥）
OCR_ENGINE=rapid

# 如果使用硅基流动API引擎，需要配置以下选项：
SILICON_FLOW_API_KEY=your_api_key_here
SILICON_FLOW_OCR_MODEL=deepseek-ai/DeepSeek-OCR

快速开始

使用默认引擎（RapidOCR本地识别）

# 导入OCR处理器
from scripts.pdf_ocr_processor import PDFOCRProcessor

# 创建处理器实例（默认使用RapidOCR）
processor = PDFOCRProcessor()

# 执行PDF OCR识别
result = processor.ocr_pdf('path/to/your/scanned.pdf')

# 获取识别结果
print(f"识别完成，共 {result['page_count']} 页")
print(f"使用引擎: {result['engine']}")
print(result['text'])

使用硅基流动API引擎

# 导入OCR处理器
from scripts.pdf_ocr_processor import PDFOCRProcessor

# 创建处理器实例，指定使用硅基流动API
processor = PDFOCRProcessor(engine="siliconflow")

# 执行PDF OCR识别
result = processor.ocr_pdf('path/to/your/scanned.pdf')

# 获取识别结果
print(f"识别完成，共 {result['page_count']} 页")
print(result['text'])

识别图片文件

# 导入OCR处理器
from scripts.pdf_ocr_processor import PDFOCRProcessor

# 创建处理器实例
processor = PDFOCRProcessor()  # 或 PDFOCRProcessor(engine="siliconflow")

# 执行图片OCR识别
result = processor.ocr_image_file('path/to/your/image.jpg')

# 获取识别结果
print(f"识别结果: {result['text']}")

命令行使用

# 使用默认RapidOCR引擎
python pdf_ocr_processor.py your_document.pdf

# 使用硅基流动API引擎
python pdf_ocr_processor.py your_document.pdf siliconflow

# 使用RapidDoc增强引擎
python pdf_ocr_processor.py your_document.pdf rapidoc

# 使用PaddleOCR引擎
python pdf_ocr_processor.py your_document.pdf paddle

进阶使用示例

批量处理多个PDF文件

import os
from scripts.pdf_ocr_processor import PDFOCRProcessor

# 创建处理器实例
processor = PDFOCRProcessor()

# 批量处理目录中的所有PDF文件
pdf_dir = "path/to/pdf/files"
output_dir = "path/to/output"
os.makedirs(output_dir, exist_ok=True)

for pdf_file in os.listdir(pdf_dir):
    if pdf_file.endswith('.pdf'):
        pdf_path = os.path.join(pdf_dir, pdf_file)
        output_path = os.path.join(output_dir, f"{os.path.splitext(pdf_file)[0]}.txt")
        
        print(f"处理文件: {pdf_file}")
        try:
            result = processor.ocr_pdf(pdf_path)
            
            # 保存识别结果到文本文件
            with open(output_path, 'w', encoding='utf-8') as f:
                f.write(f"=== PDF OCR 识别结果 ===\n")
                f.write(f"文件名: {pdf_file}\n")
                f.write(f"页数: {result['page_count']}\n")
                f.write(f"使用引擎: {result['engine']}\n\n")
                f.write(result['text'])
            
            print(f"处理完成，结果已保存到: {output_path}")
        except Exception as e:
            print(f"处理失败: {e}")

混合使用两种引擎

from scripts.pdf_ocr_processor import PDFOCRProcessor

def process_with_best_engine(pdf_path):
    """尝试使用RapidOCR，如果效果不佳则使用硅基流动API"""
    # 首先使用RapidOCR本地引擎
    rapid_processor = PDFOCRProcessor(engine="rapid")
    rapid_result = rapid_processor.ocr_pdf(pdf_path)
    
    # 简单评估识别效果（例如：检查识别出的文本长度）
    text_length = len(rapid_result['text'])
    
    if text_length < 100:  # 如果识别出的文本太短，可能效果不佳
        print("RapidOCR识别效果可能不佳，尝试使用硅基流动API...")
        silicon_processor = PDFOCRProcessor(engine="siliconflow")
        silicon_result = silicon_processor.ocr_pdf(pdf_path)
        return silicon_result
    else:
        return rapid_result

# 使用示例
result = process_with_best_engine('path/to/your/document.pdf')
print(f"识别完成，使用引擎: {result['engine']}")
print(result['text'])

支持的文件格式

PDF文件: .pdf
图片文件: .jpg, .jpeg, .png, .bmp, .gif, .tiff, .webp

输出格式

{
    "text": "识别的完整文本内容",
    "page_count": 页数,  # 图片文件始终为1
    "engine": "rapid" | "rapidoc" | "paddle" | "siliconflow"  # 使用的OCR引擎
}

使用场景

处理扫描版合同、协议等文档
提取影印版书籍、报告中的文字
处理无法直接复制文字的PDF文件
批量处理扫描版PDF文档
识别截图、扫描件等图片中的文字
处理手写体或印刷体图片文字识别

注意事项

RapidOCR引擎：
- 完全免费，无需网络连接
- 首次使用会自动下载模型文件
- 识别速度取决于CPU性能
硅基流动API引擎：
- 需要有效的API密钥
- 可能会产生费用
- 识别速度取决于文件页数、图片大小和网络状况
RapidDoc引擎：
- 完全免费，无需网络连接
- 支持版面分析、表格识别、公式识别和阅读顺序恢复
- 提供更结构化的输出，包括Markdown格式
- 处理时间可能比RapidOCR长，因为需要进行额外的分析
PaddleOCR引擎：
- 完全免费，无需网络连接
- 使用PP-OCRv5模型，具有较高的识别准确率
- 首次使用会自动下载模型文件
- 支持多种语言和场景的文字识别
对于复杂的扫描版PDF或图片，识别准确率可能会有所不同
建议使用高清晰度的扫描版PDF或图片以获得更好的识别效果

触发使用不同引擎的提示词

在与 AI IDE 中的助手交互时，您可以使用以下提示词来指定使用不同的 OCR 引擎：

📍 触发 RapidOCR（本地引擎）的提示词

"使用本地 OCR 引擎处理这个 PDF"
"用 RapidOCR 识别这个文件"
"本地处理，不需要 API"
"快速识别这个文档"
"离线处理这个 PDF"
"不使用硅基流动 API，用本地引擎"

📍 触发硅基流动 API（云端引擎）的提示词

"使用硅基流动 API 处理这个 PDF"
"用大模型 OCR 识别这个文件"
"高精度识别这个文档"
"处理复杂的扫描件"
"用云端 OCR 引擎"
"使用 AI 大模型识别"

📍 触发 RapidDoc（增强引擎）的提示词

"使用 RapidDoc 处理这个 PDF"
"用增强 OCR 识别这个文件"
"处理带有版面分析的 PDF"
"提取带有表格识别的文本"
"用 RapidDoc 获得更好的格式"
"增强 OCR 与版面分析"

📍 触发 PaddleOCR（本地引擎）的提示词

"使用 PaddleOCR 处理这个 PDF"
"用 PaddleOCR 识别这个文件"
"使用 PP-OCRv5 模型识别"
"用 PaddleOCR 进行高精度识别"
"PaddleOCR 本地处理"
"使用 PaddleOCR 引擎提取文字"

📍 示例对话

示例 1：使用本地引擎

用户：帮我处理这个扫描版 PDF，用本地 OCR 引擎快速识别
助手：好的，我将使用 RapidOCR 本地引擎为您处理。请提供 PDF 文件路径。

示例 2：使用云端引擎

用户：这个 PDF 包含手写体，需要高精度识别，用硅基流动 API
助手：理解，我将使用硅基流动 API 大模型为您处理。请提供 PDF 文件路径和您的 API 密钥（如果尚未配置）。

示例 3：自动选择

用户：帮我识别这个 PDF，选择最合适的引擎
助手：我将默认使用 RapidOCR 本地引擎为您处理。如果识别效果不理想，我们可以尝试使用硅基流动 API。

🔧 技术实现

当 AI 助手接收到这些提示词时，会：

解析用户意图，确定要使用的引擎
调用 PDFOCRProcessor(engine="rapid")、PDFOCRProcessor(engine="rapidoc")、PDFOCRProcessor(engine="paddle") 或 PDFOCRProcessor(engine="siliconflow")
执行 OCR 识别并返回结果

🎯 最佳实践

明确指定引擎：如果您对引擎有特定要求，最好在提示词中明确说明
提供上下文：说明文档类型（如手写体、复杂格式等）有助于助手选择合适的引擎
测试不同引擎：对于重要文档，可以尝试两种引擎并比较结果

通过使用这些提示词，您可以在与 AI IDE 交互时灵活控制 OCR 引擎的选择，获得最佳的识别效果

故障排除

常见问题及解决方案

RapidOCR初始化失败
- 问题：ModuleNotFoundError: No module named 'rapidocr_onnxruntime'
- 解决方案：安装RapidOCR依赖：pip install rapidocr_onnxruntime
硅基流动API 401错误
- 问题：Unauthorized: 401 Client Error
- 解决方案：检查API密钥是否正确配置在.env文件中
PDF转图片失败
- 问题：ImportError: No module named 'fitz'
- 解决方案：安装PyMuPDF依赖：pip install pymupdf
识别结果为空
- 问题：识别结果文本长度为0
- 解决方案：
  - 检查PDF是否为扫描版（非文本PDF）
  - 尝试使用硅基流动API引擎
  - 确保PDF或图片清晰可读

English Version

PDF OCR Skill

PDF OCR Skill is used to extract text content from scanned PDF files and image files. This skill supports two OCR engines:

RapidOCR (local engine): No API key required, free to use, fast recognition speed
SiliconFlow Large Model (cloud engine): Uses AI large model for high-precision OCR recognition

Features

Support text extraction from scanned PDF files
Support text recognition from multiple image formats (JPG, PNG, BMP, GIF, TIFF, WEBP)
Quadruple-engine support: RapidOCR (local), RapidDoc (enhanced), PaddleOCR (local), and SiliconFlow API (cloud)
Support Chinese and English text recognition
Maintain text order and structure
Automatically convert PDF pages to images for recognition
Intelligent engine switching: automatically switch to SiliconFlow API when RapidOCR initialization fails

Installation

Dependencies

pip install pymupdf pillow requests python-dotenv

可选依赖（推荐）

安装 RapidOCR，以启用本地识别功能：

pip install rapidocr_onnxruntime

环境配置

复制 .env.example 文件并将其重命名为 .env
根据需要配置以下选项：

# OCR engine selection
# - "rapid": Use RapidOCR local engine (default, no API key required)
# - "rapidoc": Use RapidDoc enhanced engine (no API key required)
# - "paddle": Use PaddleOCR local engine (no API key required)
# - "siliconflow": Use SiliconFlow API engine (API key required)
OCR_ENGINE=rapid

# If using SiliconFlow API engine, configure the following options:
SILICON_FLOW_API_KEY=your_api_key_here
SILICON_FLOW_OCR_MODEL=deepseek-ai/DeepSeek-OCR

快速开始

使用默认引擎（RapidOCR 本地识别）

# Import OCR processor
from scripts.pdf_ocr_processor import PDFOCRProcessor

# Create processor instance (default uses RapidOCR)
processor = PDFOCRProcessor()

# Perform PDF OCR recognition
result = processor.ocr_pdf('path/to/your/scanned.pdf')

# Get recognition result
print(f"Recognition completed, total {result['page_count']} pages")
print(f"Engine used: {result['engine']}")
print(result['text'])

使用 SiliconFlow API 引擎

# Import OCR processor
from scripts.pdf_ocr_processor import PDFOCRProcessor

# Create processor instance, specify to use SiliconFlow API
processor = PDFOCRProcessor(engine="siliconflow")

# Perform PDF OCR recognition
result = processor.ocr_pdf('path/to/your/scanned.pdf')

# Get recognition result
print(f"Recognition completed, total {result['page_count']} pages")
print(result['text'])

识别图像文件

# Import OCR processor
from scripts.pdf_ocr_processor import PDFOCRProcessor

# Create processor instance
processor = PDFOCRProcessor()  # or PDFOCRProcessor(engine="siliconflow")

# Perform image OCR recognition
result = processor.ocr_image_file('path/to/your/image.jpg')

# Get recognition result
print(f"Recognition result: {result['text']}")

命令行用法

# Use default RapidOCR engine
python pdf_ocr_processor.py your_document.pdf

# Use SiliconFlow API engine
python pdf_ocr_processor.py your_document.pdf siliconflow

# Use RapidDoc enhanced engine
python pdf_ocr_processor.py your_document.pdf rapidoc

# Use PaddleOCR engine
python pdf_ocr_processor.py your_document.pdf paddle

高级用法示例

批量处理多个 PDF 文件

import os
from scripts.pdf_ocr_processor import PDFOCRProcessor

# Create processor instance
processor = PDFOCRProcessor()

# Batch process all PDF files in directory
pdf_dir = "path/to/pdf/files"
output_dir = "path/to/output"
os.makedirs(output_dir, exist_ok=True)

for pdf_file in os.listdir(pdf_dir):
    if pdf_file.endswith('.pdf'):
        pdf_path = os.path.join(pdf_dir, pdf_file)
        output_path = os.path.join(output_dir, f"{os.path.splitext(pdf_file)[0]}.txt")
        
        print(f"Processing file: {pdf_file}")
        try:
            result = processor.ocr_pdf(pdf_path)
            
            # Save recognition result to text file
            with open(output_path, 'w', encoding='utf-8') as f:
                f.write(f"=== PDF OCR Recognition Result ===\n")
                f.write(f"File name: {pdf_file}\n")
                f.write(f"Pages: {result['page_count']}\n")
                f.write(f"Engine used: {result['engine']}\n\n")
                f.write(result['text'])
            
            print(f"Processing completed, result saved to: {output_path}")
        except Exception as e:
            print(f"Processing failed: {e}")

同时使用两个引擎

from scripts.pdf_ocr_processor import PDFOCRProcessor

def process_with_best_engine(pdf_path):
    """Try using RapidOCR, if not good enough then use SiliconFlow API"""
    # First use RapidOCR local engine
    rapid_processor = PDFOCRProcessor(engine="rapid")
    rapid_result = rapid_processor.ocr_pdf(pdf_path)
    
    # Simple evaluation of recognition effect (e.g., check recognized text length)
    text_length = len(rapid_result['text'])
    
    if text_length < 100:  # If recognized text is too short, may not be good enough
        print("RapidOCR recognition effect may not be good enough, trying SiliconFlow API...")
        silicon_processor = PDFOCRProcessor(engine="siliconflow")
        silicon_result = silicon_processor.ocr_pdf(pdf_path)
        return silicon_result
    else:
        return rapid_result

# Usage example
result = process_with_best_engine('path/to/your/document.pdf')
print(f"Recognition completed, engine used: {result['engine']}")
print(result['text'])

支持的文件格式

PDF 文件：.pdf
图像文件：.jpg、.jpeg、.png、.bmp、.gif、.tiff、.webp

输出格式

{
    "text": "Recognized full text content",
    "page_count": number_of_pages,  # Always 1 for image files
    "engine": "rapid" | "rapidoc" | "paddle" | "siliconflow"  # OCR engine used
}

使用场景

处理扫描版合同、协议和其他文档
从影印书籍和报告中提取文本
处理无法复制文本的 PDF 文件
批量处理扫描版 PDF 文档
识别屏幕截图和扫描图像中的文本
处理图像中的手写或印刷文本

注意事项

RapidOCR 引擎：
- 完全免费，无需网络连接
- 首次使用时会自动下载模型文件
- 识别速度取决于 CPU 性能
SiliconFlow API 引擎：
- 需要有效的 API 密钥
- 可能会产生费用
- 识别速度取决于页数、图像大小和网络状况
RapidDoc 引擎：
- 完全免费，无需网络连接
- 支持版面分析、表格识别、公式识别和阅读顺序恢复
- 提供更结构化的输出，包括 Markdown 格式
- 由于需要进行额外分析，处理时间可能比 RapidOCR 更长
PaddleOCR 引擎：
- 完全免费，无需网络连接
- 使用识别准确度较高的 PP-OCRv5 模型
- 首次使用时会自动下载模型文件
- 支持识别多种语言和场景中的文本
复杂的扫描版 PDF 或图像的识别准确度可能会有所不同
建议使用高分辨率的扫描版 PDF 或图像，以获得更好的识别效果

不同引擎的提示词

在 AI IDE 中与助手交互时，可以使用以下提示词来指定不同的 OCR 引擎：

📍 RapidOCR 提示词（本地引擎）

“使用本地 OCR 引擎处理此 PDF”
“使用 RapidOCR 识别此文件”
“本地处理，无需 API”
“快速识别此文档”
“离线处理此 PDF”
“不要使用 SiliconFlow API，使用本地引擎”

📍 SiliconFlow API 提示词（云端引擎）

“使用 SiliconFlow API 处理此 PDF”
“使用大模型 OCR 识别此文件”
“高精度识别此文档”
“处理复杂的扫描文档”
“使用云端 OCR 引擎”
“使用 AI 大模型进行识别”

📍 RapidDoc 提示词（增强引擎）

“使用 RapidDoc 处理此 PDF”
“使用增强型 OCR 识别此文件”
“使用版面分析处理 PDF”
“通过表格识别提取文本”
“使用 RapidDoc 获得更好的格式”
“使用版面分析增强 OCR”

📍 PaddleOCR 提示词（本地引擎）

“使用 PaddleOCR 处理此 PDF”
“使用 PaddleOCR 识别此文件”
“使用 PP-OCRv5 模型进行识别”
“使用 PaddleOCR 进行高精度识别”
“使用 PaddleOCR 本地处理”
“使用 PaddleOCR 引擎提取文本”

📍 对话示例

示例 1：使用本地引擎

User: Help me process this scanned PDF, use local OCR engine for quick recognition
Assistant: Sure, I'll use the RapidOCR local engine for you. Please provide the PDF file path.

示例 2：使用云端引擎

User: This PDF contains handwritten text, need high-precision recognition, use SiliconFlow API
Assistant: Understood, I'll use the SiliconFlow API large model for you. Please provide the PDF file path and your API key (if not already configured).

示例 3：自动选择

User: Help me recognize this PDF, choose the most suitable engine
Assistant: I'll default to using the RapidOCR local engine for you. If the recognition effect is not ideal, we can try using SiliconFlow API.

🔧 技术实现

AI 助手收到这些提示词后，将会：

解析用户意图，确定要使用的引擎
调用 PDFOCRProcessor(engine="rapid")、PDFOCRProcessor(engine="rapidoc")、PDFOCRProcessor(engine="paddle") 或 PDFOCRProcessor(engine="siliconflow")
执行 OCR 识别并返回结果

🎯 最佳实践

明确指定引擎：如果你对引擎有具体要求，最好在提示词中明确说明
提供上下文：说明文档类型（例如，手写文档、复杂格式）有助于助手选择合适的引擎
测试不同引擎：对于重要文档，可以尝试使用两种引擎并比较结果

使用这些提示词，你可以在与 AI IDE 交互时灵活控制 OCR 引擎的选择，以获得最佳识别效果

故障排除

常见问题及解决方案

RapidOCR 初始化失败
- 问题：ModuleNotFoundError: No module named 'rapidocr_onnxruntime'
- 解决方案：安装 RapidOCR 依赖：pip install rapidocr_onnxruntime
SiliconFlow API 401 错误
- 问题：Unauthorized: 401 Client Error
- 解决方案：检查 .env 文件中的 API 密钥是否配置正确
PDF 转图像失败
- 问题：ImportError: No module named 'fitz'
- 解决方案：安装 PyMuPDF 依赖：pip install pymupdf
识别结果为空
- 问题：识别结果文本长度为 0
- 解决方案：
  - 检查 PDF 是否为扫描版（非文本 PDF）
  - 尝试使用 SiliconFlow API 引擎
  - 确保 PDF 或图像清晰可读

许可证

MIT License - 详见 LICENSE.txt

支持 Markdown

登录后评论

基本信息

作者: yejinlei
仓库: yejinlei/pdf-ocr-skill
分类: 文档处理
安装次数: 439
GitHub Stars: 13

报告问题