[开源]一个 Rust 库搞定 macOS/Windows/Linux 三端 OCR：uniOCR 的 6 个使用要点

一、它到底解决什么问题？

每天打开电脑，需求很简单：把一张图里的文字抠出来。

但写过的人都知道这事并不简单：

• • macOS 上想用最快的方式，得调 Vision Kit 的 Swift API
• • Windows 上得调 Windows.Media.Ocr，C# / WinRT 一套接口
• • Linux 上没得选，只能装 Tesseract，再处理一堆动态链接和模型路径
• • 接入云服务商（Google、AWS、Azure），又是另一套 SDK 和鉴权

结果就是：一个 OCR 功能，三端三套代码，加上云端能扩到第四套。

uniOCR 就是为了这件事而生的——一个 Rust crate，把上面这些底层差异全部封进同一个 OcrEngine 接口。你写一次代码，三端跑通，云端切换只换枚举值。

今天这篇，给你 6 个使用要点，照着做就能跑。

uniOCR 跨平台架构示意

二、5 秒看懂 uniOCR 的定位

先把它放进表格里，避免选型踩坑：

一句话总结：本地优先、跨平台、Rust 原生，适合放进客户端、桌面 Agent、Screenshot pipeline。

三、上手清单：6 个使用要点

要点 1：加依赖，一行搞定

打开你的 Cargo.toml，在 [dependencies] 下加一行：

[dependencies]
uni-ocr = { git = "https://github.com/mediar-ai/uniocr.git" }
tokio = { version = "1", features = ["full"] }
anyhow = "1"

注意两点：

1. 1. crates.io 上发布名是 uni-ocr（中划线），import 时是 uniocr（无连字符），别写错
2. 2. 它依赖 tokio 异步运行时，记得一并加好

要点 2：3 行代码完成第一次 OCR

最小可运行示例，复制即用：

use uniocr::{OcrEngine, OcrProvider};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    let engine = OcrEngine::new(OcrProvider::Auto)?;
    let text = engine.recognize_file("path/to/image.png").await?;
    println!("extracted text: {}", text);
    Ok(())
}

关键点：

• • OcrProvider::Auto 会自动挑当前系统最快的引擎（macOS → Vision，Windows → Win OCR，Linux → Tesseract）
• • 整个 API 是 async，方便嵌进现有异步管线
• • 返回的就是 String，不用再解析中间结构

如果你只是想"识别一张图"，到这里就结束了。下面的要点是给真要把它放进生产代码的人看的。

要点 3：根据场景选 Provider，别全交给 Auto

Auto 适合 demo，但生产环境建议显式指定：

// 强制走 macOS 原生 Vision（精度 90%，速度 3.2 张/秒）
let engine = OcrEngine::new(OcrProvider::MacOS)?;

// 强制走 Windows 原生引擎（精度 95.2%，速度 1.2 张/秒）
let engine = OcrEngine::new(OcrProvider::Windows)?;

// 跨平台保底：走 Tesseract
let engine = OcrEngine::new(OcrProvider::Tesseract)?;

选型口诀：

• • 要速度 → macOS 原生
• • 要精度 → Windows 原生
• • 要可移植 / Linux 服务器 → Tesseract
• • 要批量识别 + 不在意成本 → Cloud（仓库里预留了接口）

Provider 选型决策图

要点 4：用 OcrOptions 调优识别效果

光会喊"识别"不够，真实业务里你要做的事是：

• • 限定语言（多语言扫描时尤其关键）
• • 设置置信度阈值，过滤垃圾结果
• • 加超时，防止挂住主线程

uniOCR 给了一套链式 API：

use uni_ocr::{OcrEngine, OcrProvider, OcrOptions};

let options = OcrOptions::default()
    .languages(vec!["eng", "fra"])
    .confidence_threshold(0.8)
    .timeout(std::time::Duration::from_secs(30));

let engine = OcrEngine::new(OcrProvider::Auto)?
    .with_options(options);

经验值参考：

要点 5：批量识别走 recognize_batch，别自己写循环

如果你一次要处理 N 张图（典型场景：屏幕录制后切帧、PDF 页转图），别 for 循环 + await：

let images = vec!["img1.png", "img2.png", "img3.png"];
let results = engine.recognize_batch(images).await?;

