kingyiusuen/image-to-latex · 上手攻略

仓库：kingyiusuen/image-to-latex
链接：https://github.com/kingyiusuen/image-to-latex
分类：学术工具 · 图像识别 · LaTeX
作者：Tom
更新：2026-08-21

这是什么

image-to-latex 是一个将数学公式图像转换为 LaTeX 代码的深度学习项目，使用 ResNet-18 作为图像编码器、Transformer 作为解码器，在 im2latex-100k 数据集上训练，测试集字符错误率（CER）约为 0.17。项目为独立研究者作品，没有商业依赖，适合学术写作者、科研人员和教育场景快速将印刷或手写的数学公式转为可编辑 LaTeX 代码。

解决的问题：在撰写学术论文时，将 PDF 或网页中的数学公式手动转写为 LaTeX 极其耗时；同类商业工具（如 Mathpix Snip）需付费，本项目提供了一个开源、可自托管、效果接近商用水平的替代方案。

快速安装

系统要求

Python 3.8+
CUDA（GPU 训练/推理，非必须但强烈推荐）
约 30 GB 磁盘空间（数据集 + 预训练模型）
建议使用虚拟环境（venv 或 conda）

安装步骤

# 克隆仓库
git clone https://github.com/kingyiusuen/image-to-latex.git
cd image-to-latex

# 创建虚拟环境并安装依赖
make venv
make install-dev

# 下载数据集并预处理（约 1+ 小时，图像裁剪最耗时）
python scripts/prepare_data.py

⚠️ 注意：prepare_data.py 的图像裁剪步骤可能超过 1 小时，这是数据集预处理的一部分，无法跳过。如仅需使用预训练模型做推理，可跳过此步直接下载 checkpoint。

下载预训练权重

项目使用 Weights & Biases 管理模型权重：

# 安装 wandb（如未安装）
pip install wandb

# 下载作者最佳模型（测试集 CER=0.17）
python scripts/download_checkpoint.py kingyiusuen/image-to-latex/1w1abmg1

# 权重保存到 artifacts/ 目录

核心用法

启动推理 API（FastAPI）

# 启动 API 服务
make api

# 文档界面：http://0.0.0.0:8000/docs

API 为 REST 接口，支持上传公式图像并获取 LaTeX 预测结果。

启动 Streamlit 可视化界面

# 需要先启动 API（在另一个终端）
make api

# 启动 Streamlit 前端
make streamlit

# 浏览器访问：http://localhost:8501

Streamlit 界面支持截图/上传公式图像、实时预览 LaTeX 渲染结果。

训练自己的模型

# 使用 1 块 GPU 训练（默认配置）
python scripts/run_experiment.py trainer.gpus=1 data.batch_size=32

# 使用 2 块 GPU
python scripts/run_experiment.py trainer.gpus=2 data.batch_size=64

# 修改学习率等其他参数（参考 conf/config.yaml）
python scripts/run_experiment.py trainer.gpus=1 optimizer.lr=0.0005

配置通过 Hydra 管理，支持命令行覆盖任意参数。

核心代码逻辑（伪代码示意）

# 模型结构（参考 project 描述，非可直接运行代码）
# Encoder: ResNet-18（取到 block3，减少参数）
# Decoder: Transformer（cross-entropy loss）
# 约 300 万参数

# 推理流程
image = load_and_preprocess("formula.png")  # 数据增强：随机缩放、高斯噪声
tokens = model.encode(image)                # ResNet-18 图像编码
latex = model.decode(tokens)                # Transformer 解码为 LaTeX token 序列
print(latex)                               # 输出 LaTeX 字符串

典型适用场景

学术论文写作：将 PDF 中公式快速转写为 LaTeX，减少手动录入
笔记整理：将教科书、网页中的公式数字化
竞赛答案整理：数学竞赛答案的格式转换
模型研究：作为 im2latex 任务的基线模型进行改进

坑与注意

⚠️ 数据集偏差：模型在 im2latex-100k 测试集上 CER=0.17，但该数据集预处理（统一尺寸、格式标准化）与真实场景（网页截图、扫描件）差距较大。真实场景准确率显著低于测试集指标。

⚠️ 水平间距歧义：LaTeX 中 \quad 和 \, 等水平间距命令视觉上完全等价，但模型输出可能混用，导致 CER 被高估。实际渲染效果可能比分数显示的更好。

⚠️ 大型公式识别差：训练数据中公式尺寸相对统一，模型对大幅面公式（超过数据集平均尺寸）的识别效果退化明显。

⚠️ 仅支持数学公式：不含正常文本的纯数学公式，不适合带文字说明的混合内容页面。

⚠️ greedy search 而非 beam search：推理时使用贪婪解码，理论上 beam search 可进一步降低 CER，但代码未实现。

⚠️ 无预训练模型直接下载：权重需通过 download_checkpoint.py + wandb 下载，国内网络可能需要代理。

⚠️ v1 版本维护状态：README 反映的是早期版本（2021 年前后）状态，代码未持续更新，新功能（如 beam search）未合并。⚠️ 版本信息基于 2026-08-21 GitHub README，实际情况请以仓库最新版本为准。

与同类对比

方案	参数量	自托管	开源	中文公式	备注
image-to-latex	~3M	✅	✅	❌	CER=0.17（测试集），学术项目
Mathpix Snip	—	❌	❌	✅	商业付费，精度高，支持手写
LaTeX-OCR (pix2tex)	~35M	✅	✅	部分	基于 Vision Transformer，效果更好
im2markup (Harvard)	~9.5M	✅	✅	❌	原始论文实现，较大但更通用
Amazon Textract	—	❌	❌	✅	商业 API，按调用收费

核心差异：本项目 vs LaTeX-OCR（pix2tex）：LaTeX-OCR 使用更现代的图像编码器（如 ViT），参数量更大但实际效果更稳定；本项目轻量但更适合作为学术基线研究。

一句话推荐结论

适合学术写作者快速将印刷公式转为 LaTeX 的轻量工具，实测精度略低于商用方案 Mathpix Snip 和开源的 LaTeX-OCR（pix2tex），但胜在代码完全可审计、修改无商业限制；注意测试集指标（CER=0.17）与真实场景存在较大差距，重要公式务必人工校验。