DotsOCR 环境搭建指南

支持平台：Linux（推荐）或 Windows + WSL2
项目地址：
https://github.com/rednote-hilab/dots.ocr

一、Windows 用户：启用 WSL 并安装 Ubuntu

仅适用于 Windows 10 版本 2004 及以上（内核版本 ≥ 19041）或 Windows 11。

1. 检查系统版本

• 按下 Win + R，输入 winver，确认系统版本满足要求。
• 若不满足，请参考微软官方文档进行手动安装：旧版 WSL 的手动安装步骤 | Microsoft Learn

2. 启用 WSL 功能

以管理员身份运行 PowerShell：

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

重启计算机后继续下一步。

3. 安装 Ubuntu 发行版

1. 打开 Microsoft Store
2. 搜索 Ubuntu
3. 推荐选择长期支持版本（如 Ubuntu 18.04.5 LTS 或 20.04 LTS）
4. 下载并启动，按提示设置用户名和密码

成功标志：终端中出现 username@hostname:~$ 提示符。

二、在 Ubuntu 中安装 Conda

1. 下载 Miniconda

访问官网获取最新链接，或执行以下命令（以 Python 3.9 为例）：

wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-Linux-x86_64.sh

2. 赋予执行权限并安装

chmod +x Miniconda3-py39_4.12.0-Linux-x86_64.sh
./Miniconda3-py39_4.12.0-Linux-x86_64.sh

按提示完成安装（接受协议、选择路径等）。

3. 配置环境变量

编辑 ~/.bashrc 文件：

vi ~/.bashrc

在文件末尾添加：

export PATH=$HOME/miniconda3/bin:$PATH

保存并生效：

source ~/.bashrc

4. 验证安装

conda --version

输出类似：conda 4.12.0 表示成功。

三、创建 DotsOCR 虚拟环境

1. 创建并激活环境

conda create -n dots_ocr python=3.12
conda activate dots_ocr

推荐使用 Python 3.12 以兼容最新依赖。

四、克隆项目代码

重要提醒：项目名为 dots.ocr，但后续模型路径不能含 .，因此需重命名！

git clone https://github.com/rednote-hilab/dots.ocr.git
mv dots.ocr dots_ocr  # 将目录名中的点改为下划线
cd dots_ocr

此时项目路径为：./dots_ocr/

五、安装 PyTorch 与 CUDA 支持

1. 查看 CUDA 版本

nvidia-smi

查看顶部显示的 CUDA Version（例如 12.8）

2. 安装对应版本的 PyTorch（示例为 CUDA 12.8）

pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 \
  --index-url https://download.pytorch.org/whl/cu128

若你的 CUDA 是 12.4，请将 cu128 改为 cu124

六、安装 CUDA 工具链（解决编译问题）

conda install cuda-toolkit -c nvidia

用于支持 flash-attn 等库的本地编译。

七、安装项目依赖

pip install -e .

-e 表示可编辑模式，便于开发调试。

八、下载模型权重

再次强调：模型保存目录名不能包含 .

使用 ModelScope（国内推荐）

python tools/download_model.py --type modelscope

默认会下载到：

./weights/DotsOCR/

建议保持此目录名为 DotsOCR（无点号）

九、使用 vLLM 部署（推荐方式）

1. 设置环境变量

export hf_model_path=./weights/DotsOCR
export PYTHONPATH=$(dirname "$hf_model_path"):$PYTHONPATH

2. 注册自定义模型模块到 vLLM

修改 vllm 入口脚本，使其加载 DotsOCR 自定义模型类。

sed -i '/^from vllm\.entrypoints\.cli\.main import main$/a\
from DotsOCR import modeling_dots_ocr_vllm' `which vllm`

注意事项：

• 确保 DotsOCR 是你的模型目录名（不含 .）
• 如果你用了 dots_ocr，请替换：sed -i 's/DotsOCR/dots_ocr/g' `which vllm`
• 查看 vllm 路径：which vllm
• 若权限不足，尝试 sudo 或检查虚拟环境权限。

3. 启动 vLLM 服务

CUDA_VISIBLE_DEVICES=0 \
vllm serve ${hf_model_path} \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.95 \
  --chat-template-content-format string \
  --served-model-name DotsOCR \
  --trust-remote-code

服务默认监听 http://localhost:8000

十、测试 vLLM 推理接口

python ./demo/demo_vllm.py --prompt_mode prompt_layout_all_en

支持不同 --prompt_mode 参数，请根据需求调整。

十一、启动 Web API 服务（Flask + vLLM）

复制示例 API 文件至项目目录（若不存在）：

cp ./demo/vllm_flask_api.py ./demo/flask_api.py  # 如有需要

启动服务：

python ./demo/vllm_flask_api.py

默认端口：5080
接口地址示例：http://<your-server-ip>:5080/inference

十二、Hugging Face 原生推理（可选）

如果你不想使用 vLLM，也可以直接运行原生 HF 推理：

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained(
    "./weights/DotsOCR",
    trust_remote_code=True
)
tokenizer = AutoTokenizer.from_pretrained("./weights/DotsOCR", trust_remote_code=True)

同样要求：路径不含 .，且设置 trust_remote_code=True

常见问题与解决方案

最终建议

• 所有涉及路径的名称避免使用 .（如 dots.ocr → dots_ocr ）
• 推荐使用 vLLM 0.9.1+ 版本部署
• 国内用户优先使用 --type modelscope 下载模型