1. 从一张扫描件说起DeepSeek-OCR 到底解决了什么老问题如果你手头有几千页 PDF 合同、发票、学术论文或者化学实验报告想把它们转成 Markdown 或结构化表格传统 OCR 的体验大概率让你崩溃过。PaddleOCR、Tesseract 这类工具在纯文字页面上还行一旦遇到双栏排版、跨页表格、数学公式、化学结构式识别结果就开始“散架”——文字顺序错乱、表格变成一堆空格、公式直接丢失。更麻烦的是传统 OCR 是“检测识别”两段式管线你需要自己写后处理逻辑去拼版面、修顺序工程量不小。DeepSeek-OCR 走的是另一条路。它把整页文档当成一张图用视觉编码器压缩成少量视觉 token再让文本解码器“看图说话”重建内容。核心思路叫“上下文光学压缩”Contexts Optical Compression把大量文本信息映射到图像 token 上模型通过视觉感知来还原文字。官方实验数据显示当文本 token 与视觉 token 的压缩比小于 10 倍时重建精度约 97%即使压到 20 倍仍有约 60% 的精度。在 OmniDocBench 基准上它用 100 个视觉 token 就超过了 GOT-OCR2.0 用 256 token 的效果用不到 800 token 就能大幅领先 MinerU2.0 平均近 7000 token 的水平。这意味着什么处理长文档时你的显存占用和推理时间会显著下降。A100-40G 实测吞吐约 2500 tok/s一页文档几秒内出结果。模型参数约 3BMIT 许可证权重完全开源支持 vLLM 和 HuggingFace Transformers 两种推理路径。它适合谁需要批量处理扫描件、PDF、混合排版文档的开发者尤其是那些被传统 OCR 后处理折磨过、想试试端到端方案的人。但它不是“轻量级”工具3B 参数在高端 GPU 上跑得舒服边缘设备需要额外压缩或蒸馏。我试过用它在本地跑一批学术论文 PDF最直观的感受是表格和公式的还原度比预期好但前提是你得选对分辨率和模式。下面从环境配置开始一步步把最小可运行路径走通。2. 前置准备TaoToken 统一 Key 与本地环境基线在动手配 DeepSeek-OCR 之前先把两件事理清楚一是本地推理的硬件和依赖基线二是如果你不想在本地扛 3B 模型的显存开销怎么通过 TaoToken 的统一 Key 走 API 调用做快速验证。本地推理的基线要求CUDA 11.8、PyTorch 2.6.0、vLLM 0.8.5cu118 版本、flash-attn 2.7.3。显存方面A100-40G 是官方实测的舒适区消费级卡如 4090 24G 也能跑但需要把分辨率调低、关闭 Gundam 模式。Python 版本建议 3.12.9conda 环境隔离。TaoToken 的角色是“统一入口”。你不需要在本地装模型权重、配 CUDA 环境直接用它的 API 就能调 DeepSeek-OCR 做单图或小批量验证。它的 Base URL 是https://taotoken.net/apiAPI Key 在控制台生成。对于想先判断“这个模型适不适合我的文档场景”的人来说走 API 验证比本地部署快得多——本地配环境可能花半小时API 调用五分钟就能出第一张图的结果。具体操作路径先到 TaoToken 控制台创建 API Key然后拿这个 Key 去调模型对话接口做单图测试。如果你后续确定要长期用、批量跑再考虑本地 vLLM 部署。两条路不冲突API 用来快速验证本地用来控成本和数据隐私。需要提前准备的清单一张测试用的文档图片建议选带表格或公式的能看出模型能力边界、一个能跑 Python 的环境、TaoToken 的 API Key。如果你走本地路线还需要确认 GPU 驱动版本和 CUDA 版本匹配。3. 可复制配置vLLM 本地推理与 Transformers 最小脚本这一节给可直接复制的配置片段。先走 vLLM 路线再给 Transformers 的最小推理脚本最后附上 TaoToken API 调用的 JSON 配置。3.1 vLLM 本地部署配置环境搭建命令如下按顺序执行git clone https://github.com/deepseek-ai/DeepSeek-OCR.git cd DeepSeek-OCR conda create -n dpsk-ocr python3.12.9 -y conda activate dpsk-ocr pip install torch2.6.0 torchvision0.21.0 torchaudio2.6.0 --index-url https://download.pytorch.org/whl/cu118 pip install vllm-0.8.5cu118-cp38-abi3-manylinux1_x86_64.whl pip install -r requirements.txt pip install flash-attn2.7.3 --no-build-isolation注意 flash-attn 的安装必须加--no-build-isolation否则编译时会找不到 torch。如果这一步报错先pip show torch确认版本是 2.6.0再nvcc -V确认 CUDA 是 11.8。单图和 PDF 批处理的运行脚本在DeepSeek-OCR-master/DeepSeek-OCR-vllm目录下cd DeepSeek-OCR-master/DeepSeek-OCR-vllm python run_dpsk_ocr_image.py python run_dpsk_ocr_pdf.py跑之前改config.py里的输入输出路径。A100-40G 上实测约 2500 tok/s一页普通文档 2-3 秒。3.2 Transformers 最小推理脚本如果你不想用 vLLMTransformers 路线更轻量适合单图测试from transformers import AutoModel, AutoTokenizer import torch m deepseek-ai/DeepSeek-OCR tok AutoTokenizer.from_pretrained(m, trust_remote_codeTrue) mdl AutoModel.from_pretrained( m, trust_remote_codeTrue, use_safetensorsTrue, _attn_implementationflash_attention_2 ).eval().cuda().to(torch.bfloat16) res mdl.infer( tok, promptimage\n|grounding|Convert the document to markdown., image_filedemo.jpg, output_path./out, base_size1024, image_size640, crop_modeTrue, save_resultsTrue, test_compressTrue ) print(res)关键参数说明base_size1024是基础分辨率image_size640是实际输入尺寸crop_modeTrue开启裁剪模式处理大图test_compressTrue会输出压缩比信息。_attn_implementationflash_attention_2启用 FlashAttention 加速前提是 flash-attn 装好了。3.3 TaoToken API 调用配置如果你走 API 路线用下面的 JSON 配置调模型对话接口{ base_url: https://taotoken.net/api, api_key: 你的_TaoToken_API_Key, model: deepseek-ai/DeepSeek-OCR, messages: [ { role: user, content: image\n|grounding|Convert the document to markdown. } ], max_tokens: 4096, temperature: 0.0 }把api_key替换成你在 TaoToken 控制台生成的实际 Key。这个配置可以直接用 curl 或 Python requests 发请求。注意temperature0.0保证输出稳定OCR 任务不需要创造性。4. 验证请求从单图到批量 PDF 的成功结果核验配置写好了接下来验证是否真的跑通。分三步单图测试、批量 PDF 测试、结果核验。单图测试用 Transformers 脚本或 API 调用都行。跑通后你会看到终端输出一段 Markdown 文本同时./out目录下生成结果文件。检查三件事文字顺序是否正确、表格是否保留结构、公式是否还原。如果输出里出现大量乱码或重复大概率是分辨率设太低或 prompt 不对。批量 PDF 测试用 vLLM 的run_dpsk_ocr_pdf.py。跑之前记录基线吞吐tok/s 和页/秒。A100-40G 上 2500 tok/s 对应大约每页 2-3 秒。如果你的吞吐明显低于这个数检查是不是开了 Gundam 模式或分辨率设太高。结果核验建议随机抽样 100 页计算字符级和词级准确率同时人工检查表格和公式的结构保真度。我实测下来纯文字页面准确率很高双栏排版的顺序基本正确复杂表格偶尔会丢列公式还原依赖 prompt 的引导。模式选择上先用 Small640 分辨率100 token跑一遍页复杂或公式多再切 Base1024256 token极复杂用 Large/Gundam。核验时统计生成长度、错误率和耗时找到精度和速度的平衡点。Prompt 工程方面文档转 Markdown 用|grounding|Convert the document to markdown.只做 OCR 用Free OCR.表格抽取和图解析在 README 里有示例 prompt。不同 prompt 对输出格式影响很大建议先固定一个 prompt 跑基线再逐步调优。5. 常见报错排查flash-attn 编译失败与 vLLM 版本冲突这一节对照真实报错给排查路径。flash-attn 编译或导入失败。症状是pip install flash-attn时报编译错误或 import 时提示 CUDA/torch 版本不匹配。根因通常是 torch 版本和 CUDA 版本对不上。快速定位pip show torch看版本nvcc -V看 CUDA 版本。处置固定 torch2.6.0 cu118重装 flash-attn安装时加--no-build-isolation。vLLM 起不来或导入冲突。症状是import vllm报错或启动时提示 transformers 版本不兼容。根因是 vLLM 和 transformers 版本耦合。快速定位pip freeze | grep vllm和pip freeze | grep transformers。处置调整 vLLM 或 transformers 版本至兼容状态vLLM 0.8.5 对应 transformers 4.46 左右。显存爆或吞吐异常。症状是 OOM 或 tok/s 远低于 2500。根因是分辨率或模式选太大。快速定位监控显存使用情况nvidia-smi看占用。处置从 Small640起测降分辨率、关 Gundam、增批量与流水线优化。401 报错。如果你走 TaoToken API 路线遇到 401 说明 API Key 无效或没传对。检查请求头里的 Authorization 字段确认 Key 是从控制台复制的完整字符串。本地推理不会出这个错只有 API 调用才会。local proxy failed。这个报错通常出现在网络请求环节检查你的请求地址是不是https://taotoken.net/api不要多加路径或参数。reading choices 报错。这是响应解析问题通常是返回体格式和你的解析代码不匹配。打印完整响应体看结构确认choices[0].message.content字段存在。OAuth 相关报错。如果你用 Claude Code 或类似工具接入OAuth 流程走不通时检查回调地址和 Key 权限。CC Switch、Cline MCP、Codex auth.json 这三件套的配置要写全Base URL、Key、Model ID 一个都不能少。6. 语义一致 CTA按场景选接入路径跑通最小测试后根据你的实际场景选下一步。如果你还在验证阶段想快速判断 DeepSeek-OCR 适不适合你的文档类型直接走 TaoToken 的模型对话接口用统一 Key 调单图测试五分钟出结果。地址https://taotoken.net/api Key 在控制台生成。如果你确定要长期用、批量处理文档建议本地 vLLM 部署控成本和数据隐私。部署前先到接入文档确认最新的依赖版本和参数配置避免版本冲突。如果你是要做长期编码或 Agent 集成比如把 OCR 能力嵌到自动化流程里走 Coding Plan 更合适统一管理 Key 和调用配额。排障和接入细节看 API Keys 和接入文档模型能力验证走模型对话长期编码和 Agent 场景走 Coding Plan。三条路按需选不用全走一遍。
1. 从一张扫描件说起DeepSeek-OCR 到底解决了什么老问题如果你手头有几千页 PDF 合同、发票、学术论文或者化学实验报告想把它们转成 Markdown 或结构化表格传统 OCR 的体验大概率让你崩溃过。PaddleOCR、Tesseract 这类工具在纯文字页面上还行一旦遇到双栏排版、跨页表格、数学公式、化学结构式识别结果就开始“散架”——文字顺序错乱、表格变成一堆空格、公式直接丢失。更麻烦的是传统 OCR 是“检测识别”两段式管线你需要自己写后处理逻辑去拼版面、修顺序工程量不小。DeepSeek-OCR 走的是另一条路。它把整页文档当成一张图用视觉编码器压缩成少量视觉 token再让文本解码器“看图说话”重建内容。核心思路叫“上下文光学压缩”Contexts Optical Compression把大量文本信息映射到图像 token 上模型通过视觉感知来还原文字。官方实验数据显示当文本 token 与视觉 token 的压缩比小于 10 倍时重建精度约 97%即使压到 20 倍仍有约 60% 的精度。在 OmniDocBench 基准上它用 100 个视觉 token 就超过了 GOT-OCR2.0 用 256 token 的效果用不到 800 token 就能大幅领先 MinerU2.0 平均近 7000 token 的水平。这意味着什么处理长文档时你的显存占用和推理时间会显著下降。A100-40G 实测吞吐约 2500 tok/s一页文档几秒内出结果。模型参数约 3BMIT 许可证权重完全开源支持 vLLM 和 HuggingFace Transformers 两种推理路径。它适合谁需要批量处理扫描件、PDF、混合排版文档的开发者尤其是那些被传统 OCR 后处理折磨过、想试试端到端方案的人。但它不是“轻量级”工具3B 参数在高端 GPU 上跑得舒服边缘设备需要额外压缩或蒸馏。我试过用它在本地跑一批学术论文 PDF最直观的感受是表格和公式的还原度比预期好但前提是你得选对分辨率和模式。下面从环境配置开始一步步把最小可运行路径走通。2. 前置准备TaoToken 统一 Key 与本地环境基线在动手配 DeepSeek-OCR 之前先把两件事理清楚一是本地推理的硬件和依赖基线二是如果你不想在本地扛 3B 模型的显存开销怎么通过 TaoToken 的统一 Key 走 API 调用做快速验证。本地推理的基线要求CUDA 11.8、PyTorch 2.6.0、vLLM 0.8.5cu118 版本、flash-attn 2.7.3。显存方面A100-40G 是官方实测的舒适区消费级卡如 4090 24G 也能跑但需要把分辨率调低、关闭 Gundam 模式。Python 版本建议 3.12.9conda 环境隔离。TaoToken 的角色是“统一入口”。你不需要在本地装模型权重、配 CUDA 环境直接用它的 API 就能调 DeepSeek-OCR 做单图或小批量验证。它的 Base URL 是https://taotoken.net/apiAPI Key 在控制台生成。对于想先判断“这个模型适不适合我的文档场景”的人来说走 API 验证比本地部署快得多——本地配环境可能花半小时API 调用五分钟就能出第一张图的结果。具体操作路径先到 TaoToken 控制台创建 API Key然后拿这个 Key 去调模型对话接口做单图测试。如果你后续确定要长期用、批量跑再考虑本地 vLLM 部署。两条路不冲突API 用来快速验证本地用来控成本和数据隐私。需要提前准备的清单一张测试用的文档图片建议选带表格或公式的能看出模型能力边界、一个能跑 Python 的环境、TaoToken 的 API Key。如果你走本地路线还需要确认 GPU 驱动版本和 CUDA 版本匹配。3. 可复制配置vLLM 本地推理与 Transformers 最小脚本这一节给可直接复制的配置片段。先走 vLLM 路线再给 Transformers 的最小推理脚本最后附上 TaoToken API 调用的 JSON 配置。3.1 vLLM 本地部署配置环境搭建命令如下按顺序执行git clone https://github.com/deepseek-ai/DeepSeek-OCR.git cd DeepSeek-OCR conda create -n dpsk-ocr python3.12.9 -y conda activate dpsk-ocr pip install torch2.6.0 torchvision0.21.0 torchaudio2.6.0 --index-url https://download.pytorch.org/whl/cu118 pip install vllm-0.8.5cu118-cp38-abi3-manylinux1_x86_64.whl pip install -r requirements.txt pip install flash-attn2.7.3 --no-build-isolation注意 flash-attn 的安装必须加--no-build-isolation否则编译时会找不到 torch。如果这一步报错先pip show torch确认版本是 2.6.0再nvcc -V确认 CUDA 是 11.8。单图和 PDF 批处理的运行脚本在DeepSeek-OCR-master/DeepSeek-OCR-vllm目录下cd DeepSeek-OCR-master/DeepSeek-OCR-vllm python run_dpsk_ocr_image.py python run_dpsk_ocr_pdf.py跑之前改config.py里的输入输出路径。A100-40G 上实测约 2500 tok/s一页普通文档 2-3 秒。3.2 Transformers 最小推理脚本如果你不想用 vLLMTransformers 路线更轻量适合单图测试from transformers import AutoModel, AutoTokenizer import torch m deepseek-ai/DeepSeek-OCR tok AutoTokenizer.from_pretrained(m, trust_remote_codeTrue) mdl AutoModel.from_pretrained( m, trust_remote_codeTrue, use_safetensorsTrue, _attn_implementationflash_attention_2 ).eval().cuda().to(torch.bfloat16) res mdl.infer( tok, promptimage\n|grounding|Convert the document to markdown., image_filedemo.jpg, output_path./out, base_size1024, image_size640, crop_modeTrue, save_resultsTrue, test_compressTrue ) print(res)关键参数说明base_size1024是基础分辨率image_size640是实际输入尺寸crop_modeTrue开启裁剪模式处理大图test_compressTrue会输出压缩比信息。_attn_implementationflash_attention_2启用 FlashAttention 加速前提是 flash-attn 装好了。3.3 TaoToken API 调用配置如果你走 API 路线用下面的 JSON 配置调模型对话接口{ base_url: https://taotoken.net/api, api_key: 你的_TaoToken_API_Key, model: deepseek-ai/DeepSeek-OCR, messages: [ { role: user, content: image\n|grounding|Convert the document to markdown. } ], max_tokens: 4096, temperature: 0.0 }把api_key替换成你在 TaoToken 控制台生成的实际 Key。这个配置可以直接用 curl 或 Python requests 发请求。注意temperature0.0保证输出稳定OCR 任务不需要创造性。4. 验证请求从单图到批量 PDF 的成功结果核验配置写好了接下来验证是否真的跑通。分三步单图测试、批量 PDF 测试、结果核验。单图测试用 Transformers 脚本或 API 调用都行。跑通后你会看到终端输出一段 Markdown 文本同时./out目录下生成结果文件。检查三件事文字顺序是否正确、表格是否保留结构、公式是否还原。如果输出里出现大量乱码或重复大概率是分辨率设太低或 prompt 不对。批量 PDF 测试用 vLLM 的run_dpsk_ocr_pdf.py。跑之前记录基线吞吐tok/s 和页/秒。A100-40G 上 2500 tok/s 对应大约每页 2-3 秒。如果你的吞吐明显低于这个数检查是不是开了 Gundam 模式或分辨率设太高。结果核验建议随机抽样 100 页计算字符级和词级准确率同时人工检查表格和公式的结构保真度。我实测下来纯文字页面准确率很高双栏排版的顺序基本正确复杂表格偶尔会丢列公式还原依赖 prompt 的引导。模式选择上先用 Small640 分辨率100 token跑一遍页复杂或公式多再切 Base1024256 token极复杂用 Large/Gundam。核验时统计生成长度、错误率和耗时找到精度和速度的平衡点。Prompt 工程方面文档转 Markdown 用|grounding|Convert the document to markdown.只做 OCR 用Free OCR.表格抽取和图解析在 README 里有示例 prompt。不同 prompt 对输出格式影响很大建议先固定一个 prompt 跑基线再逐步调优。5. 常见报错排查flash-attn 编译失败与 vLLM 版本冲突这一节对照真实报错给排查路径。flash-attn 编译或导入失败。症状是pip install flash-attn时报编译错误或 import 时提示 CUDA/torch 版本不匹配。根因通常是 torch 版本和 CUDA 版本对不上。快速定位pip show torch看版本nvcc -V看 CUDA 版本。处置固定 torch2.6.0 cu118重装 flash-attn安装时加--no-build-isolation。vLLM 起不来或导入冲突。症状是import vllm报错或启动时提示 transformers 版本不兼容。根因是 vLLM 和 transformers 版本耦合。快速定位pip freeze | grep vllm和pip freeze | grep transformers。处置调整 vLLM 或 transformers 版本至兼容状态vLLM 0.8.5 对应 transformers 4.46 左右。显存爆或吞吐异常。症状是 OOM 或 tok/s 远低于 2500。根因是分辨率或模式选太大。快速定位监控显存使用情况nvidia-smi看占用。处置从 Small640起测降分辨率、关 Gundam、增批量与流水线优化。401 报错。如果你走 TaoToken API 路线遇到 401 说明 API Key 无效或没传对。检查请求头里的 Authorization 字段确认 Key 是从控制台复制的完整字符串。本地推理不会出这个错只有 API 调用才会。local proxy failed。这个报错通常出现在网络请求环节检查你的请求地址是不是https://taotoken.net/api不要多加路径或参数。reading choices 报错。这是响应解析问题通常是返回体格式和你的解析代码不匹配。打印完整响应体看结构确认choices[0].message.content字段存在。OAuth 相关报错。如果你用 Claude Code 或类似工具接入OAuth 流程走不通时检查回调地址和 Key 权限。CC Switch、Cline MCP、Codex auth.json 这三件套的配置要写全Base URL、Key、Model ID 一个都不能少。6. 语义一致 CTA按场景选接入路径跑通最小测试后根据你的实际场景选下一步。如果你还在验证阶段想快速判断 DeepSeek-OCR 适不适合你的文档类型直接走 TaoToken 的模型对话接口用统一 Key 调单图测试五分钟出结果。地址https://taotoken.net/api Key 在控制台生成。如果你确定要长期用、批量处理文档建议本地 vLLM 部署控成本和数据隐私。部署前先到接入文档确认最新的依赖版本和参数配置避免版本冲突。如果你是要做长期编码或 Agent 集成比如把 OCR 能力嵌到自动化流程里走 Coding Plan 更合适统一管理 Key 和调用配额。排障和接入细节看 API Keys 和接入文档模型能力验证走模型对话长期编码和 Agent 场景走 Coding Plan。三条路按需选不用全走一遍。
