pix2tex：开源免费公式OCR，截图秒变LaTeX代码

线代写过论文或整理过技术文档的朋友估计都跟公式排版搏斗过。手敲 LaTeX 公式有多折磨人用过的都懂一个希腊字母挨一个查一个矩阵结构试半天遇到带分式的复杂公式更是恨不得摔键盘。后来大家习惯用 Mathpix 拍照截图直接转 LaTeX 代码确实方便但免费额度一个月就那几次用完了要么掏钱订阅要么手动录入效率又重新被打回原形。这篇文章要聊的是一个能替代 Mathpix 的开源方案pix2tex也就是大家常说的 Latex-OCR。它同样能把公式截图甚至照片直接转换成 LaTeX 源码完全本地运行不用联网不消耗任何商业 API 额度理论上你可以无限次数使用。对于经常处理公式的学生、科研人员、做技术文档的工程师来说这是一个非常值得掌握的免费工具。我会从安装环境讲起然后是命令行快速上手再到 Python API 调用和批量处理脚本最后把我在实际使用中踩过的坑和排查办法整理出来。无论你是第一次听说这个工具还是已经试过但没跑通这篇文章都值得看一看。1. 内容整体设计与思路拆解1.1 从公式截图到 LaTeX 代码这个工具到底做了什么先理解一下 pix2tex 的本质。Mathpix 和 pix2tex 这类工具的核心任务是在做一次“图像到结构化文本”的转换。你输入一张公式截图它要识别出图片里的数学符号、字母、数字、上下标、分式、根号、矩阵等结构然后把这些视觉元素映射成一段 LaTeX 源码。这个过程和普通的 OCR比如识别文档里的一段中文或英文文字不一样的地方在于数学公式天然带有二维空间结构。比如 x 的平方平方的“2”不是在 x 旁边而是在 x 的右上角这个位置关系用普通 OCR 是识别不出来的必须依赖一个能理解“空间布局 → 结构语法”的模型。pix2tex 的做法是用视觉编码器提取图像特征再用类似 Transformer 的序列解码器逐步生成 LaTeX token 序列。有过图像理解或 NLP 背景的朋友看到这个架构应该会觉得很眼熟——它本质上就是一个 image-to-text 的序列生成任务只是把目标输出从自然语言换成了 LaTeX 语言。我最初研究这个工具的时候也担心过开源模型的效果会不会比商业产品差太多。实际用下来之后我的判断是对绝大多数常规公式比如论文里常见的行内公式、求导、积分、矩阵、分段函数pix2tex 的识别质量是完全可以接受的。如果对比预算和可用的次数上限这个免费开源工具的综合性价比其实远高于商业方案。1.2 为什么选择 pix2tex 而不是继续用 MathpixMathpix 的免费额度有限对高频用户不够友好这是很多人寻找替代品最直接的原因。除此之外还有几个值得考虑的点第一Mathpix 是云端服务截图内容会传到对方的服务器上虽然一般商业产品在隐私条款上都有承诺但对于还没公开的研究成果或公司内部文档部分人会有顾虑。pix2tex 是完全本地推理的不需要把图片发给任何人这在数据安全性上是一个明显优势。第二Mathpix 的订阅费用在同类工具里并不便宜而且如果只是偶尔用几次按订阅制付费感觉不太划算。开源工具则是零成本起步你付出的是折腾环境的时间换来的是充分的自由度。第三pix2tex 可以嵌入到自己的工具链里。比如我后来写了一个脚本自动截取屏幕区域识别公式后直接把 LaTeX 代码写入剪贴板整个过程不到三秒。这种深度定制能力是闭源产品做不到的。1.3 整体使用方案概览以我自己的经验一套完整的使用方案分几个层次。第一层是直接使用官方提供的命令行工具适合不写代码、只要偶尔转一张截图的用户。第二层是编写 Python 脚本调用 pix2tex 的 API适合需要批量处理、定制预处理流程、或者想把公式识别功能嵌入到自己程序里的场景。第三层是前后端结合比如用 Gradio 或 FastAPI 搭一个简单的 Web 界面可以在局域网的任何设备上访问这个适合团队内部共享或者不想在每台设备上都配 Python 环境的场景。文章接下来的章节我按照这几个层次逐步展开从最简单的命令行动手到 Python API 的核心参数和调用细节再到实际操作中遇到过的典型问题和解决思路。2. 安装环境与初始配置2.1 硬件与软件要求先说实话pix2tex 对硬件还是有一定要求的。模型本身不算大但它基于深度学习框架运行推理的时候需要加载预训练权重并执行计算。如果是纯 CPU 环境速度会稍微慢一些一张普通的公式截图可能要等一两秒。如果你有 NVIDIA 显卡并装了 CUDA 版本的 PyTorch推理速度会明显提升几乎能做到毫秒级响应。我的建议是如果你的电脑有独显尽量装 CUDA 版本的 PyTorch。如果没有也不要太担心CPU 跑起来没有想象中那么慢尤其是模型加载完成后识别单张图片的速度完全在可用范围内。操作系统方面Windows、macOS、Linux 都有对应的安装方式下面的步骤我会以 Windows 和 Linux 为主macOS 用户基本同理只是个别依赖包名称可能略有不同。Python 版本建议 3.8 到 3.11 之间。这个项目对 Python 版本是有隐性要求的太高版本的 Python 可能还没等 pix2tex 适配其他依赖库就已经出兼容问题了。我自己在 3.10 和 3.11 上都跑通过3.12 没试过建议稳妥起见不要用最新版。2.2 快速安装 pytorch关键一步pix2tex 的底层依赖是 PyTorch这一步是大多数环境安装失败的根源。很多朋友直接执行pip install pix2tex然后看到安装过程报错或者运行时提示找不到 torch问题就出在这里。正确做法是先去 PyTorch 官网根据你的环境复制对应的安装命令。这里有一个非常关键的区别如果你需要 CUDA 加速就不要用 pip 默认安装的 CPU 版 PyTorch因为默认源安装的 torch 通常不支持 GPU。注意安装 PyTorch 时不要图省事直接pip install torch。请前往 PyTorch 官网选择你对应的操作系统、包管理器和 CUDA 版本复制官方给出的安装命令。这一步能避免很多后续问题。以 CUDA 11.8 为例Linux 下的安装命令类似pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118Windows 用户用的是同样的命令只是系统环境不同。如果纯 CPU 环境可以执行pip3 install torch torchvision torchaudio安装完成后建议先验证一下 PyTorch 是否正常import torch print(torch.__version__) print(torch.cuda.is_available())如果torch.cuda.is_available()返回 True说明你的 PyTorch 能识别显卡后面模型推理就会快很多。如果返回 False 但你已经安装了 CUDA 版就要检查显卡驱动和 CUDA 版本是不是匹配这点后面再细说。2.3 源码安装 pix2tex推荐使用源码安装而不是直接pip install pix2tex。源码安装有几个好处一是你可以随时拉取最新的更新和 bug 修复二是源码目录里有完整的测试脚本和权重下载说明方便排查问题三是我遇到的某些版本问题在源码版本中根本不存在。源码安装其实非常简单命令就是标准流程git clone https://github.com/lukas-blecher/LaTeX-OCR.git cd LaTeX-OCR pip install -r requirements.txt pip install -e .关键点在于pip install -e .这个命令不仅会安装项目本身的依赖还会把项目以可编辑模式装进环境里保证latexocr命令和 Python 包pix2tex都能被正确识别。如果不想走源码直接pip install pix2tex也能成功但我在实际使用中遇到过命令行入口找不到、权重文件路径不对等问题源码安装反而更省心。建议有动手能力的朋友直接用源码方式。2.4 初始化并下载模型权重安装完成后首次运行工具时会自动下载预训练模型权重大小大概在 100 到 200MB 之间具体体积视版本而定。官方权重托管在 GitHub 的 release 页面国内网络环境下有可能下载失败这里提供一个解决思路你可以手动去 GitHub 找到对应版本的权重文件一般是.pth文件放到本机缓存目录。模型文件的存放路径在不同系统下不太一样通常是通过checkpoints参数指定的。在源码目录下有一个默认的 checkpoint 路径一般位于用户目录下的.pix2tex或类似隐藏文件夹里。如果你不确定可以运行一次命令看日志里输出的路径信息。我当时的做法是先用浏览器手动下载权重文件然后根据源码里pix2tex/model/settings.py文件中配置的路径把文件复制过去。这样能绕开命令行下载时的网络问题。如果你网络环境较好直接让它自动下载就好这个权重文件是公式识别模型的核心没有它程序无法运行所以这个步骤马虎不得。3. 命令行快速上手离线公式识别的第一现场3.1 latexocr 命令的使用安装并初始化完成之后第一步就是打开终端Windows 上是 CMD 或 PowerShell输入命令latexocr。这个命令会启动一个图形界面的交互窗口。它会自动打开摄像头如果是桌面版或者等待你拖拽图片文件进去。实际操作很简单你截一张公式图片然后把这个图片文件直接拖进 latexocr 的窗口等待一两秒窗口里的识别结果区域就会出现 LaTeX 源码。界面上还会有复制按钮点击一下就直接把 LaTeX 代码复制到系统剪贴板了方便你立刻粘贴到论文或文档里。命令行还有非交互式的用法适合不打开图形界面、直接在脚本中调用。比如latexocr --image path/to/formula.png这种方式会直接把识别结果打印在终端里。如果你只是想快速测试一张图片不需要图形界面这个方式更高效。需要注意的是某些版本的命令行参数可能略有区别如果不确定先在终端运行latexocr --help看看帮助信息里有哪些可选参数。3.2 GUI 模式下的实用操作细节GUI 模式看起来简单但有几个小细节值得注意。第一拖拽图片进窗口后程序不会立刻开始识别而是会等图片加载完成所以不要重复拖拽容易造成程序卡顿。第二如果你的图片分辨率很高程序会自动缩放图片这个缩放过程可能会影响最终识别效果尤其是非常小的上下标。这时候可以用截图工具先把关键区域裁剪出来再拖入。第三GUI 模式识别结果有时不止一个候选如果你看到结果不是预期的公式可以看看界面上是否有备选结果切换的功能。在实际版本中有些版本提供了多个候选输出的选项有些版本没有这一点不用强求命令行和 API 反而更容易做这种扩展。3.3 批量识别场景下的命令行限制命令行模式虽然方便但处理批量图片时比较局限。比如你有 50 张公式截图想一次性全部转换成 LaTeX 代码直接用命令行一条条跑效率偏低。这种场景我建议直接跳到下一节用 Python 脚本批量处理。我也试过在终端里写一个 for 循环不断调用latexocr --image但每次启动都会重新加载模型耗时太长不推荐这种方式。4. Python API 调用与批量处理4.1 核心 APIpix2tex 的模型加载与推理大多数有代码能力的使用者最终都会选择在 Python 环境里直接调用 pix2tex这样自由度最高。核心代码如下from PIL import Image from pix2tex.cli import LatexOCR # 初始化模型加载预训练权重 model LatexOCR() # 打开公式图片并识别 image Image.open(formula.png) result model(image) print(result)上面这段代码就是这个工具的“最小可用集”。看起来简单但真实的调用过程中有非常多细节需要注意。LatexOCR()初始化时会加载模型权重如果是第一次运行它会检查权重文件是否存在于本地不存在就会尝试下载。这个过程可能需要几十秒甚至更久取决于网络情况。初始化完成后后续的多次推理不会重复加载模型所以尽量只初始化一次然后在循环里重复使用。model(image)接受的参数是 PIL 的 Image 对象不是文件路径。所以每次识别前你需要先用Image.open()打开图片。还有一点Image.open()并不会立即把图片数据读入内存它是惰性加载的只有在你执行model(image)时才会真实解码。所以如果你在循环里反复打开同一张图片要注意及时用image.close()释放资源否则文件句柄会越积越多最终导致资源耗尽的报错。4.2 图片预处理对识别率的影响实际测试下来pix2tex 对图片质量的要求不算苛刻但有一些预处理动作能明显提升识别准确率。最核心的一条是尽量让图片中的公式主体在画面中占比更大背景干扰更少。具体来说如果你截取的图片包含大块空白边缘或者混有正文文字、水印、线条等噪声识别的出错率会上升。我在自己的脚本里加了这样几步预处理将图片转为灰度图Image.convert(L)增加对比度让公式部分更清晰自动裁剪图片周围多余的空白区域。from PIL import Image, ImageOps, ImageEnhance def preprocess_image(path): img Image.open(path) img img.convert(L) # 灰度化 img ImageOps.autocontrast(img) # 自动增强对比度 img ImageOps.expand(img, border10, fillwhite) # 四周加白边 return img这里有一个值得说的细节我特意给图片四周加了一圈白边这个操作的目的是给模型留出足够的“呼吸空间”。因为模型在训练时很多训练样本是带一定边距的如果截图恰好从公式边界开始切识别效果反而会下降。留出白边相当于让输入分布更接近训练数据实测对识别率有一定的正面影响。如果你处理的图片是深色背景比如某些 IDE 的深色主题截图建议先反色处理把背景转成白色、文字转成黑色否则模型的表现可能会变差。反色操作很简单PIL 里用ImageOps.invert()即可。4.3 利用温度参数获取多个候选结果pix2tex 的模型是一个序列生成模型它内部通过某种采样策略来生成 LaTeX token 序列。默认情况下它采用贪心解码也就是每一步都选择概率最大的 token这样只会得到一个结果。但在某些复杂公式上贪心解码的结果可能不是最优的。官方 API 提供了一种方式可以通过调整解码参数获得多个候选结果。我在实践中发现在model(image)调用时传入temperature参数可以控制解码的随机程度从而得到多样化的输出。result model(image, temperature0.2)不过要注意temperature参数的存在和具体名称在不同版本里可能有差异。如果你用的版本不支持直接传这个参数可以考虑修改pix2tex的源码找到模型解码的相关代码调整采样策略。这一块比较进阶普通用户可以不深究但知道这个机制的存在是有好处的——当你遇到一个公式怎么都识别不对不妨换一个随机种子或调一下温度或许就能得到正确结果。4.4 批量识别的实战脚本我写了这样一个脚本专门用于批量处理一个文件夹里的所有公式截图并将结果保存为 Markdown 文件import os from PIL import Image, ImageOps, ImageEnhance from pix2tex.cli import LatexOCR model LatexOCR() def preprocess(path): img Image.open(path) img img.convert(L) img ImageOps.autocontrast(img) img ImageOps.expand(img, border10, fillwhite) return img results [] input_dir formulas output_file output.md for filename in sorted(os.listdir(input_dir)): if not filename.lower().endswith((.png, .jpg, .jpeg)): continue path os.path.join(input_dir, filename) img preprocess(path) latex model(img) results.append(f### {filename}\n\nlatex\n{latex}\n\n) print(f{filename} - {latex}) with open(output_file, w, encodingutf-8) as f: f.write(\n.join(results))这个脚本的逻辑很简单遍历输入目录里的所有图片做相同的预处理每张图片调用一次model()然后把文件名和对应的 LaTeX 代码按顺序写入一个 Markdown 文档。这样你得到的 output.md 直接就能作为笔记素材或者进一步人工校对修改。实际跑起来的时候50 张图片在 GPU 环境下不到一分钟就能完成CPU 环境下可能需要几分钟。这个速度已经完全满足日常批量整理笔记的需求了。5. 常见问题与排查技巧实录5.1 模型初始化时报错找不到权重文件这是我遇到最多的一个问题。症状是运行LatexOCR()或第一次执行latexocr命令时程序报错说找不到.pth文件。原因一般是权重文件没有成功下载或者下载到了错误的位置。排查思路先确认你的网络能不能正常访问 GitHub。如果能就尝试删除本地旧的缓存目录重新跑一次让程序重新下载。如果不能就去 GitHub 手动下载权重文件把它放到源码里指定的路径下。权重文件的具体路径在pix2tex/model/settings.py里能看到一般是checkpoints目录。你只需要把文件复制到那个目录再次运行程序就能正常加载。顺带说一下如果你更新了 pix2tex 的版本最好也更新权重文件新旧不匹配时会导致识别结果出现大量乱码或者直接报维度错误。5.2 识别结果总是出现不相关的字符有时候明明是一张很简单的公式图片输入进去却识别出一堆莫名其妙的字母。这种情况多半是图片没有做好预处理。最常见的问题就是图片的对比度不够或者是彩色背景干扰。比如有一张带浅灰色底纹的公式截图直接丢给模型识别结果可能一塌糊涂。但先转成灰度图、增加对比度后再识别就完全正常。如果图片是反色的深色背景一定要先反色处理。记住这个原则你喂给模型的图片应该是白底黑字、公式清晰、无多余噪声的状态。如果图片质量很好但仍然识别错乱可以考虑把公式区域裁剪得更紧凑一些去掉边缘的非公式元素比如页码、题注、横线等。5.3 GPU 能识别但速度很慢如果你安装了 CUDA 版本的 PyTorch但推理速度还是像 CPU 一样慢首先要确认程序是不是真的在用 GPU 推理。在调用模型的代码里加入以下检查import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果torch.cuda.is_available()返回 False说明你的 PyTorch 其实是 CPU 版本或者 CUDA 环境变量没有配置好。常见原因有两个一是安装 PyTorch 时用了默认 PyPI 源装的是 CPU 版二是显卡驱动版本太旧和 PyTorch 需要的 CUDA 版本不匹配。重新安装正确的 PyTorch 版本后速度会显著改善。如果你实在搞不定 GPU 加速CPU 跑也不是不能用只是每张图片要多等一两秒。5.4 GUI 界面偶尔卡死或闪退GUI 模式的稳定性在不同系统上表现不太一样Windows 上相对稳定Linux 上如果缺少某些图形库可能会闪退。遇到这种情况我的建议是优先使用命令行模式或 Python API图形界面本身只是个便利工具不是核心功能。另外GUI 窗口处理大尺寸图片时容易卡顿尽量控制在 2000 像素宽度以内过大的图片先缩放再拖入体验会好很多。5.5 表格、复杂矩阵的识别效果不如预期坦白说pix2tex 的核心能力集中在常见数学公式上对于非常复杂的矩阵、带大量对齐环境的公式、或者某些特殊数学符号识别率会有明显下降。这里给你一个实用建议遇到这种复杂结构先把它拆成若干小公式分别识别然后把 LaTeX 代码手动拼起来。比如一个 4 行 4 列的大矩阵直接识别往往会有行列错位。但如果拆成两三个小块分别识别拼接时的正确率提高很多。这个算是“开源工具使用者的妥协艺术”虽然绕了一些弯路但最终的 LaTeX 代码质量是有保障的。5.6 命令行参数进化的追踪方式不同版本的 pix2tex 在命令行参数上有些变化如果你在使用时发现某个参数不起作用或者报错不要急着怀疑是代码问题先去项目 GitHub 仓库的 README 和 release notes 查看最新说明。开源项目迭代速度很快可能上个版本有某个参数这个版本就改名字了。另外GitHub 的 Issues 区是排查问题的宝库很多用户遇到的坑都有解决方案用英文搜索关键词比如找不到权重文件、识别错误等往往能直接找到答案。6. 进阶玩法把这套工具嵌进你的工作流6.1 用剪贴板无缝衔接截图与 LaTeX 代码我知道很多人平时的工作流是看到一段公式 → 截图 → 打开 Mathpix → 得到 LaTeX → 粘贴到文档中。用 pix2tex 之后你可以把中间步骤进一步压缩做成一个“截图即得代码”的脚本。思路是用 Python 监听剪贴板或监听某个快捷键一旦触发就截取当前屏幕区域自动跑识别并把结果写回剪贴板。这样你甚至不需要打开任何窗口整个过程就像按了一下相机快门。我自己写过一个简化版通过键盘监听库获取快捷键按下后调用系统截图工具截取区域然后传给 pix2tex 模型最后把 LaTeX 代码写入剪贴板。整个过程大概 3 秒钟。虽然不像商业工具那样有华丽界面但实用程度一点不差。6.2 部署一个局域网内可用的公式识别服务如果你的实验室或团队成员都有公式识别的需求可以在服务器上部署一个 Web 界面大家通过浏览器访问无需在本机安装任何依赖。用 Gradio 可以快速搭建一个网页核心代码不复杂import gradio as gr from pix2tex.cli import LatexOCR model LatexOCR() def predict(image): if image is None: return return model(image) gr.Interface(fnpredict, inputsgr.Image(typepil), outputstext).launch(server_name0.0.0.0, server_port7860)这个界面支持上传图片或直接粘贴截图返回 LaTeX 代码支持一键复制。部署一次全组共享比每个人都折腾一遍本地环境要省事得多。这个方法特别适合 Windows 和 Linux 混合环境下的团队因为摆脱了本机系统差异的困扰。6.3 在 Jupyter Notebook 或 Markdown 写作工具里内嵌如果你经常用 Jupyter Notebook 做数据分析或整理实验记录可以把 pix2tex 封装成一个魔法命令直接在 notebook 里调用。这样你看到一篇 PDF 里的公式截图后传进去Notebook 里就直接出现 LaTeX 代码整理笔记效率翻倍。如果你用 Obsidian 或 Typora 这类支持 LaTeX 的 Markdown 编辑器pix2tex 生成的代码直接粘贴即可渲染完全无缝。配合剪贴板脚本你甚至可以在 Obsidian 里保持“截图 → 粘贴 → 渲染公式”的流畅体验。结尾一点个人体会在把 pix2tex 当作主力公式识别工具用了大半年之后我最深的感受是开源工具也许在开箱即用的体验上不如商业产品那么顺滑但它的上限远高于闭源工具。你愿意花一两个小时调通环境、写几个脚本就能换回近乎无限的免费识别次数还能按自己的需求定制工作流。本文章中的安装和调用步骤我已经尽量按最容易踩坑的顺序展开如果你在操作中遇到这里没写到的问题建议先去项目 GitHub 的 Issues 区搜索绝大多数问题都有现成的答案。如果你成功跑通了整套流程不妨试试进阶玩法把公式识别真正嵌入到自己的写作、备课、科研工作流里去那种顺畅感是值得体验的。