# 环境选择
```bash
git clone https://gitee.com/zhch158_admin/dots.ocr.git

git config --local user.name "zhch158_admin"
git config --local user.email "zhch158@sina.com"
# 自定义缓存时间（如7200秒）
git config --global credential.helper 'cache --timeout=7200'

conda create -n dots.ocr python=3.12
# vllm目前最高支持到3.12

```

# Linux安装
flash-attn 确实没有 macOS 的预编译包，因为 flash-attn 是专门为 NVIDIA GPU（CUDA）设计的，而 Mac 使用的是 Apple Silicon 或 Intel CPU，不支持 CUDA
![1755961939668](image/study-notes/1755961939668.png)
```bash
cd dots.ocr

conda activate dots.ocr
uv pip install -U torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://download.pytorch.org/whl/cu126

# dots.ocr目前使用transformers-4.51.3
# vllm必须降级，只能使用0.9.1
# 但vllm 0.10.1.1 requires transformers>=4.55.0
uv pip install -e .

# 安装最新版vllm
uv pip install -U vllm==0.9.1

# 解决vllm版本兼容问题，检查当前版本
pip list | grep -E "(vllm|transformers|torch|flash_attn|flashinfer)"

# 查看端口占用情况
sudo lsof -i:8101

# 显示所有监听的端口
sudo ss -tuln

# 显示特定端口
sudo ss -tulpn | grep :8101

# 显示进程信息
sudo ss -tulpn sport = :8101

# 更新后下载模型 # with modelscope
python3 tools/download_model.py --type modelscope
```

# 修复CUDA链接
```bash
# 移除错误的符号链接
sudo rm -f /usr/lib/x86_64-linux-gnu/libcuda.so*
sudo rm -f /usr/local/cuda*/lib64/libcuda.so*

# 找到真正的 NVIDIA 驱动库
find /usr -name "libcuda.so*" 2>/dev/null

# 创建正确的符号链接（假设找到了 /usr/lib/x86_64-linux-gnu/libcuda.so.570.169）
sudo ln -sf /usr/lib/x86_64-linux-gnu/libcuda.so.570.169 /usr/lib/x86_64-linux-gnu/libcuda.so.1
sudo ln -sf /usr/lib/x86_64-linux-gnu/libcuda.so.1 /usr/lib/x86_64-linux-gnu/libcuda.so

# 运行诊断命令
nvidia-smi
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.device_count())"
```


# MAC 安装
```zsh
cd dots.ocr
conda activate py312

uv pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 

# 跳过依赖安装
uv pip install -e . --no-deps

# 手动安装兼容的依赖
uv pip install -r zhch/requirements-macos.txt

```

# 设置launch.json
```json
	"configurations": [
		{
			"name": "Python Debugger: Current File",
			"type": "debugpy",
			"request": "launch",
			"program": "${file}",
			"console": "integratedTerminal",
			"cwd": "${fileDirname}",
			"env": {"PYTHONPATH":"${workspaceFolder};${env:PYTHONPATH}"},
			"envFile": "${workspaceFolder}/.env",
			"justMyCode": false
		},
		{
			"name": "app",
			"type": "debugpy",
			"request": "launch",
			// "module": "paddlex.__main__",
			"program": "${workspaceFolder}/zhch/paddlex_cli.py",
			"console": "integratedTerminal",
			"cwd": "${workspaceFolder}/zhch",
			"env": {"PYTHONPATH":"${workspaceFolder};${env:PYTHONPATH}"},
			"envFile": "${workspaceFolder}/.env",
			"args": [
				// "-m", "paddlex.paddlex_cli",
				// "--get_pipeline_config", "${workspaceFolder}/zhch/PP-StructureV3-zhch.yaml"
				"--pipeline", "PP-StructureV3",
				"--use_doc_orientation_classify=True",
				"--use_doc_unwarping=True",
				"--input", "sample_data/300674-母公司现金流量表-扫描.png",
				"--save_path", "sample_data/output",
				"--device", "gpu",
			],
			"justMyCode": false
		}
	]
```

