让你的Mac用上DeepSeek-OCR：一个从0到1的开源适配之旅

DeepSeek-OCR这段时间非常火，但官方开源的文件是“按 NVIDIA/CUDA 习惯写的 Linux 版推理脚本+模型权重”，而不是“跨设备跨后端”的通吃实现，因此无法直接在苹果设备上运行，对于Mac用户来说，在许多新模型诞生的第一时间，往往只能望“模”兴叹。得益于开源社区的探索，如今已有了可行路径，我在此基础上写了一个能让DeepSeek-OCR在Macos上跑起来的项目 DeepSeek-OCR_macOS。目前已开源，欢迎大家使用反馈。

https://github.com/xiumaoprompt/DeepSeek-OCR_macOS

基本介绍

DeepSeek-OCR_macOS 不仅仅是让模型能在Mac上“跑起来”，我希望提供的是一种“开箱即用”的、顺滑流畅的完整体验。

它是一个集成了以下特性的完整工作流：

• 一键式配置: 我编写了一个独创的setup.py自动化脚本。用户无需手动修改任何代码、处理复杂的路径问题或担心Python的导入错误，只需运行一个命令，脚本就会像一位贴心管家，引导你完成所有环境配置。
• Gradio图形界面: 项目配备了简洁易用的Gradio Web UI，你只需要在浏览器中拖拽上传图片或PDF，点击按钮，即可获得高质量的OCR结果。
• macOS兼容: 在 Apple Silicon 与 Intel 的 CPU 上稳定运行；提供 MPS（Apple GPU）实验性支持。
• 纯本地化运行: 所有计算都在你的本地设备上完成，完美保障了你的数据隐私和安全。 项目的目标是：让在Mac上部署和使用DeepSeek-OCR，变得像安装一个普通软件一样简单。

操作流程：只需三步

项目把复杂的流程封装到了极致。你只需要跟随下面三个简单的步骤，就能在自己的Mac上运行起DeepSeek-OCR。

第一步：下载项目和模型

首先，你需要把项目代码和DeepSeek的官方模型克隆到本地。

# 1. 克隆项目

git clone https://github.com/xiumaoprompt/DeepSeek-OCR_macOS.git

cd DeepSeek-OCR_macOS

# 2. 克隆官方模型 (需要先安装 git-lfs)

git lfs install

git clone https://huggingface.co/deepseek-ai/DeepSeek-OCR

第二步：呼叫“管家” (运行自动化配置)

这是整个流程中最“神奇”的一步。运行我为你准备的setup.py脚本：

python setup.py

这位“管家”会启动一个交互式程序，一步步引导你：

1. 找到模型：让你把刚刚下载的DeepSeek-OCR文件夹拖进终端，它会自动获取并验证路径。
2. 施行“手术”：自动用我修改过的、兼容macOS的文件，替换掉模型中原有的核心脚本。
3. 搭建“桥梁”：为你处理好Python的模块导入问题。
4. 写入“记忆”：将模型路径永久记录在配置文件中。

你无需理解这背后的复杂原理，只需跟着提示按几下回车。

第三步：启动引擎！

当“管家”告诉你一切就绪后，你就可以安装依赖并启动Web UI了。

# 安装所有依赖

pip install -r pip-requirements.txt

# 启动Gradio应用

python -m macos_workflow.app

现在，打开浏览器，访问终端中显示的地址（如 http://127.0.0.1:7860），一个强大的本地OCR工具就在你面前了。

原理揭秘

从“无法运行”到“顺畅使用”，此项目的核心主要解决了一个核心问题：设备不兼容。

1.核心“手术”：修改modeling_deepseekocr.py

这是整个移植工作的核心。在huggingface上的原始代码充满了device='cuda'这样的硬编码，并且使用了一些在macOS的MPS后端上支持不佳或效率低下的数据类型（如bfloat16）。

“手术”主要包括：

• 解除设备绑定：将所有写死的'cuda'设备指定，改为了一个从配置文件读取的、动态的device变量。这样，代码就能自动适应'mps'或'cpu'。
• 数据类型适配：将一些在MPS上可能出错的数据类型（如torch.bfloat16）替换为更稳定、兼容性更广的torch.float32，确保模型能在不同硬件上稳定运行。
• 修正张量操作：确保所有参与计算的Tensor（张量）在进行运算前，都被正确地移动到了用户指定的设备上，避免了“张量不在同一设备”的常见PyTorch错误。

这个过程就像是把一个只习惯用右手写字的人，教会他如何用左手同样流利地书写。

写在最后

这个项目源于一个简单的个人需求，但它最终演变成了一个遵循开源精神的完整解决方案。如果你也对这个项目感兴趣，欢迎加群一起讨论！

文章来自于“Al修猫Prompt”，作者“Al修猫Prompt”。