图片文字识别 Skill(image-ocr)

概述

从图片中提取文字,输出可复制、可检索、可再加工的文本。基于 RapidOCR(ONNX 运行时,纯 CPU,中英文皆强),自动降级到 PaddleOCR / EasyOCR / Tesseract。

除纯文本外还支持:

• 版面还原 — 保留原始行列位置,适合有分栏、缩进的内容
• 表格提取 — 按坐标聚类成列,输出 Markdown 表格
• 坐标与置信度 — 每块文字的位置和识别可信度,用于定位和质量判断
• 图像增强 — 灰度/去噪/自适应二值化,救回低质量扫描件和拍照文档

何时使用

使用场景:

• 截图提字、报错弹窗文字、代码截图转文本
• 扫描件、拍照文档、票据、证件的文字录入
• 表格截图转 Markdown / 结构化数据
• 图片内容需要被搜索、比对或写入代码

不要用于:

• 理解画面内容而非提字(这是什么场景/描述这张图/分析这个图表)→ 用 image-inspector skill
• 文字型 PDF、Word、Excel → 用 document-reader skill,直接取文本层精度更高
• 只需要图片尺寸、EXIF → 用 image-inspector skill
• 随手看一张普通截图(单张、只看一次、不需要精确文字)→ 直接用 Read 工具读图,见下方成本说明

成本:单张随手看,读图比本 skill 更省

加载本 SKILL.md 约需 2200 token,而 Read 一张图最多约 1600 token(最长边超 1568px 会被自动缩放,形成天花板)。加载 skill 的成本 ≈ 直接看一整张大图。

实测(1662×816 管理界面截图):直接读图 1607 token;本 skill 输出仅 650 token,但加上加载成本共 2850 token,反而更贵。

所以只在以下情况用本 skill:

• 批量处理(同会话 5 张以上)— 加载成本被摊薄,每张省约 1000 token
• 超大图/长截图 — 切片后逐张读图可达 8000+ token,OCR 提文字远更省
• 需要精确文字 — 代码、金额、编号、证件号,读图易看错,这是准确性问题而非成本问题
• 需要结构化数据 — --json 的坐标与置信度,读图无法替代

⚠️ 富 UI 截图慎用:低对比度文字、下拉框内的值、反色按钮(蓝底白字)OCR 易漏。此类图即使用了 skill 仍需读图核对,等于两份成本都付,直接读图才是更优解。

使用方式

基础提取

python ~/.claude/skills/image-ocr/scripts/image_ocr.py 图片路径

直接输出识别到的文字,按阅读顺序排列。

按场景选参数

关于 --preprocess:默认不要用

实测结论:RapidOCR 对原图的鲁棒性远超预处理后的图。 同一张高斯模糊测试图:

原因是 RapidOCR 是深度学习模型,依赖笔画的灰度过渡信息,而二值化会把这些信息丢掉。模糊、光照不均的图片请直接识别,不要加 --preprocess。

--preprocess 仅在这些情况值得一试:

• 极低对比度的老旧扫描件(文字与背景几乎同色)
• 强反光、阴影覆盖过半的拍照文档
• 原图直接识别返回空结果时,作为最后的补救手段

用了之后必须对比原图结果,取更好的那个,不要默认相信预处理版本。

# 版面还原:保留行列位置
python ~/.claude/skills/image-ocr/scripts/image_ocr.py screenshot.png --layout

# 表格转 Markdown
python ~/.claude/skills/image-ocr/scripts/image_ocr.py table.png --table

# 低质量扫描件:先直接识别,漏字再放宽阈值
python ~/.claude/skills/image-ocr/scripts/image_ocr.py scan.jpg --min-conf 0.3

# 拿坐标和置信度
python ~/.claude/skills/image-ocr/scripts/image_ocr.py form.png --json

支持多文件:image_ocr.py a.png b.png c.jpg

识别结果的处理原则

OCR 不是 100% 可靠,拿到结果后:

1. 明显的错字直接修正 — 中文常见混淆(己/已、末/未、日/曰)、数字字母混淆(0/O、1/l/I、5/S)。结合上下文语义判断,不要原样照抄错字。
2. 平均置信度低于 0.7 时警惕 — 输出头部会显示平均置信度。偏低说明图片质量差,此时应结合 Read 工具直接读图核对,而不是硬用低质量结果。
3. 有丢弃提示要留意 — 丢弃低置信: N 说明有 N 块文字因置信度不足被过滤。若怀疑漏了关键内容,降低 --min-conf 重跑。
4. 完全没识别到文字 — 依次尝试:--min-conf 0.2、--preprocess。都无效则可能图中确实无文字,或文字是艺术字/严重变形,此时改用 Read 工具直接读图辨认。
5. 关键数字务必核对 — 金额、日期、编号、证件号这类不能错的内容,建议同时用 Read 工具读图人工比对一遍再交付。
6. 标点会被规范化 — RapidOCR 倾向输出全角标点(错误码： 而非 错误码:),且可能省略空格(Retry2026)。需要精确还原原文格式时注意调整。

选项

输出示例

默认模式:

=== login_error.png ===
引擎: rapidocr  文本块: 6  平均置信度: 0.9421

登录失败
错误码: AUTH_401
用户名或密码不正确
请检查后重试
忘记密码?
返回首页

--table 模式:

| 姓名 | 部门 | 工号 |
|---|---|---|
| 张伟 | 技术部 | 10023 |
| 李娜 | 财务部 | 10087 |

--boxes 模式:

[120,45,286,72] (0.98) 登录失败
[120,88,412,110] (0.95) 错误码: AUTH_401

引擎说明

当前环境已安装 RapidOCR(rapidocr_onnxruntime 1.4.4),开箱可用,无需额外配置。

首次运行会加载模型(约 15MB,已随包内置),耗时略长,后续调用变快。

如需切换引擎:

pip install paddleocr paddlepaddle    # 精度更高,安装体积大
pip install easyocr                   # 多语言支持广

Tesseract 需另装程序本体和 chi_sim 中文语言包,中文效果不如 RapidOCR,不推荐。脚本会检测二进制是否真实存在,不会因 pytesseract 空壳而误判可用。

依赖

pip install rapidocr_onnxruntime pillow
pip install opencv-python numpy      # --preprocess 需要

当前环境已确认:RapidOCR 1.4.4、Pillow 12.0.0、OpenCV 4.12.0、numpy 2.2.6 均可用。

常见问题

提示"未找到可用的 OCR 引擎" 执行 pip install rapidocr_onnxruntime。

中文识别成乱码或繁简混杂 RapidOCR 默认中英文模型。若原图是繁体或日韩文,考虑 --engine easyocr 并调整其语言参数。

表格错列 --table 依赖坐标聚类,合并单元格、无框线表格、行高不齐时会错列。改用 --layout 看原始排布,再手工整理成表格。

中文路径报错 脚本已用 np.fromfile + imdecode 处理,不受中文路径影响。若仍报错请反馈完整路径。

识别很慢 首次加载模型的固定开销。超大图建议先用 image-inspector 的 --prep 压缩,再送入 OCR。

文件位置

• 主脚本:~/.claude/skills/image-ocr/scripts/image_ocr.py
• 依赖清单:~/.claude/skills/image-ocr/requirements.txt