# 启动脚本
zhch/launch_model_vllm.sh
需要在/home/ubuntu/anaconda3/envs/dots.ocr/bin/vllm中加入DotsOCR
```bash
#!/home/ubuntu/anaconda3/envs/dots.ocr/bin/python3
# -*- coding: utf-8 -*-
import sys 
from vllm.entrypoints.cli.main import main
from DotsOCR import modeling_dots_ocr_vllm
if __name__ == "__main__":
    if sys.argv[0].endswith("-script.pyw"):
        sys.argv[0] = sys.argv[0][:-11]
    elif sys.argv[0].endswith(".exe"):
        sys.argv[0] = sys.argv[0][:-4]
    sys.exit(main())
```

```bash
# 监控内存使用情况
watch -n 1 nvidia-smi

# 启动应用
python demo_gradio.py
```

# 在线体验环境
```
https://dotsocr.xiaohongshu.com/
```

# Flash Attention 详细介绍

## Flash Attention 原理与优势

### 核心概念
Flash Attention 是一种高效的注意力机制实现，通过重新设计内存访问模式来显著提升性能：

1. **分块计算 (Block-wise Computation)**
   - 将大矩阵分解成小块逐块处理
   - 避免存储完整的注意力矩阵 (N×N)

2. **内存层次优化**
   - 减少 GPU 显存 (HBM) 和 SRAM 之间的数据传输
   - 利用 GPU 的内存层次结构提升效率

3. **在线 Softmax**
   - 采用数值稳定的在线算法
   - 避免中间结果的完整存储

### 性能优势
- **内存效率**: 从 O(N²) 降低到 O(N)
- **计算速度**: 长序列上可提速 2-4倍  
- **精度保持**: 与标准注意力数值相同

## 项目中的 Flash Attention 使用

### 当前配置
```python
# demo/demo_hf.py
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    attn_implementation="flash_attention_2",  # 启用 Flash Attention 2
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True
)
```

### 依赖要求
```
flash-attn==2.8.0.post2  # CUDA 专用，不支持 macOS
```

## Apple Silicon 适配方案

### 问题分析
1. **硬件限制**: Flash Attention 专为 NVIDIA CUDA GPU 设计
2. **架构差异**: Apple Silicon 使用 Metal Performance Shaders (MPS)
3. **软件兼容**: flash-attn 库不支持 macOS/Metal

## 解决方案
### 方法1
1. **移除 Flash Attention 依赖**: 在 macOS 上不使用 flash-attn
2. 修改weights/DotsOCR_CPU_bfloat16/config.json，修改"attn_implementation": "sdpa",
3. 调用程序：zhch/demo_hf_macos_bfloat16.py

### 方法2
1. **移除 Flash Attention 依赖**: 在 macOS 上不使用 flash-attn
2. 运行zhch/convert_model_float16.py，将模型转换为 float16 格式，weights/DotsOCR_float16
3. 调用程序：zhch/demo_hf_macos_float16.py

### 方法3
1. **移除 Flash Attention 依赖**: 在 macOS 上不使用 flash-attn
2. 运行zhch/convert_model_macos_float32.py，将模型转换为 float32 格式，weights/DotsOCR_float32
3. 调用程序：zhch/demo_hf_macos_float32.py

# linux上批量识别OmniDocBench数据集
```bash
cd ~/zhch/dots.ocr/zhch
conda activate dots.ocr

./vllm_daemon.sh start

python OmniDocBench_DotsOCR_multthreads.py

python OmniDocBench_DotsOCR_multthreads.py --input_file "/home/ubuntu/zhch/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf" --output_dir "./data_DotsOCR_Results" --ip "127.0.0.1" --port "8101" --model_name "DotsOCR" --prompt_mode "prompt_layout_all_en" --batch_size "1" --max_workers "3" --dpi "200"

python OmniDocBench_DotsOCR_multthreads.py --input_file "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf" --output_dir "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/data_DotsOCR_Results" --ip "10.192.72.11" --port "8101" --model_name "DotsOCR" --prompt_mode "prompt_layout_all_en" --batch_size "1" --max_workers "3" --dpi "200"

```