Surya 2.5 GGUF

Surya 2.5 GGUF

从文档图像里读取文字、表格和版面，并以文字返回。这是 Surya 2.5 OCR 模型面向 llama.cpp 的 GGUF 版本，适合想在自己电脑上运行文档 OCR 的人。

由 datalab-to 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：这个仓库提供 Surya 2.5 的 GGUF 版本，Surya 是 Datalab 的 OCR 模型，这些版本用于在 llama.cpp 下运行。Surya 读取页面图像，返回文字，并带有版面标签、阅读顺序和 HTML 格式的表格。仓库里有 bf16 和 8-bit 文件，还有一个视觉投影文件，两种模型文件都需要搭配它。

适合谁：需要在自己的硬件上把扫描页面和文档图像转成文字，并且愿意运行本地服务器的人。

Industry | Who uses it | How they use it | Example
文档处理 | 把纸质记录数字化的团队 | 在本地部署模型，并把页面扫描件发给它 | 把一叠扫描表单转成文字
法律与金融 | 处理 PDF 和扫描件的人员 | 从文档图像里提取文字和表格 | 把一份扫描对账单里的表格提取为 HTML
研究 | 构建文档流程的开发者 | 把 GGUF 版本当作自己工具里的 OCR 环节 | 在自己的页面上比较 8-bit 和 bf16 文件

如果你想要托管的 OCR 服务，或者不想运行 llama.cpp，可以跳过它。

用在哪里：它在 llama.cpp 下运行，文件可以在 Windows、macOS 或 Linux 上下载。模型卡提到自动设置适用于 Apple Silicon 和 CPU。

• llama.cpp：通过 llama-server 提供 GGUF 文件的服务
• surya-ocr Python 包：可以替你启动服务器
• Apple Silicon 或 CPU：这个包会自动完成设置的环境

Use case | Who | What they get back
整页 OCR | 文档团队 | 一页图像里的文字
版面分析 | 流程开发者 | 区块标签和阅读顺序
表格提取 | 分析人员 | 以 HTML 返回的表格

如何设置：你需要 Python 和 llama.cpp，以及这三个文件。

• 带 pip 的 Python
• 带 llama-server 的 llama.cpp
• 视觉投影文件，两种模型文件都需要搭配它

1. 安装 Hugging Face hub 库并下载文件。
2. 或者安装 surya-ocr 包，它会获取 bf16 文件，并在 Apple Silicon 或 CPU 上自行启动服务器。
3. 如果想自己部署，用两个文件运行 llama-server。
4. 设置两个 Surya 环境变量 SURYA_INFERENCE_BACKEND 和 SURYA_INFERENCE_URL，让 Surya 连接到你的服务器。

pip install -U huggingface_hub
hf download datalab-to/surya-ocr-2.5-gguf

更快的方式：

pip install surya-ocr

自己部署服务：

llama-server -m surya-2.5.gguf --mmproj surya-2.5-mmproj.gguf --jinja --special \
  --parallel 8 --ctx-size 98304 -ngl 99 --port 8080

如何使用：先启动服务器，把 Surya 指向它，再对页面图像运行 OCR。special 参数是必需的，因为区块标签和坐标只有带上它才会返回。

Tool | What it does
llama-server | 通过本地端口提供 GGUF 模型服务
--mmproj | 加载视觉投影文件
--special | 必需，返回区块标签和坐标
--parallel 8 | 同时处理八个请求

示例：你用 Surya 的文件启动 llama-server，并发给它一张整页扫描件。你会得到这一页的文字，以及区块标签、坐标和阅读顺序，表格则以 HTML 返回。

新手与专家：如果你刚接触这类模型，先安装 surya-ocr，让它替你启动服务器。先给它一张清晰的页面扫描件，再把文字和页面对照检查。

如果你熟悉这个领域，模型卡报告了一次在 M4 Max 上用 8 个并行请求做的速度测试。Surya 2.5 完成了全部 32 页，而 Surya 2 在达到 token 上限前完成了 28 页。8-bit 文件在速度相近的情况下占用的内存比 bf16 更少。

Title: 模型卡的速度测试，32 个整页请求
Model | Pages per second | Peak memory
Surya 2 in bf16 | 0.061 | 5,875 MB
Surya 2.5 in bf16 | 0.190 | 4,764 MB
Surya 2.5 in Q8_0 | 0.198 | 4,278 MB

页面图像发送到 llama-server
Surya 2.5 读取文字和版面
返回区块标签和坐标
你使用文字和 HTML 表格

注意事项：作者报告 Surya 在 OmniParseBench 上得分 85.9，在 olmOCR-bench 上为 83.7%，这些是他们自己的数字。

• License: Hugging Face 记录为 OpenRAIL，模型卡的徽章显示代码为 Apache 2.0，模型为 OpenRAIL-M
• Cost to run: 本地使用未提及费用，不过 Datalab 还提供一个可选的托管平台
• Data it reaches: 你发给本地服务器的页面图像
• Not for: 表格的行列几何信息，这需要 Surya 2 检查点

Hugging Face 上的数据（2026年11月13日）

• 任务：image text to text
• 框架：transformers
• 参数量：589M
• Weights: about 294 MB at 4-bit (estimate)
• Formats: GGUF
• 最近 30 天下载：126,232
• 点赞：8
• 许可证：openrail
• 基于：datalab-to/surya-ocr-2.5
• 标签：transformers, gguf, qwen3_5, image-text-to-text, markdown, layout, conversational

链接

• 模型：https://huggingface.co/datalab-to/surya-ocr-2.5-gguf
• 文件：https://huggingface.co/datalab-to/surya-ocr-2.5-gguf/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download datalab-to/surya-ocr-2.5-gguf

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。