从图片或 PDF 文档中识别并提取文字内容，支持多种图片格式和 PDF 文件，自动判断是否包含文字并保留原始格式输出结构化结果；当用户需要从图片或 PDF 提取文字、进行 OCR 识别、处理含文字的文档或转换为可编辑文本时使用
---
name: pdf-image-text-extractor
description: 从图片或 PDF 文档中识别并提取文字内容，支持多种图片格式和 PDF 文件，自动判断是否包含文字并保留原始格式输出结构化结果；当用户需要从图片或 PDF 提取文字、进行 OCR 识别、处理含文字的文档或转换为可编辑文本时使用
dependency:
python:
- pymupdf>=1.23.0
---
# PDF和图片文字提取
---
## 1. 简介
**PDF和图片文字提取**是一款从图片和 PDF 文档中智能识别并提取文字内容的工具。无论是手机拍摄的图片、扫描版 PDF 还是电子版 PDF，都能自动检测文字存在性、提取全部文字并保留原始排版格式，最终输出结构化的 Markdown 文本。
**核心价值**：告别手动抄录，一键提取文档中的文字，节省 90% 的转录时间。
**适用对象**：学生（提取教材/论文文字）、办公人员（提取合同/发票信息）、内容创作者（提取参考资料）、开发者（批量处理文档）。
---
## 2. 功能特性
| 功能 | 说明 |
| ------------------- | -------------------------------------------------------------------------- |
| 📷 **图片文字识别** | 支持 PNG、JPG、JPEG、GIF、WebP、BMP 等常见格式，自动检测并提取图片中的文字 |
| 📄 **PDF 文字提取** | 同时支持扫描版和文字版 PDF，保留段落结构和标题层级 |
| 🎯 **智能判断** | 自动判断文档是否包含文字，无文字时明确提示，避免空等 |
| 📝 **结构化输出** | 输出 Markdown 格式，标题、正文、段落层次分明，可直接阅读或二次编辑 |
| 🌐 **多语言支持** | 支持中文、英文等多种语言文字的识别和提取 |
| 🔒 **隐私保护** | 处理的文件仅在当前会话中使用，不会被持久化存储 |
**特色亮点**：
- 图片文字提取无需安装任何额外依赖，直接使用内置 `read_image` 工具
- PDF 文字提取采用 PyMuPDF 引擎，精准识别字体大小和粗体格式，自动生成 Markdown 标题层级
- 输出结果可灵活选择：直接展示、保存为 `.md` 文件、或嵌入其他文档
---
## 3. 一键安装
### 依赖安装
| 依赖 | 说明 | 安装命令 |
| ----------------- | -------------------- | ----------------------------- |
| `pymupdf>=1.23.0` | PDF 文字提取核心引擎 | `pip install pymupdf>=1.23.0` |
> **注意**：图片文字提取功能直接使用 AI 内置的 `read_image` 工具，无需安装任何额外依赖。`pymupdf` 仅在需要提取 PDF 文字时才需安装。
### 环境要求
- Python 3.7+
- 支持的操作系统：macOS / Linux / Windows
---
## 4. 使用指南
### 图片文字提取
**操作流程**：
1. **上传图片** — 将包含文字的图片文件上传到对话中
2. **自动识别** — 智能体使用 `read_image` 工具自动识别图片内容，提取所有文字（包括标题、正文、注释、水印等）
3. **判断文字存在性** — 如果检测到文字，进入下一步；如果未检测到文字，智能体会明确告知"图片中未包含可提取的文字"
4. **格式化输出** — 保持原有的文字结构和排版，整理为易读的格式
**可选分支**：
- 当用户仅需查看文字内容：直接输出文字，不生成文件
- 当用户要求保存结果：生成 `.md` 文件
- 当图片文字模糊或难以识别：说明情况并提供最佳识别结果
### PDF 文字提取
**操作流程**：
1. **上传 PDF 文件** — 将 PDF 文件上传到对话中
2. **执行提取脚本**：
```bash
python scripts/pdf_text_extractor.py <pdf_file_path>
```
3. **查看提取结果** — 脚本返回 JSON 格式结果，包含：
- `success`: 是否成功
- `text`: Markdown 格式的文本内容
- `page_count`: 总页数
- `error`: 错误信息（如有）
4. **格式化输出** — 脚本返回的文本为 Markdown 格式，可直接展示或保存为文件
**脚本参数说明**：
| 参数 | 说明 | 必填 |
| ----------------- | ------------------ | ---- |
| `<pdf_file_path>` | PDF 文件的本地路径 | 是 |
**输出格式示例**：
```json
{
"success": true,
"text": "## 第一章 引言\n\n这是正文内容...\n\n---\n\n## 第二章 方法\n\n...",
"page_count": 10,
"error": ""
}
```
**可选分支**：
- 当 PDF 包含扫描图片：提示用户该页面为扫描图片，可能需要 OCR 处理
- 当提取失败：检查文件是否存在、格式是否正确、PDF 是否加密
### 常用命令 / 指令速查表
| 场景 | 命令 / 操作 |
| ------------- | --------------------------------------------- |
| 提取图片文字 | 上传图片，直接让智能体识别 |
| 提取 PDF 文字 | `python scripts/pdf_text_extractor.py <路径>` |
| 仅查看不保存 | 提取后直接输出文本即可 |
| 保存为文件 | 提取后要求智能体生成 `.md` 文件 |
| 安装依赖 | `pip install pymupdf>=1.23.0` |
---
## 5. 使用场景
| 场景 | 角色 | 需求 | 使用方式 | 预期收益 |
| ------------------- | ------------------- | ------------------------------------------ | -------------------------------------------- | ----------------------------------------------- |
| 🔬 **学术研究** | 研究生 / 学者 | 从扫描版 PDF 论文中提取文字做笔记和引用 | 上传 PDF → 执行提取脚本 → 获取 Markdown 原文 | 无需手动打字，准确率 95%+，直接复制到论文中引用 |
| 💼 **办公文档处理** | 行政 / 法务 / 财务 | 从图片合同、发票、扫描件中提取关键文字信息 | 上传图片 → 智能体识别 → 提取文字 | 告别逐字手打，提升文档数字化效率 |
| ✍️ **内容二次创作** | 自媒体 / 编辑 | 从 PDF 电子书中提取文字作为创作素材 | 上传 PDF → 提取全部文字 → 保存为 .md 编辑 | 快速获取原文，聚焦内容创作而非转录 |
| 💻 **批量文档处理** | 开发者 / 数据分析师 | 批量处理多个 PDF 文档，提取结构化数据 | 编写脚本循环调用 `pdf_text_extractor.py` | 自动化处理，可集成到数据处理流水线中 |
---
## 6. 项目架构
### 目录结构
```
pdf-image-text-extractor/
├── SKILL.md # Skill 定义文件
├── README.md # 用户文档（中文）
├── README.en.md # 用户文档（英文）
└── scripts/
└── pdf_text_extractor.py # PDF 文字提取核心脚本
```
### 技术栈
| 技术 | 用途 | 版本要求 |
| -------------- | -------------------------- | ----------- |
| Python | 脚本运行环境 | 3.7+ |
| PyMuPDF (fitz) | PDF 解析和文字提取引擎 | >=1.23.0 |
| urllib | 内置标准库，用于 HTTP 请求 | Python 内置 |
### 核心模块说明
**`scripts/pdf_text_extractor.py`** — PDF 文字提取核心脚本：
- **`extract_text_from_pdf(pdf_path)`** — 主提取函数，打开 PDF 文件，逐页解析文本块，根据字体大小（>16px 判定为标题）和粗体属性自动生成 Markdown 格式（## 和 ### 标题），输出含页面分隔符的结构化文本
- **`record_skill_usage()`** — 调用 Redfox 记录接口，记录工具使用次数（不影响主流程）
- **`main()`** — CLI 入口，接收 PDF 文件路径参数，调用提取函数并输出 JSON 结果
### 资源索引
| 资源 | 路径 | 说明 |
| -------- | -------------------------------------------------------------- | ---------------- |
| 核心脚本 | [scripts/pdf_text_extractor.py](scripts/pdf_text_extractor.py) | PDF 文字提取脚本 |
| 用户文档 | [README.md](README.md) | 中文使用说明 |
| 用户文档 | [README.en.md](README.en.md) | 英文使用说明 |
---
## 7. 常见问答
### 安装
**Q：安装 pymupdf 时报错怎么办？**
A：确保 Python 版本 >= 3.7。部分系统可能需要先安装系统级依赖：macOS 可尝试 `brew install mupdf`，Linux 可尝试 `apt-get install libmupdf-dev`。
**Q：是否必须安装 pymupdf？**
A：如果只使用图片文字提取功能，无需安装。仅在需要提取 PDF 文字时才需要安装 pymupdf。
### 使用
**Q：图片文字提取的准确率如何？**
A：文字识别结果受图片清晰度、字体、背景等因素影响。清晰图片准确率可达 95%+，模糊或复杂背景的图片准确率会下降。
**Q：PDF 提取后文字格式是什么样的？**
A：脚本自动生成 Markdown 格式输出，大字体行自动转为 `##` 标题，粗体大字体为 `###` 标题，不同页面之间用 `---` 分隔。
**Q：能否处理加密的 PDF？**
A：不支持加密或受密码保护的 PDF 文件。需要先解密后再提取。
**Q：提取的文字可以保存吗？**
A：可以。提取后要求智能体生成 `.md` 文件即可保存到本地。
### 故障排除
**Q：PDF 提取结果为空怎么办？**
A：可能原因：1) PDF 是扫描图片（图片型 PDF），需要使用 OCR 工具；2) PDF 本身不含文字层。对于扫描版 PDF，建议先使用 OCR 工具预处理。
**Q：文件过大导致处理缓慢？**
A：建议处理小于 50MB 的文件。过大的文件可在提取前进行分割处理。
**Q：提示"文件不存在"？**
A：确认 PDF 文件路径正确，文件已上传到工作目录中。可使用绝对路径避免路径问题。
**Q：图片中未检测到文字？**
A：可能原因：1) 图片确实不含文字；2) 图片中的文字过于模糊或与背景融合。尝试使用更高清晰度的图片重新提取。
Creator's repository · redfox-data/redfox-community