# [PaddleX本地安装教程](https://paddlepaddle.github.io/PaddleX/latest/installation/installation.html)

# 环境选择

```
git clone https://gitee.com/zhch158_admin/PaddleX.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'

cd PaddleX
# 安装python环境
uv venv paddle_env --python 3.11
#激活环境
source paddle_env/bin/activate

uv pip install pytest PyMuPDF
```

# 安装依赖 CPU

```
uv pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
uv pip install -e .
paddlex --install PaddleOCR PaddleDetection PaddleClas  # 例如PaddleOCR
# uv pip install paddleocr==3.2.0
```

# linux GPU - 更新版本以匹配NVML 570.169

```bash
# 首先检查NVIDIA驱动版本
nvidia-smi

# 确保驱动版本 ≥ 570.169
# 如果需要更新驱动
sudo apt update
sudo apt install nvidia-driver-570  # 或更新版本

# 安装匹配的CUDA版本（推荐12.6以匹配您的驱动）
wget https://developer.download.nvidia.com/compute/cuda/12.6.0/local_installers/cuda_12.6.0_560.28.03_linux.run
sudo sh cuda_12.6.0_560.28.03_linux.run

# 安装PaddlePaddle GPU版本
uv pip install -U --reinstall paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
uv pip install -e .
paddlex --install PaddleOCR PaddleDetection PaddleClas

# 验证安装
python -c "import paddle; print(f'CUDA available: {paddle.device.is_compiled_with_cuda()}'); print(f'GPU count: {paddle.device.cuda.device_count()}')"
```

# 模型下载源

PaddleX 支持通过环境变量 PADDLE_PDX_MODEL_SOURCE 来指定模型下载源。根据 official_models.py 中的实现，支持以下下载源：

支持的下载源
huggingface - HuggingFace（默认优先级）
modelscope - ModelScope
bos - 百度云存储
aistudio - AI Studio

```bash
# 使用百度云存储源
export PADDLE_PDX_MODEL_SOURCE="bos"
python ppstructurev3_single_process.py --input_file "file.pdf" --output_dir "./output"

# 使用 ModelScope 源
export PADDLE_PDX_MODEL_SOURCE="modelscope"
python ppstructurev3_single_process.py --input_file "file.pdf" --output_dir "./output"
```

# 设置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": "pipline ppstructurev3",
			"type": "debugpy",
			"request": "launch",
			"module": "paddlex.__main__",
			// "program": "${workspaceFolder}/paddlex/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
		}
	]
```

# 测试样例

```
paddleocr ocr -i zhch/sample_data/600916_中国黄金_2002年报_83_94_2.png --save_path zhch/sample_data/output --enable_mkldnn=False  --device=cpu

# 版面分析
paddleocr layout_detection -i zhch/sample_data/600916_中国黄金_2002年报_83_94_2.png --save_path zhch/sample_data/output --model_name="PP-DocLayout_plus-L" --enable_mkldnn=False --device=cpu

# 表格解析
paddleocr table_recognition_v2 -i zhch/sample_data/600916_中国黄金_2002年报_83_94_2.png --save_path zhch/sample_data/output --device=cpu --enable_mkldnn=False

paddleocr pp_structurev3 \
  -i zhch/sample_data/600916_中国黄金_2002年报_83_94_2.png --save_path zhch/sample_data/output \
  --enable_mkldnn=False  --device=cpu
  
paddlex --pipeline table_recognition_v2 --use_doc_orientation_classify=False --use_doc_unwarping=False --input zhch/sample_data/600916_中国黄金_2002年报_83_94_2.png --save_path zhch/sample_data/output --device cpu

paddlex --pipeline table_recognition_v2 --use_doc_orientation_classify=True --use_doc_unwarping=True --input zhch/sample_data/600916_中国黄金_2002年报_83_94_2.png --save_path zhch/sample_data/output --device cpu

# 输入是PDF
paddlex --pipeline table_recognition_v2 --use_doc_orientation_classify=True --use_doc_unwarping=True --input zhch/sample_data/至远彩色印刷工业有限公司-2022年母公司.pdf --save_path zhch/sample_data/output --device cpu
```

# macOS 查看显卡信息

```
# 使用 system_profiler 命令查看 GPU 信息
system_profiler SPDisplaysDataType
```

# 调试pipeline

zhch/my_config/PP-StructureV3.yaml中需要所有OCR的参数设定limit_type,limit_side_len

```yaml
        SubModules:
          TextDetection:
            module_name: text_detection
            model_name: PP-OCRv5_server_det
            model_dir: null
            limit_side_len: 2560
            limit_type: max
            max_side_limit: 4000