recognize_batch 内部做了并行调度，根据 README 说法是"async/await + parallel processing + memory efficient"，并强调了"unsafe 部分是经过内存泄漏压力测试的"。

实测建议：

• • 批次大小：单批 50–100 张是甜点区，太大反而 GC/内存压力大
• • 顺序无关：返回顺序与输入顺序对齐，可放心用 index 关联原始数据
• • 失败容忍：当前版本一张失败可能影响整批，重要任务可分批重试

要点 6：装好平台依赖，再去跑你的代码

很多人第一次跑出错，不是代码问题，是环境没装齐。一份对照清单：

⚠️ 用 Tesseract 时记得装语言包（中文要 tesseract-ocr-chi-sim，否则识别中文一团乱码）。

三端依赖安装速查表

四、性能数据：什么时候选哪个引擎？

仓库里给出的 benchmark 是在 M4 MacBook Pro Max 上跑的（单位：images/second）：

读这张表的正确姿势：

1. 1. macOS 上要快，就别想 Tesseract——Vision 是这个量级里最快的
2. 2. Windows 慢但准——95.2% 的精度对凭证、账单类场景是降维打击
3. 3. Tesseract 数据 TBD——但工程经验上，它在 Linux 上是唯一答案
4. 4. 数字会变——M4 是顶配，自家机器上请重新跑 cargo run --example basic

五、4 个官方示例，照着改最快

仓库 examples/ 目录提供了 4 个 ready-to-run 程序：

# 1. 基础：单张识别
cargo run --example basic

# 2. 批量：多张并行
cargo run --example batch_processing

# 3. 选项：自定义参数
cargo run --example custom_options

# 4. 平台：强制指定 provider
cargo run --example platform_specific

推荐学习路径：

1. 1. 先跑 basic，确认环境 OK
2. 2. 再读 custom_options，理解 OcrOptions 的链式调用
3. 3. 业务真要批量处理，去抄 batch_processing 的并发结构
4. 4. 跨平台分发产品，看 platform_specific 处理 cfg 分支

六、什么场景值得引入它？什么不值得？

最后给一份选型 checklist，避免你装回去又删掉：

值得引入：

• • ✅ 你在写 Rust 桌面/CLI 工具，需要 OCR 能力但不想绑死某个 OS
• • ✅ 你做 Screenshot Pipeline、屏幕录制内容索引（screenpipe 自家场景）
• • ✅ 你在意离线能力，不能把图片传到云端
• • ✅ 你想要一个统一抽象，未来把 Tesseract 换成 PaddleOCR 时只改一行

不值得引入：

• • ❌ 你写的是 Web 服务，目标平台只有 Linux —— 直接用 Tesseract 或 PaddleOCR 绑定即可
• • ❌ 你只搞中文古籍/表格 OCR —— 专业模型（PaddleOCR / TrOCR）效果更好
• • ❌ 你需要版面分析、表格还原、公式识别 —— uniOCR 当前定位是"纯文字提取"，复杂结构不在 scope 内

七、总结清单

把今天这篇浓缩成 6 行，可以截图保存：

1. 1. 加依赖：uni-ocr (git) + tokio + anyhow，一次到位
2. 2. 写最少代码：OcrEngine::new(Auto) + recognize_file() 三行跑通
3. 3. 生产环境别 Auto：按平台和精度需求显式选 Provider
4. 4. 用 OcrOptions：语言、置信度、超时三件套，缺一不可
5. 5. 批量走 batch：别 for + await，recognize_batch 自带并行
6. 6. 环境清单：macOS/Windows 零配置，Linux/Tesseract 装包别忘语言包

从今天开始，先做第一步：在你 next 的 Rust 小项目里把这一行加进去：

uni-ocr = { git = "https://github.com/mediar-ai/uniocr.git" }

跑通 basic 例子，再考虑要不要替换掉你已有的 OCR 调用。

项目地址：https://github.com/screenpipe/uniOCR 截至 2026 年 6 月：Star 224 / Fork 20 / 主语言 Rust / License MIT

如果你有更好的跨平台 OCR 方案，或者用 uniOCR 做出了有意思的项目，欢迎在评论区告诉我。

今天的分享就到这里。后续我会持续为大家带来实用的技术干货和前沿的技术资讯。如果你对工具链探索感兴趣，我会持续分享前端工程化、构建优化等实战经验，欢迎关注，不要错过任何精彩内容！