图像 OCR 技能

用途

该技能通过 pytesseract Python 库调用 Tesseract OCR 引擎，实现对图像文件（JPG、PNG 等）中文字的高精度提取。适用于扫描文档、截图、含文字的照片、收据、表单以及其他包含文本的视觉内容。

适用场景

• 从扫描文档或照片中提取文字
• 从截图或图像抓取结果中读取文字
• 批量处理包含文本信息的图像文件
• 将视觉文档转换为机器可读的文本
• 从图像中的表单、收据或表格中提取结构化数据

所需库

需安装以下 Python 库：

import pytesseract
from PIL import Image
import json
import os

输入要求

• 文件格式：JPG、JPEG、PNG、WEBP
• 图像质量：印刷体文字建议最低 300 DPI；文字需清晰、易辨识
• 文件大小：单张图像不超过 5MB（必要时请缩放）
• 文字语言：若非英文，请显式指定以提升识别准确率

输出 Schema

所有提取结果必须以符合以下 Schema 的合法 JSON 格式返回：

{
  "success": true,
  "filename": "example.jpg",
  "extracted_text": "从图像中完整提取的原始文本...",
  "confidence": "high|medium|low",
  "metadata": {
    "language_detected": "en",
    "text_regions": 3,
    "has_tables": false,
    "has_handwriting": false
  },
  "warnings": [
    "右下角文字部分被遮挡",
    "页眉区域检测到对比度偏低"
  ]
}

字段说明

• success：布尔值，表示文字提取是否成功完成
• filename：原始图像文件名
• extracted_text：按阅读顺序（自上而下、自左向右）组织的完整文本内容
• confidence：基于图像质量与文字清晰度得出的整体 OCR 置信度等级
• metadata.language_detected：ISO 639-1 语言代码
• metadata.text_regions：识别出的独立文本块数量
• metadata.has_tables：是否检测到表格类数据结构
• metadata.has_handwriting：是否检测到手写文字
• warnings：记录的质量问题或潜在错误列表

代码示例

基础 OCR 提取

import pytesseract
from PIL import Image

def extract_text_from_image(image_path):
    """使用 Tesseract OCR 从单张图像中提取文字。"""
    img = Image.open(image_path)
    text = pytesseract.image_to_string(img)
    return text.strip()

带置信度数据的 OCR

import pytesseract
from PIL import Image

def extract_with_confidence(image_path):
    """提取文字并返回逐词置信度分数。"""
    img = Image.open(image_path)

    # 获取包含置信度的详细 OCR 数据
    data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)

    words = []
    confidences = []

    for i, word in enumerate(data['text']):
        if word.strip():  # 跳过空字符串
            words.append(word)
            confidences.append(data['conf'][i])

    # 计算平均置信度
    avg_confidence = sum(c for c in confidences if c > 0) / len([c for c in confidences if c > 0]) if confidences else 0

    return {
        'text': ' '.join(words),
        'average_confidence': avg_confidence,
        'word_count': len(words)
    }

完整 OCR 并输出 JSON

import pytesseract
from PIL import Image
import json
import os

def ocr_to_json(image_path):
    """执行 OCR 并以 JSON 格式返回结果。"""
    filename = os.path.basename(image_path)
    warnings = []

    try:
        img = Image.open(image_path)

        # 获取详细 OCR 数据
        data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)

        # 提取文本并保留结构
        text = pytesseract.image_to_string(img)

        # 计算置信度
        confidences = [c for c in data['conf'] if c > 0]
        avg_conf = sum(confidences) / len(confidences) if confidences else 0

        # 判定置信度等级
        if avg_conf >= 80:
            confidence = "high"
        elif avg_conf >= 50:
            confidence = "medium"
        else:
            confidence = "low"
            warnings.append(f"OCR 置信度偏低：{avg_conf:.1f}%")

        # 统计文本区域（块）数量
        block_nums = set(data['block_num'])
        text_regions = len([b for b in block_nums if b > 0])

        result = {
            "success": True,
            "filename": filename,
            "extracted_text": text.strip(),
            "confidence": confidence,
            "metadata": {
                "language_detected": "en",
                "text_regions": text_regions,
                "has_tables": False,
                "has_handwriting": False
            },
            "warnings": warnings
        }

    except Exception as e:
        result = {
            "success": False,
            "filename": filename,
            "extracted_text": "",
            "confidence": "low",
            "metadata": {
                "language_detected": "unknown",
                "text_regions": 0,
                "has_tables": False,
                "has_handwriting": False
            },
            "warnings": [f"OCR 执行失败：{str(e)}"]
        }

    return result

# 使用示例
result = ocr_to_json("document.jpg")
print(json.dumps(result, indent=2))

批量处理多张图像

import pytesseract
from PIL import Image
import json
import os
from pathlib import Path

def process_image_directory(directory_path, output_file):
    """处理目录下所有图像并保存结果。"""
    image_extensions = {'.jpg', '.jpeg', '.png', '.webp'}
    results = []

    for file_path in sorted(Path(directory_path).iterdir()):
        if file_path.suffix.lower() in image_extensions:
            result = ocr_to_json(str(file_path))
            results.append(result)
            print(f"已处理：{file_path.name}")

    # 保存结果
    with open(output_file, 'w') as f:
        json.dump(results, f, indent=2)

    return results

