# deepseek-ocr.rs

**Repository Path**: mirrors_trending/deepseek-ocr.rs

## Basic Information

- **Project Name**: deepseek-ocr.rs
- **Description**: Rust implementation of DeepSeek-OCR with OpenAI-compatible server & CLI No Python environment needed - just download and run.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-29
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# deepseek-ocr.rs 🚀

Rust 实现的 DeepSeek-OCR 推理栈，提供快速 CLI 与 OpenAI 兼容的 HTTP Server，统一打包多种 OCR 后端、视觉输入预处理、提示词工具与服务端能力，方便在本地 CPU、Apple Metal 或 NVIDIA CUDA GPU(alpha) 上构建文档理解工作流。

> 英文文档请参见 [README.md](README.md)。  

> 想直接下载可执行文件？访问 [Github Actions](https://github.com/TimmyOVO/deepseek-ocr.rs/actions/workflows/build-binaries.yml)，下载最新一次成功运行生成的 macOS（含 Metal）或 Windows 压缩包。

## 模型选择指南 🔬

| 模型 | 内存占用* | 最佳硬件 | 适用场景 |
| --- | --- | --- | --- |
| **DeepSeek‑OCR** | **≈6.3GB** FP16 权重，含激活/缓存约 **13GB**（512 token） | Apple Silicon + Metal、24GB VRAM NVIDIA、32GB+ RAM 桌面 | 追求最高准确率、多视角文档、对延迟不敏感。SAM+CLIP 视觉 + DeepSeek‑V2 MoE（3B 参数，单 token 激活 ≈570M）。 |
| **PaddleOCR‑VL** | **≈4.7GB** FP16 权重，含激活/缓存约 **9GB** | 16GB 笔电、CPU-only 节点、中端 GPU | 更快冷启动，dense Ernie decoder（0.9B）+ SigLIP 视觉，适合批量作业与轻量部署。 |
| **DotsOCR** | **≈9GB** FP16 权重，但高分辨率图像通常需要 **30–50GB** RAM/VRAM（视觉 token 数极大） | Apple Silicon + Metal BF16、≥24GB CUDA、或 64GB RAM CPU 工作站 | DotsVision + Qwen2 统一 VLM，在版面、阅读顺序、grounding、多语种公式等任务表现最好，代价是显著的内存和延迟。 |

\*默认 FP16 safetensors 容量；实际资源与序列长度、是否启用 KV Cache 相关。

选择建议：

- **有 16–24GB 以上 VRAM / RAM、追求极致质量？** 选 **DeepSeek‑OCR**，SAM+CLIP 全局+局部视野、DeepSeek‑V2 MoE 解码能在复杂版式中保持更高还原度，但代价是更大的显存和更高延迟。
- **硬件预算有限或需要低延迟 / 高吞吐？** 选 **PaddleOCR‑VL**，SigLIP + dense Ernie（18 层、hidden 1024）在 10GB 以内即可运行，CPU 模式也更易部署。
- **手头有充裕显存/内存，重视阅读顺序、grounding、复杂多语种 PDF？** 选 **DotsOCR**，在 Metal/CUDA 上配合 `--dtype bf16`（或 CUDA 下 `--dtype f16`）能获得更稳定的推理速度，但需接受 40 tok/s 左右预填充与数+ GB RSS 的成本。

## 为什么选择 Rust？💡

官方 DeepSeek-OCR 依赖 Python + Transformers，部署体积大、依赖多，嵌入原生系统成本高。Rust 重写后的优势：

- 无需 Python 运行时或 conda，产物更小、更易嵌入。
- 内存安全、线程友好，可直接融入现有 Rust 服务。
- CLI 与 Server 共用一套核心逻辑，避免重复维护。
- 依旧兼容 OpenAI 客户端，同时聚焦单轮 OCR 场景确保输出稳定。

## 技术栈 ⚙️

- **Candle**：Rust 深度学习框架，支持 Metal/CUDA（alpha） 与 FlashAttention。
- **Rocket**：异步 HTTP 框架，提供 `/v1/responses`、`/v1/chat/completions` 等 OpenAI 兼容路由。
- **tokenizers**：上游模型提供的 Tokenizer，通过 `crates/assets` 在 Hugging Face / ModelScope 镜像间缓存与校验。
- **纯 Rust 视觉/Prompt 管线**：CLI 与 Server 复用，减少重复逻辑。

## 相比 Python 实现的优势 🥷

- Apple Silicon 冷启动更快、内存占用更低，且提供原生二进制分发。
- 资产下载/校验由 Rust crate 统一托管，可在 Hugging Face 与 ModelScope 之间自动切换。
- 自动折叠多轮会话，仅保留最近一次 user 提示，确保 OCR 场景稳定。
- 与 Open WebUI 等 OpenAI 客户端“即插即用”，无需额外适配层。

## 项目亮点 ✨

- **一套代码，两种入口**：批处理友好的 CLI 与兼容 `/v1/responses`、`/v1/chat/completions` 的 Rocket Server。
- **开箱即用**：首次运行自动从 Hugging Face 或 ModelScope（取决于实时延迟）拉取配置、Tokenizer 与权重。
- **Apple Silicon 友好**：Metal + FP16 加速让笔记本也能实时 OCR。
- **NVIDIA GPU（α 测试）**：构建时附加 `--features cuda` 并以 `--device cuda --dtype f16` 运行，可在 Linux/Windows 上尝鲜 CUDA 加速。
- **Intel MKL（预览）**：安装 Intel oneMKL 后，构建时附加 `--features mkl` 以提升 x86 CPU 上的矩阵运算速度。
- **OpenAI 客户端即插即用**：Server 端自动折叠多轮对话，只保留最新 user 指令，避免 OCR 模型被多轮上下文干扰。

## 模型矩阵 📦

本仓库当前暴露 3 个基础模型 ID，以及 DeepSeek‑OCR / PaddleOCR‑VL 的 DSQ 量化变体：

| Model ID | Base Model | Precision | 建议使用场景 |
| --- | --- | --- | --- |
| `deepseek-ocr` | `deepseek-ocr` | FP16（通过 `--dtype` 选择实际精度） | 完整 DeepSeek‑OCR 管线（SAM+CLIP + MoE 解码），在 Metal/CUDA/大内存 CPU 上追求最高质量时使用。 |
| `deepseek-ocr-q4k` | `deepseek-ocr` | `Q4_K` | 显存非常紧张、本地离线批处理等场景，在牺牲一定精度的前提下压缩模型体积。 |
| `deepseek-ocr-q6k` | `deepseek-ocr` | `Q6_K` | 常规工程环境下的折中选择，在质量与体积之间取得平衡。 |
| `deepseek-ocr-q8k` | `deepseek-ocr` | `Q8_0` | 希望尽量接近全精度质量，同时仍获得一定压缩收益。 |
| `paddleocr-vl` | `paddleocr-vl` | FP16（通过 `--dtype` 选择实际精度） | 默认推荐的轻量后端：0.9B Ernie + SigLIP，在 CPU/16GB 笔电等硬件上也能流畅运行。 |
| `paddleocr-vl-q4k` | `paddleocr-vl` | `Q4_K` | 面向大规模、强压缩的文档/表格场景，对精度要求相对较低。 |
| `paddleocr-vl-q6k` | `paddleocr-vl` | `Q6_K` | 通用推荐，适合绝大多数工程部署。 |
| `paddleocr-vl-q8k` | `paddleocr-vl` | `Q8_0` | 更偏向准确率、仍比 FP16 更节省显存。 |
| `dots-ocr` | `dots-ocr` | FP16 / BF16（运行时 `--dtype` 决定） | DotsVision + Qwen2 统一 VLM，用于复杂版面、多语种、阅读顺序与 grounding 场景；高分辨率时内存占用可达 30–50GB。 |
| `dots-ocr-q4k` | `dots-ocr` | `Q4_K` | 在已接受 DotsOCR 内存 profile 的前提下，通过 DSQ snapshot 对权重做强压缩；适合极端显存/内存预算。 |
| `dots-ocr-q6k` | `dots-ocr` | `Q6_K` | 推荐的折中量化档位：在大幅节省权重占用的同时尽量贴近 FP16/BF16 质量。 |
| `dots-ocr-q8k` | `dots-ocr` | `Q8_0` | 偏向精度的量化版本，在全精度基础上做温和压缩。 |

量化模型的元数据来源于 `crates/assets/src/lib.rs:40-120` 中的 `QUANTIZED_MODEL_ASSETS`，并由 `crates/dsq-models/src/adapters` 下的适配器导出。DotsOCR 现在提供 `dots-ocr-q4k` / `dots-ocr-q6k` / `dots-ocr-q8k` 三个 DSQ 变体，这些 `.dsq` 文件都是基于原始 safetensors 的“补丁”，推理时仍然需要同时存在 baseline 权重与 snapshot。

## 快速上手 🏁

### 环境要求

- Rust 1.78+（支持 2024 Edition）
- Git
- 可选：macOS 13+ 的 Apple Silicon（用于 Metal）
- 可选：Linux/Windows 的 NVIDIA GPU（需 CUDA 12.2+ 工具链与驱动，当前为alpha阶段）
- 可选：x86 平台安装 Intel oneMKL（预览），用于提升 CPU 推理性能
- 推荐：配置 `HF_TOKEN` 访问 Hugging Face `deepseek-ai/DeepSeek-OCR`（若该源不可用会自动切换 ModelScope）

### 克隆仓库

```bash
git clone https://github.com/TimmyOVO/deepseek-ocr.rs.git
cd deepseek-ocr.rs
cargo fetch
```

### 模型资源

第一次运行 CLI 或 Server 会把配置、tokenizer 及 ~6.3GB 的 `model-00001-of-000001.safetensors` 下载到 `DeepSeek-OCR/`。也可以手动触发：

```bash
cargo run -p deepseek-ocr-cli --release -- --help # dev profile 极慢，建议始终加 --release
```

若自定义缓存目录，请设置 `HF_HOME` 或导出 `HF_TOKEN`。完整模型约 6.3GB，推理时需预留 ~13GB 内存（模型 + 激活）。

### 预构建产物

不想自己编译？点这里 [Github Actions](https://github.com/TimmyOVO/deepseek-ocr.rs/actions/workflows/build-binaries.yml) 里产出 macOS（含 Metal）和 Windows 压缩包。登录 GitHub，打开最新一次绿色运行，下载 `deepseek-ocr-macos` 或 `deepseek-ocr-windows` 即可。

## 配置与优先级 🗂️

CLI 与 Server 共享同一份配置。首次启动会在系统配置目录生成带默认值的 `config.toml`，后续运行都会沿用该文件确保两个入口保持一致。

| 平台 | 默认配置文件 | 模型缓存目录 |
| --- | --- | --- |
| Linux | `~/.config/deepseek-ocr/config.toml` | `~/.cache/deepseek-ocr/models/<id>/…` |
| macOS | `~/Library/Application Support/deepseek-ocr/config.toml` | `~/Library/Caches/deepseek-ocr/models/<id>/…` |
| Windows | `%APPDATA%\deepseek-ocr\config.toml` | `%LOCALAPPDATA%\deepseek-ocr\models\<id>\…` |

- 可通过 `--config /path/to/config.toml`（CLI/Server 通用）自定义路径；当文件不存在时会自动创建并写入默认内容。
- 默认的 `config.toml` 已包含 `deepseek-ocr`（默认）、`paddleocr-vl` 与 `dots-ocr` 三个模型条目，可通过 `--model paddleocr-vl` / `--model dots-ocr`（或修改 `[models].active`）在后端之间即时切换；
- 需要自定义资源位置时，可在对应 `models.entries.<id>` 下设置 `config`/`tokenizer`/`weights`，或直接在运行时使用 `--model-config`、`--tokenizer`、`--weights` 覆盖。
- `config.toml` 中的 `[models.entries."<id>"]` 节点允许为不同模型指定独立的 `config`、`tokenizer`、`weights` 路径；若留空则使用上表所示缓存目录并按需下载。
- 参数覆盖顺序为：命令行参数 → `config.toml` → 内置默认值。HTTP API 请求体中的字段（例如 `max_tokens`）会在该次调用中继续覆盖前述设置。

默认配置文件内容如下，可根据需要修改后长期生效：

```toml
[models]
active = "deepseek-ocr"

[models.entries.deepseek-ocr]

[inference]
device = "cpu"
template = "plain"
base_size = 1024
image_size = 640
crop_mode = true
max_new_tokens = 512
use_cache = true

[server]
host = "0.0.0.0"
port = 8000
```

- `[models]` 用于指定当前激活的模型以及额外的模型条目（每个条目都可以指向各自的配置、Tokenizer 与权重文件）。
- `[inference]` 提供 CLI 与 Server 共用的推理默认值（设备、模板、视觉分辨率、生成长度与缓存策略）。
- `[server]` 决定网络监听地址以及 `/v1/models` 返回的模型名。

更多覆盖项详见 `crates/cli/README_CN.md` 与 `crates/server/README_CN.md`。

## 基准对比 📊

下表展示在同一张图像与提示词下，启用了 Accelerate 的 Rust CLI（单次请求）与 Python 参考实现的性能表现：

| 阶段（Stage）                                     | ref total (ms) | ref avg (ms) | python total | python/ref |
|--------------------------------------------------|----------------|--------------|--------------|------------|
| Decode – Overall (`decode.generate`)             | 30077.840      | 30077.840    | 56554.873    | 1.88x      |
| Decode – Token Loop (`decode.iterative`)         | 26930.216      | 26930.216    | 39227.974    | 1.46x      |
| Decode – Prompt Prefill (`decode.prefill`)       | 3147.337       | 3147.337     | 5759.684     | 1.83x      |
| Prompt – Build Tokens (`prompt.build_tokens`)    | 0.466          | 0.466        | 45.434       | 97.42x     |
| Prompt – Render Template (`prompt.render`)       | 0.005          | 0.005        | 0.019        | 3.52x      |
| Vision – Embed Images (`vision.compute_embeddings`)| 6391.435     | 6391.435     | 3953.459     | 0.62x      |
| Vision – Prepare Inputs (`vision.prepare_inputs`)| 62.524         | 62.524       | 45.438       | 0.73x      |

## 命令行工具 🖥️

直接运行：

```bash
cargo run -p deepseek-ocr-cli --release -- \
  --prompt "<image>\n<|grounding|>Convert this receipt to markdown." \
  --image baselines/sample/images/test.png \
  --device cpu --max-new-tokens 512
```

> macOS 用户可以在 `cargo run`/`cargo build` 命令后附加 `--features metal` 以启用 Accelerate + Metal 后端。
>
> Linux/Windows 用户：附加 `--features cuda` 并在运行参数中加入 `--device cuda --dtype f16`，即可使用 NVIDIA GPU 加速。
>
> Intel MKL 预览：先安装 Intel oneMKL，构建时附加 `--features mkl`，可在 x86 CPU 上取得更高的矩阵运算性能。

安装成全局二进制：

```bash
cargo install --path crates/cli
deepseek-ocr-cli --help
```

常用参数：

- `--prompt` / `--prompt-file`：包含 `<image>` 占位符的提示词
- `--image`：与 `<image>` 数量一致的图片路径
- `--device` / `--dtype`：macOS 建议 `--device metal --dtype f16`，NVIDIA 用户使用 `--device cuda --dtype f16`
- `--max-new-tokens`：生成长度上限
- Sampling 相关：`--do-sample`、`--temperature`、`--top-p`、`--top-k`、`--repetition-penalty`、`--no-repeat-ngram-size`、`--seed`
  - 默认保持确定性输出（`do_sample=false`、`temperature=0.0`、`no_repeat_ngram_size=20`）
  - 若需要随机 sampling，请显式指定 `--do-sample true --temperature 0.8`，并按需调整其他参数

## HTTP Server ☁️

启动 OpenAI 兼容服务：

```bash
cargo run -p deepseek-ocr-server --release -- \
  --host 0.0.0.0 --port 8000 \
  --device cpu --max-new-tokens 512
```

> 如果要在 macOS 上启用 Metal，请为以上命令加上 `--features metal`，同时运行时配合 `--device metal`。
>
> Intel MKL 预览：构建前安装 Intel oneMKL，再附加 `--features mkl`，即可在 x86 CPU 上获得更快的推理速度。
>
> 若在 Linux/Windows 上使用 NVIDIA GPU，请加上 `--features cuda` 并以 `--device cuda --dtype f16` 启动服务。

注意事项：

- 图片需使用 `data:` URL（base64）或可访问的 `http(s)` 链接，禁止本地路径。
- Server 已自动将多轮对话折叠为最近一次 user 轮次，保持单轮 OCR 体验。
- 与 [Open WebUI](https://github.com/open-webui/open-webui) 等 OpenAI 兼容客户端开箱即用——只需在客户端设置 `base_url` 为 `http://localhost:8000/v1` 并选择 `deepseek-ocr` 模型。
- 如果需要大图上传，可在 Rocket 配置里调高 JSON/body limit。

![Open WebUI 连接 deepseek-ocr.rs](./baselines/sample_1.png)

## GPU 加速 ⚡

- **Metal（macOS 13+ & Apple Silicon）**：构建命令附加 `--features metal`，运行时使用 `--device metal --dtype f16`。
- **CUDA（alpha，Linux/Windows & NVIDIA GPU）**：提前安装 CUDA 12.2+，构建时加 `--features cuda`，执行时传入 `--device cuda --dtype f16`。
- **Intel MKL（预览）**：安装 Intel oneMKL，构建时附加 `--features mkl`，可提升 x86 CPU 推理性能。
- 无论使用哪种 GPU，推荐 `cargo build --release -p deepseek-ocr-cli --features metal|cuda` 以获取更高吞吐。
- 结合 `--max-new-tokens`、`--crop-mode` 等参数可在延迟与质量之间做权衡。

## 目录结构 🗂️

- `crates/core`：推理管线、模型装载、会话模板。
- `crates/cli`：命令行入口 `deepseek-ocr-cli`。
- `crates/server`：提供 OpenAI 风格 API 的 Rocket 服务。
- `crates/assets`：模型/Tokenizer 下载与缓存工具。
- `baselines/`：基准输入输出样例，便于回归测试。

更多 CLI 说明请参见 [`crates/cli/README_CN.md`](crates/cli/README_CN.md)；服务端 API 详见 [`crates/server/README_CN.md`](crates/server/README_CN.md)。

## 常见问题 🛠️

- **资产下载源**：会自动在 Hugging Face 与 ModelScope 之间按延迟择优。命令行会提示当前使用的源与目标路径。
- **下载失败**：确认 `HF_TOKEN` 已配置，或重试以利用 Hugging Face/ModelScope 缓存。
- **首轮耗时长**：第一次推理需要加载模型并热启动 GPU（Metal/CUDA α)，后续会更快。
- **图片过大被拒**：放大 Rocket 限额或对图像进行下采样。

## 致谢 🙏

- 模型由 [DeepSeek-AI](https://huggingface.co/deepseek-ai/DeepSeek-OCR) 提供。
- 项目依赖 Candle、Rocket 等优秀 Rust 开源生态，感谢所有维护者。

## 许可证 📄

本仓库遵循上游 DeepSeek-OCR 模型的使用条款，详见 `DeepSeek-OCR/LICENSE`，下游使用请遵守相同限制。