```

## 问题分析

1. **配置文件中印章识别是关闭的**：

   - 在 `PP-StructureV3.yaml` 中，`use_seal_recognition: False`
   - 这意味着初始化时没有加载印章识别相关的模型
2. **命令行参数冲突**：

   - 您使用了 `--use_seal_recognition True` 参数试图启用印章识别
   - 但由于初始化时没有加载相关模型，导致运行时检查失败
3. **模型检查失败**：

   - 在 `_LayoutParsingPipelineV2.check_model_settings_valid` 方法中检测到模型未初始化
   - 错误消息："Set use_seal_recognition, but the models for seal recognition are not initialized."

## 解决方案

### 方案3：使用专门的印章识别管道

如果您主要需要印章识别功能，可以使用专门的印章识别管道：

````bash
paddlex --pipeline seal_recognition \
    --input sample_data/300674-母公司现金流量表-扫描.png \
    --device gpu:0 \
    --use_doc_orientation_classify False \
    --use_doc_unwarping False
````

## 完整的解决步骤

1. **获取 PP-StructureV3 配置文件**：

   ````bash
   paddlex --get_pipeline_config PP-StructureV3 --save_path ./my_config
   ````
2. **修改配置文件**：

   ````yaml
   # 在 my_config/PP-StructureV3.yaml 中修改：
   use_seal_recognition: True  # 改为 True
   ````
3. **使用修改后的配置文件**：

   ````bash
   paddlex --pipeline ./my_config/PP-StructureV3.yaml \
       --input sample_data/300674-母公司现金流量表-扫描.png \
       --device gpu:0
   ````

## 为什么模型目录存在但无法加载

虽然您在目录中看到了 `PP-OCRv4_server_seal_det` 模型文件，但问题不在于模型文件是否存在，而在于：

1. **管道初始化阶段**：根据配置文件中的 `use_seal_recognition: False`，管道没有初始化印章识别相关的子管道
2. **运行时检查**：当您通过参数设置 `use_seal_recognition=True` 时，系统检查发现相关模型未初始化，因此报错

这是 PaddleX 的设计机制，确保只有在配置文件中明确启用的功能才会被初始化和使用。

# 运行批量识别OmniDocBench数据集

    - 只能单进程，

```bash
cd ~/zhch/PaddleX/zhch
conda activate paddle
# export PADDLE_PDX_MODEL_SOURCE="modelscope"
export PADDLE_PDX_MODEL_SOURCE="bos"

python ppstructurev3_single_process.py

python ppstructurev3_single_process.py --input_file "/home/ubuntu/zhch/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf" --output_dir "./data_PPStructureV3_Results" --pipeline "./my_config/PP-StructureV3.yaml" --device "gpu:0"

# macOS
python ppstructurev3_single_process.py --input_file "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf" --output_dir "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/data_PPStructureV3_Results" --pipeline "./my_config/PP-StructureV3.yaml" --device "cpu"

# 安装服务
paddlex --install serving

# macOS
paddlex --serve --pipeline zhch/PP-StructureV3-zhch.yaml

# linux 10.192.72.11
# 启动ppstructure_v3增强自定义adapter服务
zhch/ppstructure_v3_daemon.sh start

# client
python ppstructurev3_single_client.py --input_file "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf" --output_dir "/Users/zhch158/workspace/data/至远彩色印刷工业有限公司/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

# client 流水分析
python ppstructurev3_single_client.py --input_file "/Users/zhch158/workspace/data/流水分析/A用户_单元格扫描流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/A用户_单元格扫描流水/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

python ppstructurev3_single_client.py --input_file "/Users/zhch158/workspace/data/流水分析/A用户_单元格图片合成.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/A用户_单元格图片合成/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

python ppstructurev3_single_client.py --input_file "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/B用户_扫描流水/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

python ppstructurev3_single_client.py --input_file "/Users/zhch158/workspace/data/流水分析/B用户_图片合成流水.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/B用户_图片合成流水/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

python ppstructurev3_single_client.py --input_file "/Users/zhch158/workspace/data/流水分析/对公_招商银行图.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/对公_招商银行图/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

python ppstructurev3_single_client.py --input_file "//Users/zhch158/workspace/data/流水分析/德_内蒙古银行照.pdf" --output_dir "/Users/zhch158/workspace/data/流水分析/德_内蒙古银行照/data_PPStructureV3_Results" --api_url "http://10.192.72.11:8111/layout-parsing" --timeout 300

```

# process_pdf_batch.sh
```bash
# 方法1: 使用文件列表
chmod +x process_pdf_batch.sh
./process_pdf_batch.sh -f pdf_list.txt

# 方法2: 直接指定 PDF 列表
./process_pdf_batch.sh -p "A用户_单元格扫描流水.pdf,B用户_扫描流水.pdf,对公_招商银行图.pdf,德_内蒙古银行照.pdf"

# 方法3: 处理指定目录下所有 PDF
./process_pdf_batch.sh -d "/Users/zhch158/workspace/data/流水分析"

# 方法4: 完整参数
./process_pdf_batch.sh \
    -s "ppstructurev3_single_client.py" \
    -d "/Users/zhch158/workspace/data/流水分析" \
    -o "data_PPStructureV3_Results" \
    -u "http://10.192.72.11:8111/layout-parsing" \
    -t 600 \
    -f "pdf_list.txt"
```

```bash
# 1. 查看所有处理器
python batch_process_pdf.py --list-processors

# 2. 使用 PPStructureV3 客户端 (默认输出: ppstructurev3_client_results)
python batch_process_pdf.py -p ppstructurev3_single_client -f pdf_list.txt

# 3. 使用 PPStructureV3 本地处理器 (默认输出: ppstructurev3_results)
python batch_process_pdf.py -p ppstructurev3_single_process -f pdf_list.txt

# 4. 使用 PaddleOCR-VL (默认输出: paddleocr_vl_results)
python batch_process_pdf.py -p paddleocr_vl_single_process -f pdf_list.txt

# 5. 覆盖默认输出目录
python batch_process_pdf.py -p ppstructurev3_single_client -f pdf_list.txt -o custom_output

# 6. 模拟运行查看配置
python batch_process_pdf.py -p ppstructurev3_single_client -f pdf_list.txt --dry-run
```