Tesseract 配置选项

语言选择

# 指定语言（默认为英文）
text = pytesseract.image_to_string(img, lang='eng')

# 多语言支持
text = pytesseract.image_to_string(img, lang='eng+fra+deu')

页面分割模式（PSM）

使用 --psm 参数控制 Tesseract 对图像的分割方式：

# PSM 3：全自动页面分割（默认）
text = pytesseract.image_to_string(img, config='--psm 3')

# PSM 4：假设为单列变长文本
text = pytesseract.image_to_string(img, config='--psm 4')

# PSM 6：假设为统一文本块
text = pytesseract.image_to_string(img, config='--psm 6')

# PSM 11：稀疏文本 — 尽可能多地查找文本
text = pytesseract.image_to_string(img, config='--psm 11')

常用 PSM 值说明：

• 0：仅执行方向与文字类型检测（OSD）
• 3：全自动页面分割（默认）
• 4：单列变长文本
• 6：统一文本块
• 7：单行文本
• 11：稀疏文本
• 13：原始行（Raw line）

图像预处理

为提升 OCR 准确率，建议对图像进行预处理：

from PIL import Image, ImageFilter, ImageOps

def preprocess_image(image_path):
    """对图像进行预处理以提升 OCR 效果。"""
    img = Image.open(image_path)

    # 转为灰度图
    img = img.convert('L')

    # 提升对比度
    img = ImageOps.autocontrast(img)

    # 应用轻微锐化
    img = img.filter(ImageFilter.SHARPEN)

    return img

# 使用预处理后的图像执行 OCR
img = preprocess_image("document.jpg")
text = pytesseract.image_to_string(img)

高级预处理策略

对于低对比度、褪色文字或深色背景等困难图像，可尝试多种预处理方法：

1. 灰度 + 自动对比度增强 —— 适用于大多数图像的基础增强
2. 反色处理 —— 对深色背景+浅色文字使用 ImageOps.invert()
3. 图像缩放 —— 对小尺寸图像进行放大（如 2 倍），以改善字符识别效果
4. 阈值二值化 —— 使用 img.point(lambda p: 255 if p > threshold else 0) 进行二值化，尝试不同阈值（如 100、128）
5. 锐化处理 —— 应用 ImageFilter.SHARPEN 以增强边缘清晰度

多轮 OCR 策略

对于复杂图像，单次 OCR 可能遗漏部分文字。建议采用多轮 OCR，结合不同配置提升覆盖率：

1. 尝试多种 PSM 模式 —— 不同页面分割模式适用于不同版式（例如：--psm 6 适合文本块，--psm 4 适合多列，--psm 11 适合稀疏文本）

2. 尝试多种预处理变体 —— 对同一图像的不同预处理版本分别运行 OCR

3. 合并结果 —— 汇总各轮 OCR 输出，最大化文本覆盖范围

def multi_pass_ocr(image_path):
    """使用多种策略执行 OCR 并合并结果。"""
    img = Image.open(image_path)
    gray = ImageOps.grayscale(img)

    # 生成预处理变体
    variants = [
        ImageOps.autocontrast(gray),
        ImageOps.invert(ImageOps.autocontrast(gray)),
        gray.filter(ImageFilter.SHARPEN),
    ]

    # 待尝试的 PSM 模式
    psm_modes = ['--psm 6', '--psm 4', '--psm 11']

    all_text = []
    for variant in variants:
        for psm in psm_modes:
            try:
                text = pytesseract.image_to_string(variant, config=psm)
                if text.strip():
                    all_text.append(text)
            except Exception:
                pass

    # 合并所有提取到的文本
    return "\n".join(all_text)

该方法可显著提升收据、褪色文档及质量参差不齐图像的文字提取效果。

错误处理

常见问题与解决方案

问题：未找到 Tesseract

# 验证 Tesseract 是否已安装
try:
    pytesseract.get_tesseract_version()
except pytesseract.TesseractNotFoundError:
    print("Tesseract 未安装或未加入系统 PATH")

问题：OCR 质量差

• 对图像进行预处理（灰度化、对比度增强、锐化）
• 根据文档类型选用合适的 PSM 模式
• 确保图像分辨率足够（≥300 DPI）

问题：输出为空或乱码

• 确认图像中确实含有可识别文字
• 尝试不同 PSM 模式
• 验证图像文件是否损坏

质量自检清单

返回结果前，请确保完成以下校验：

• 输出为合法 JSON（可用 json.loads() 验证）
• 所有必需字段均已存在（success、filename、extracted_text、confidence、metadata）
• 文本保持逻辑阅读顺序（自上而下、自左向右）
• 置信度等级真实反映 OCR 实际质量
• warnings 数组已包含所有检测到的问题
• JSON 中特殊字符已正确转义

限制条件

• Tesseract 对印刷体文字效果最佳；手写体识别能力有限
• 装饰性字体、艺术字或高度风格化的文本会降低识别准确率
• 数学公式与特殊符号可能无法准确提取
• 已被涂黑（redacted）或添加水印的文字不可恢复
• 严重图像退化（模糊、噪声、低分辨率）将显著降低识别精度
• 复杂多栏排版可能需要定制 PSM 配置

版本历史

• 1.0.0（2026-01-13）：初始发布，基于 Tesseract/pytesseract OCR