1. 简介DeepSeek-OCR 2 是 DeepSeek 团队于2026 年 1 月 26 日正式开源的新一代光学字符识别OCR模型代表了文档智能理解领域的重大突破。该模型的核心创新是视觉因果流Visual Causal Flow技术这是一种全新的文档解析范式彻底改变了机器阅读文档的方式。与传统 OCR 系统按像素顺序从左上到右下机械扫描的方式不同DeepSeek-OCR 2 通过视觉因果流模拟人类的阅读方式——它不会按固定的栅格顺序遍历文档而是根据语义意义而非空间坐标来识别重要信息。模型首先对整个文档建立全局理解然后智能地决定逻辑阅读顺序例如遵循列的布局、将标签与其值关联、以及连贯地解析表格。在技术架构上DeepSeek-OCR 2 采用了DeepEncoder V2视觉编码器这是一个将视觉编码器转变为推理模型的创新架构。它通过可学习的查询 token 逐步处理信息每个步骤都依赖于前一个步骤从而在源头修复阅读顺序并将视觉与语言自然对齐。该模型具备高效的视觉-文本压缩能力可以将1,000 个文本 token 压缩成仅 100 个视觉 token同时保持超过 97% 的解码准确率。在生产环境中模型能够在一张 A100-40G GPU 上每天生成或解析超过 200,000 页的文档。目前相关内容已经在官网中可以直接安装使用了NVIDIA Alpamayo自动生成项目中了。2. 环境配置2.1 系统要求在开始部署 DeepSeek-OCR 2 之前请确保您的系统满足以下硬件和软件要求。由于模型采用了大规模的视觉-语言架构对计算资源有一定要求配置项最低要求推荐配置CUDA 版本11.812.1Python 版本3.83.10/3.11GPU 显存16GB24GB系统内存32GB64GB操作系统Linux (Ubuntu 20.04)Ubuntu 22.04注意事项如果您的显存低于 16GB可以通过调整gpu_memory_utilization参数如设为 0.6和减小max_model_len如设为 4096来降低显存占用但这可能会影响处理长文档的能力。2.2 安装步骤以下是完整的环境安装流程。建议使用 Conda 创建独立的虚拟环境以避免与系统中其他 Python 项目产生依赖冲突。整个安装过程需要下载约 10GB 的依赖包和模型文件请确保网络连接稳定。# 1. 克隆代码仓库# 从 GitHub 获取 DeepSeek-OCR 2 的官方代码gitclone https://github.com/deepseek-ai/DeepSeek-OCR-2.gitcdDeepSeek-OCR-2# 2. 创建 Conda 虚拟环境# 使用 Python 3.8 创建名为 deepseek-ocr2 的独立环境conda create-ndeepseek-ocr2python3.8-yconda activate deepseek-ocr2# 3. 安装 PyTorchCUDA 11.8 版本# 根据您的 CUDA 版本选择对应的 PyTorch 安装命令pipinstalltorch2.6.0torchvision0.21.0torchaudio2.6.0\--index-url https://download.pytorch.org/whl/cu118# 4. 安装 vLLM 推理引擎官方指定版本# 必须使用 v0.8.5 版本其他版本可能存在 API 兼容性问题pipinstallhttps://github.com/vllm-project/vllm/releases/download/v0.8.5/vllm-0.8.5cu121-cp38-abi3-manylinux1_x86_64.whl# 5. 安装项目依赖和 Flash Attention# Flash Attention 可显著提升推理速度pipinstall-rrequirements.txt pipinstallflash-attn2.7.3 --no-build-isolation常见问题如果在安装 flash-attn 时遇到编译错误请确保已安装 CUDA Toolkit 和对应版本的 GCC 编译器。3. 快速开始3.1 方式一vLLM 推理适合生产环境vLLM 是一个高性能的大语言模型推理引擎专为生产环境设计。相比原生 Transformers 推理vLLM 通过 PagedAttention 技术实现了更高效的显存管理支持连续批处理Continuous Batching和并发请求处理。在实际测试中vLLM 的推理速度可达原生实现的 3-5 倍特别适合需要处理大量文档的批量 OCR 场景。DeepSeek-OCR 2 官方提供了基于 vLLM 的推理脚本支持单图推理和 PDF 批量处理两种模式。单图推理采用流式输出可以实时查看识别进度PDF 处理则会自动将文档拆分为单页图像逐页进行识别后合并结果。# 进入 vLLM 推理目录cdDeepSeek-OCR2-master/DeepSeek-OCR2-vllm# 单图推理流式输出适合交互式使用# 运行后会提示输入图片路径识别结果实时显示python run_dpsk_ocr2_image.py# PDF 批量处理适合文档数字化场景# 自动处理 PDF 中的所有页面输出结构化 Markdownpython run_dpsk_ocr2_pdf.py3.2 方式二Gradio 可视化界面推荐新手对于不熟悉命令行操作的用户我们提供了基于 Gradio 框架的 Web 可视化界面。Gradio 是 Hugging Face 推出的机器学习演示工具能够快速将 AI 模型封装为交互式 Web 应用。通过这个界面您可以直接在浏览器中上传图片、选择识别模式、查看 OCR 结果和边界框可视化效果无需编写任何代码。该界面支持四种识别模式文档转 Markdown保留文档结构、纯文字识别仅提取文本、表格识别专门处理表格内容以及自定义提示词高级用户可自行编写指令。识别完成后界面会同时显示清理后的文本结果和带有边界框标注的可视化图像方便您直观地了解模型对文档各区域的识别情况。3.2.1 安装 Gradio首先需要安装 Gradio 库。Gradio 的安装非常简单只需一条 pip 命令即可完成。建议安装最新版本以获得最佳的界面体验和功能支持。pipinstallgradio3.2.2 启动界面将以下代码保存为deepseek_ocr2_gradio.py放入DeepSeek-OCR2-vllm目录。这段代码实现了完整的 Web 界面功能包括图像加载、模型推理、边界框绘制和结果展示。代码采用异步架构设计能够高效处理用户请求同时通过全局引擎变量避免模型重复加载提升响应速度。 DeepSeek-OCR 2 Gradio 可视化界面 importasyncioimportreimportosimporttimeimportnumpyasnpfromPILimportImage,ImageDraw,ImageFont,ImageOpsimporttorchimportgradioasgr# 环境配置iftorch.version.cuda11.8:os.environ[TRITON_PTXAS_PATH]/usr/local/cuda-11.8/bin/ptxasos.environ[VLLM_USE_V1]0os.environ[CUDA_VISIBLE_DEVICES]0fromvllmimportAsyncLLMEngine,SamplingParamsfromvllm.engine.arg_utilsimportAsyncEngineArgsfromvllm.model_executor.models.registryimportModelRegistryfromdeepseek_ocr2importDeepseekOCR2ForCausalLMfromprocess.ngram_norepeatimportNoRepeatNGramLogitsProcessorfromprocess.image_processimportDeepseekOCR2Processor# 配置MODEL_PATHdeepseek-ai/DeepSeek-OCR-2ModelRegistry.register_model(DeepseekOCR2ForCausalLM,DeepseekOCR2ForCausalLM)engineNone# 全局引擎defload_image(image):加载图像try:ifisinstance(image,str):imageImage.open(image)returnImageOps.exif_transpose(image).convert(RGB)except:returnNonedefre_match(text):提取边界框patternr(\|ref\|(.*?)\|/ref\|\|det\|(.*?)\|/det\|)matchesre.findall(pattern,text,re.DOTALL)matches_image[m[0]forminmatchesif|ref|image|/ref|inm[0]]matches_other[m[0]forminmatchesif|ref|image|/ref|notinm[0]]returnmatches,matches_image,matches_otherdefdraw_boxes(image,refs):绘制边界框w,himage.size img_drawimage.copy()drawImageDraw.Draw(img_draw)fontImageFont.load_default()forrefinrefs:try:labelref[1]coordseval(ref[2])color(np.random.randint(0,200),np.random.randint(0,200),np.random.randint(0,255))forx1,y1,x2,y2incoords:x1,y1int(x1/999*w),int(y1/999*h)x2,y2int(x2/999*w),int(y2/999*h)draw.rectangle([x1,y1,x2,y2],outlinecolor,width2)draw.text((x1,max(0,y1-15)),label,fontfont,fillcolor)except:continuereturnimg_drawasyncdefasync_generate(image_features,prompt):异步推理globalengineifengineisNone:engine_argsAsyncEngineArgs(modelMODEL_PATH,hf_overrides{architectures:[DeepseekOCR2ForCausalLM]},dtypebfloat16,max_model_len8192,trust_remote_codeTrue,gpu_memory_utilization0.75,)engineAsyncLLMEngine.from_engine_args(engine_args)sampling_paramsSamplingParams(temperature0.0,max_tokens8192,logits_processors[NoRepeatNGramLogitsProcessor(20,90,{128821,128822})],skip_special_tokensFalse,)request{prompt:prompt}ifimage_featuresandimageinprompt:request[multi_modal_data]{image:image_features}final_outputasyncforoutinengine.generate(request,sampling_params,freq-{time.time()}):ifout.outputs:final_outputout.outputs[0].textreturnfinal_outputdefprocess_ocr(image,mode,custom_prompt,crop_mode):主处理函数ifimageisNone:return请上传图片,Nonepil_imageload_image(image)ifpil_imageisNone:return图像加载失败,Noneprompts{文档转 Markdown:image\n|grounding|Convert the document to markdown.,纯文字识别:image\nFree OCR.,表格识别:image\n|grounding|Extract the table content.,自定义:custom_promptorimage\nFree OCR.}promptprompts.get(mode,prompts[纯文字识别])# 处理图像image_featuresDeepseekOCR2Processor().tokenize_with_images(images[pil_image],bosTrue,eosTrue,croppingcrop_mode)ifimageinpromptelseNone# 推理try:resultasyncio.run(async_generate(image_features,prompt))exceptExceptionase:returnf错误:{e},None# 绘制边界框matches,_,_re_match(result)result_imagedraw_boxes(pil_image,matches)# 清理文本forminmatches:resultresult.replace(m[0],)returnresult,result_image# Gradio 界面withgr.Blocks(titleDeepSeek-OCR 2)asdemo:gr.Markdown(# DeepSeek-OCR 2 可视化界面)withgr.Row():withgr.Column():input_imagegr.Image(label上传图片,typepil)modegr.Radio([文档转 Markdown,纯文字识别,表格识别,自定义],value文档转 Markdown,label识别模式)custom_promptgr.Textbox(label自定义提示词,visibleTrue)crop_modegr.Checkbox(label裁剪模式,valueTrue)btngr.Button(开始识别,variantprimary)withgr.Column():output_textgr.Textbox(label识别结果,lines15)output_imagegr.Image(label边界框可视化)btn.click(process_ocr,[input_image,mode,custom_prompt,crop_mode],[output_text,output_image])demo.launch(server_name0.0.0.0,server_port7860)3.2.3 运行完成代码保存后在终端中执行以下命令启动 Gradio 服务。首次运行时程序会自动从 Hugging Face 下载 DeepSeek-OCR-2 模型权重约 8GB请确保网络连接稳定。模型加载完成后您将在终端看到服务启动成功的提示信息。cdDeepSeek-OCR2-master/DeepSeek-OCR2-vllm python deepseek_ocr2_gradio.py启动成功后打开浏览器访问http://localhost:7860即可使用 Web 界面。如果您需要从其他设备访问可以将代码中的server_name参数设为0.0.0.0这样局域网内的其他设备也能通过您的 IP 地址访问该服务。界面加载完成后您将看到左侧的图片上传区域和参数设置面板右侧则是识别结果展示区域。4. 常用提示词DeepSeek-OCR 2 通过不同的提示词Prompt来控制输出格式和识别行为。提示词中的image标记表示图像输入位置|grounding|标记则启用边界框检测功能使模型在输出文本的同时标注各元素在图像中的位置坐标。以下是三种最常用的提示词模板任务类型提示词适用场景文档转 Markdownimage\n|grounding|Convert the document to markdown.保留文档结构输出带格式的 Markdown纯文字识别image\nFree OCR.仅提取文本内容不保留格式表格识别image\n|grounding|Extract the table content.专门处理表格输出结构化数据提示您也可以编写自定义提示词来实现特定需求例如image\n|grounding|Extract all mathematical formulas.可以专门提取文档中的数学公式。5. 参数说明在使用 DeepSeek-OCR 2 时有几个关键参数会影响识别效果和性能表现。合理调整这些参数可以在不同场景下获得最佳的识别结果。以下是各参数的详细说明参数说明默认值调整建议base_size基础分辨率影响图像预处理1024高清文档可适当增大image_size图像处理尺寸影响显存占用768显存不足时可减小crop_mode是否启用裁剪模式True大图/长文档推荐开启save_results是否保存结果到文件True批量处理时建议开启gpu_memory_utilizationGPU 显存利用率0.75显存不足时可降至 0.6max_model_len最大序列长度8192长文档需要更大值裁剪模式说明当处理大尺寸图像或长文档时启用裁剪模式crop_modeTrue可以将图像智能分割为多个子区域分别处理然后合并结果。这种方式能够有效避免显存溢出同时保持识别精度。6. 常见问题6.1 Q1: 出现ImportError: cannot import name SamplingMetadata错误原因vLLM 版本不兼容。DeepSeek-OCR 2 依赖特定版本的 vLLM API而较新或较旧版本的 vLLM 可能已经修改了相关接口。解决方案卸载当前 vLLM 版本安装官方指定的 v0.8.5 版本pip uninstall vllm-ypipinstallhttps://github.com/vllm-project/vllm/releases/download/v0.8.5/vllm-0.8.5cu121-cp38-abi3-manylinux1_x86_64.whl6.2. Q2: 显存不足CUDA Out of Memory原因模型加载和推理过程中显存占用超过了 GPU 可用显存。解决方案调整以下参数降低显存占用engine_argsAsyncEngineArgs(gpu_memory_utilization0.6,# 降低显存利用率max_model_len4096,# 减小最大序列长度)6.3 Q3: 模型下载速度慢或失败原因Hugging Face 服务器在国内访问可能不稳定。解决方案使用国内镜像源或手动下载模型后指定本地路径MODEL_PATH/path/to/local/DeepSeek-OCR-2# 修改为本地模型路径7. 总结DeepSeek-OCR 2 作为新一代智能文档识别模型通过视觉因果流技术实现了从像素扫描到语义理解的范式跃迁。本教程介绍了从环境配置、模型部署到实际使用的完整流程涵盖了命令行推理和可视化界面两种使用方式。无论您是需要批量处理企业文档的开发者还是希望快速体验 OCR 能力的研究人员都可以根据自身需求选择合适的部署方案。随着 DeepSeek 团队持续迭代优化未来模型在多语言支持、手写识别、复杂版式解析等方面还将带来更多惊喜。建议关注官方 GitHub 仓库获取最新更新也欢迎在社区中分享您的使用经验和改进建议。