DeepSeek-OCR 在本地该如何部署?除了基本的硬件要求,还需要做好环境的前置工作,相对还是比较复杂的,大家可以根据下面流程进行操作！
一、DeepSeek-OCR 本地部署全流程
1. 前置条件说明
DeepSeek-OCR 是深度求索推出的高性能开源 OCR 工具，支持多语言、多场景文字识别，本地部署需满足以下基础条件：
硬件：CPU(任意型号)即可运行，NVIDIA 显卡(显存≥4GB)可加速推理;无显卡也可正常使用，仅识别速度稍慢。
系统：Windows 10/11、Linux(Ubuntu 20.04+/CentOS 7+)、macOS 12+。
软件：Python 3.8~3.11(推荐 3.9.兼容性最佳)、Git、pip(Python 包管理工具)。
2. 环境准备
(1)安装基础软件
Python：从Python 官网下载对应版本，安装时务必勾选「Add Python to PATH」。
Git：从Git 官网安装，默认选项即可，用于克隆项目仓库。
显卡加速（可选）：NVIDIA 显卡用户需安装 CUDA 11.7 + 和 cuDNN 8.8+，安装流程参考 NVIDIA 官方文档，无显卡可跳过。
(2)验证基础环境
打开命令提示符(CMD)/ 终端，执行以下命令验证安装：
bash
运行
# 验证Python版本
python –version # 输出Python 3.9.x即正常
# 验证Git
git –version # 输出Git版本号即正常
# 验证pip(可选)
pip –version
星宇智算官网支持免费部署立马安装！点击下方立即试用!
3. 部署步骤
(1)克隆项目仓库
bash
运行
# 克隆DeepSeek-OCR仓库(官方开源地址)
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
# 进入项目目录
cd DeepSeek-OCR
(2)创建并激活虚拟环境(推荐)
虚拟环境可避免依赖冲突，是 Python 项目的最佳实践：
bash
运行
# 创建虚拟环境(命名为venv)
python -m venv venv
# Windows激活虚拟环境
venv\Scripts\activate
# Linux/macOS激活虚拟环境
source venv/bin/activate
# 激活后终端前缀会显示(venv)，表示进入虚拟环境
(3)安装依赖包
国内用户建议使用清华镜像源加速下载，避免依赖安装失败：
bash
运行
# 升级pip到最新版本
pip install –upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
# 安装核心依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 安装PyTorch(显卡用户装CUDA版本，CPU用户装CPU版本)
# 显卡版(CUDA 11.7)
pip install torch==2.0.1 torchvision==0.15.2 –index-url https://download.pytorch.org/whl/cu117
# CPU版(无显卡用户)
pip install torch==2.0.1 torchvision==0.15.2 –index-url https://download.pytorch.org/whl/cpu
(4)下载预训练模型
DeepSeek-OCR 依赖预训练模型才能运行，步骤如下：
进入项目目录下的models文件夹(无则手动新建);
从官方 Hugging Face 仓库(https://huggingface.co/deepseek-ai/DeepSeek-OCR)下载模型文件(包括deepseek-ocr-base.pt等核心文件);
将下载的所有模型文件放入models文件夹，确保文件路径无中文、空格等特殊字符。
(5)启动网页版服务
bash
运行
# 启动WebUI(默认端口8000)
python webui.py
# 若端口被占用，指定其他端口(如8080)
python webui.py –port 8080
启动成功后，终端会输出访问地址(如http://127.0.0.1:8000)，打开浏览器访问该地址即可进入 DeepSeek-OCR 网页界面。
(6)功能测试
在网页界面中：
点击「上传图片」，选择包含文字的图片(支持 jpg、png、pdf 等格式);
点击「开始识别」，等待几秒即可看到识别结果;
可选择「导出结果」将识别文字保存为 txt、json 等格式。
二、常见问题解答(FAQ)
1. 执行webui.py提示「No module named ‘xxx’」?
原因：依赖包未安装完整，或未激活虚拟环境。
解决：
确认终端前缀有(venv)，未激活则重新执行激活命令;
重新安装依赖：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple;
若仍报错，手动安装缺失包：pip install xxx(xxx 为缺失的包名)。
2. 启动 WebUI 后浏览器无法访问http://127.0.0.1:8000?
原因：端口被占用、防火墙拦截，或启动命令指定了错误地址。
解决：
更换端口启动：python webui.py –port 8080.访问http://127.0.0.1:8080;
Windows 关闭防火墙，或允许 Python 通过防火墙;
Linux/macOS 执行sudo ufw allow 8000放行端口。
3. 识别图片时提示「模型文件不存在」?
原因：预训练模型未下载，或文件路径错误。
解决：
确认models文件夹内有完整的模型文件，无遗漏;
检查模型文件名与代码中指定的名称一致(默认无需修改，只需文件存在);
确保模型文件路径无中文、空格、特殊符号(如D:\DeepSeek-OCR\models是合法路径，D:\深度学习\OCR模型不合法)。
4. 显卡可用但识别速度慢，未调用 GPU?
原因：PyTorch 安装了 CPU 版本，或 CUDA 环境未配置成功。
解决：
执行python -c “import torch; print(torch.cuda.is_available())”，输出True表示 CUDA 可用，False则重新安装显卡版 PyTorch;
更新显卡驱动到最新版本，重启电脑后重试。
5. 识别中文乱码 / 识别准确率低?
原因：图片质量差，或模型不匹配场景。
解决：
上传清晰的图片，避免模糊、倾斜、强光 / 阴影;
复杂场景(如手写、竖排文字)可在网页界面选择「高精度模式」;
确认使用的是完整的中文预训练模型，而非轻量版。
6. macOS 系统提示「OSError: dlopen (libtorch.dylib) failed」?
原因：macOS 系统依赖库缺失。
解决：
安装 Xcode 命令行工具：xcode-select –install;
安装 Homebrew 后执行brew install libomp;
重新安装 PyTorch 的 macOS 版本：pip install torch torchvision –upgrade。
环境核心：Python 3.8~3.11 + 匹配的 PyTorch 版本是部署成功的基础，虚拟环境能有效避免依赖冲突;
部署关键：克隆仓库→安装依赖→下载模型→启动 WebUI，模型文件完整且路径合法是识别功能正常的前提;
问题排查：依赖缺失补装对应包、端口占用换端口、GPU 未调用检查 CUDA 和 PyTorch 版本、识别异常优化图片质量。
DeepSeek-OCR 本地部署的核心是「环境匹配」和「模型完整」，新手建议优先在 Windows 系统测试，熟悉流程后再部署到 Linux 服务器。
