本技能用于从图像、PDF 或文档图片中提取文字,底层调用 PP-OCRv5 API。
适用场景:从图片(截图、照片、扫描件、图表)中提取文字;读取 PDF 或文档图片中的文字;对任何含文字的视觉内容执行 OCR;解析发票、收据、表单、表格等结构化文档;识别手机拍摄照片中的文字;从指向图片或 PDF 的 URL 中提取文字。
不适用场景:可直接用 Read 工具读取的纯文本文件;代码文件或 markdown 文档;不涉及图像转文字的任务。
使用方式(基本流程):
- 确认输入来源。用户提供 URL 时使用 --file-url 参数;提供本地文件路径时使用 --file-path 参数;用户上传图片时先保存再使用 --file-path。
- 执行 OCR: python scripts/ocr_caller.py --file-url "用户提供的 URL" --pretty 或本地文件: python scripts/ocr_caller.py --file-path "文件路径" --pretty
- 解析 JSON 响应:检查 ok 字段(true 为成功,false 为错误);从 result.full_text 提取全部识别文字;从 quality.quality_score 获取识别置信度(0.0-1.0);ok 为 false 时展示 error.message。
- 向用户呈现结果:以可读格式展示提取的文字;质量分低于 0.5 时提醒用户;需要结构化输出时使用 result.pages[].items[] 获取逐行数据。
模式选择:默认使用 --mode auto(自适应)。用户明确要求“快速识别/fast”时用 --mode fast;要求“高精度/accurate”时用 --mode quality。Auto 模式会自动尝试 1-3 次,逐步提高校正级别,返回最佳结果。
输出结构示例: { "ok": true, "result": { "full_text": "所有识别文字", "pages": [...] }, "quality": { "quality_score": 0.85, "text_items": 42 } } 关键字段:result.full_text 为完整文字;quality.quality_score 0.72 以上为良好,低于 0.5 为较差;ok 为 false 时 error.message 给出错误描述。
首次配置:若用户尚未配置 API 凭据,运行 python scripts/configure.py,会提示输入 API_URL(Paddle AI Studio 端点)与 PADDLE_OCR_TOKEN(访问令牌),配置保存至 .env 文件,只需配置一次。
错误处理:缺少配置时提示运行 python scripts/configure.py;认证失败(403)对应 error_code: PROVIDER_AUTH_ERROR,需重新配置正确凭据;配额超限(429)对应 error_code: PROVIDER_QUOTA_EXCEEDED,表示当日 API 配额耗尽,需等待或升级;未检测到文字时 quality_score 为 0.0、text_items 为 0,可能图片空白、损坏或不含文字。
质量分解释:0.90-1.00 识别质量优秀;0.72-0.89 识别质量良好(默认目标);0.50-0.71 质量一般,可能存在错误;0.00-0.49 质量差或未检测到文字。质量低于 0.5 时建议:使用 --mode quality 提高精度;检查图片是否清晰且含文字;尽量提供更高分辨率图片。
高级选项(仅在用户明确要求时使用):包含原始提供商响应(调试): python scripts/ocr_caller.py --file-url "URL" --return-raw-provider 请求可视化(显示检测区域): python scripts/ocr_caller.py --file-url "URL" --visualize 调整 auto 模式参数: python scripts/ocr_caller.py --file-url "URL" --max-attempts 2 --quality-target 0.80 --budget-ms 20000
参考文档:references/agent_policy.md(auto 模式策略与质量评分)、references/normalized_schema.md(完整输出 schema 规范)、references/provider_api.md(提供商 API 契约细节)。调试复杂问题、用户询问质量评分算法、需理解自适应重试机制或自定义 auto 模式参数时可加载。
测试:运行 python scripts/smoke_test.py 可验证配置与 API 连通性。