breezedeus/Pix2Text · 上手攻略

• 仓库：breezedeus/Pix2Text
• 链接：https://github.com/breezedeus/Pix2Text
• 分类：academic-writing / ai
• 作者：Tom
• 更新：2026-08-13

是什么

Pix2Text（简称 P2T）是一个开源 Python 工具，核心功能是把图片（含数学公式、表格、版面布局）识别并转换为 Markdown 格式，定位是 Mathpix 的免费开源替代品。

2025 年 7 月升级到 V1.1.4 后，数学公式检测（MFD）和识别（MFR）模型均已升级到 1.5 版本，版面分析引入 DocLayout-YOLO 模型，整体识别精度大幅提升。支持 80+ 种语言，中英文效果最佳。也可以把整个 PDF 文件转换为 Markdown。

V1.1.5（2026.02.07）进一步重构了模型下载逻辑，优先从 HuggingFace 官方端点下载，失败后按镜像列表回退，下载稳定性更好。

解决什么问题

1. 公式转 LaTeX：论文 PDF 中的数学公式（连分式、积分、矩阵等）无法直接复制粘贴，手动重敲成本极高。P2T 直接输出 LaTeX 代码。
2. PDF 批量转 Markdown：扫描版 PDF 或无法复制的 PDF，直接提取文字和表格成 Markdown，供 LLM 处理或归档。
3. 多语言 OCR：支持 80+ 语言，中英文优先用 CnOCR（更快更准），其他语言用 EasyOCR。
4. 版面分析：不是简单 OCR——能区分正文、标题、表格、图片块，按阅读顺序整合成结构化 Markdown。
5. 表格识别：识别图片中的表格并输出 Markdown 表格格式，不是把表格当图片处理。

快速安装

标准安装（仅支持中英文）

pip install pix2text

多语言支持（安装 EasyOCR 相关依赖）

pip install pix2text[multilingual]

国内镜像加速

pip install pix2text -i https://mirrors.aliyun.com/pypi/simple

VLM 模式（使用闭源大模型识别表格/公式，需额外安装）

pip install pix2text[vlm]

⚠️ 首次安装若遇 OpenCV 问题，建议先 pip install opencv-python 再装 pix2text。PyTorch 依赖若安装异常，请参考 PyTorch 官方安装指南。

模型版本要求

核心用法

Python API 基本调用

from pix2text import Pix2Text

# 默认初始化（首次使用自动下载模型）
p2t = Pix2Text()

# 图片转 Markdown
result = p2t("/path/to/image.jpg")
print(result)

# 纯公式图片（不经过版面分析，直接送入 MFD+MFR）
from pix2text import FormulaRecognizer
recog = FormulaRecognizer()
outs = recog.recognize_formula("/path/to/formula.png")
print(outs)  # 输出 LaTeX 代码

命令行工具（开箱即用）

# 直接识别图片并输出 Markdown
pix2text /path/to/image.jpg

# 开启版面分析模式
pix2text --enable-table --analyze-layout /path/to/image.jpg

# 指定设备（GPU 加速）
pix2text --device cuda /path/to/image.jpg

# 批量处理 PDF
pix2text /path/to/document.pdf

高级：PDF 转 Markdown

from pix2text import PDFReader

reader = PDFReader()
result = reader.read("/path/to/document.pdf")
print(result)  # 输出 Markdown，包含文字、公式、表格

高级：VLM 模式（闭源模型识别表格/公式）

# 需要先安装 pix2text[vlm]，并配置 LiteLLM 支持的 API key（如 OpenAI）
import os
os.environ["OPENAI_API_KEY"] = "your-key"

from pix2text import Pix2Text
p2t = Pix2Text.from_config(
    enable_table=True,
    table_engine="VlmTableOCR",  # 使用 VLM 识别表格
)
result = p2t("/path/to/image.jpg")

在线服务（不装任何东西）

不想装 Python？直接用 P2T 网页版： - 每人每天免费 10,000 字符限额 - 目前仅支持简体中文和英文 - 受硬件限制，复杂任务建议用开源版本

核心模型说明

国内下载慢可用 HuggingFace 镜像：https://hf-mirror.com/{model-path}

典型适用场景

• 论文公式转 Markdown：把含 LaTeX 公式的 PDF 截图或图片直接转成可编辑的 Markdown，复制到笔记软件或直接喂给 LLM 处理。
• 扫描版 PDF 提取内容：无法复制文字的扫描件，用 P2T 转 Markdown 后供 LLM 做摘要、问答、翻译。
• 复杂版面图片转结构化文本：含多栏、表格、公式、题注的学术图片，一键输出 Markdown。
• 多语言 OCR 存档：80+ 语言支持，适合处理外文文献、小语种资料。
• 数学笔记数字化：手写公式图片（需清晰）可转 LaTeX，用于整理错题本或备课材料。

坑与注意

1. 首次使用自动下载模型：模型文件较大（数百 MB），首次运行需要联网下载。国内用户推荐配置 HuggingFace 镜像或使用 hf-mirror.com。

2. MFD/MFR 1.5 模型需要 pix2text ≥ 1.1.4：如果是从旧版本升级上来的，请 pip install pix2text --upgrade。低于 1.1.4 版本不支持 1.5 版模型。

3. 扫描版 PDF 效果依赖图片质量：分辨率低、倾斜、阴影、字迹模糊的图片识别效果差；建议先用图像处理工具（去噪、纠偏）预处理。

4. 手写公式识别不稳定：MFR 模型在标准印刷体数学公式上训练，手写体识别准确率明显低于印刷体，且因人而异。

5. VLM 模式需要额外配置：VlmTableOCR 和 VlmTextFormulaOCR 依赖 LiteLLM + 闭源 API（OpenAI / Claude 等），不是纯本地开源方案，使用成本较高。

6. 在线服务每日限额 10,000 字符：超出后需等次日刷新或使用开源版本，不适合大规模批处理。

7. 只有简体中文和英文的网页版：其他语言图片请用开源版本。

8. Windows 上 OpenCV 安装可能报错：建议用 pip install opencv-python-headless 替代，或在 WSL2 环境中运行。

与同类对比

核心差异：Pix2Text 是目前开源方案中公式识别精度最高的（MFR 1.5 在多个数据集上达 SOTA），且整合了版面分析 + 表格识别 + PDF 转换三合一，MIT 协议适合商业使用。相比 Mathpix 的核心功能完全不付费。

一句话推荐结论

写学术笔记、处理含公式的 PDF、或做 OCR + LLM pipeline——先试 Pix2Text 网页版确认效果，符合预期后再 pip install pix2text 做本地批处理，省掉 Mathpix 订阅费。

来源

• GitHub：https://github.com/breezedeus/Pix2Text
• 在线文档：https://pix2text.readthedocs.io
• 在线服务：https://p2t.breezedeus.com
• HuggingFace Demo：https://huggingface.co/spaces/breezedeus/Pix2Text-Demo
• Release Notes：https://pix2text.readthedocs.io/zh-cn/stable/RELEASE
• CnOCR（文字识别引擎）：https://github.com/breezedeus/cnocr
• DocLayout-YOLO：https://github.com/opendatalab/DocLayout-YOLO

⚠️ V1.1.5（2026.02.07）为当前最新版本（基于 PyPI 收录信息），实际 PyPI 发布页面请以 pip show pix2text 输出为准。