PaddleOCR-VL-half-GGUF-pured

项目概览

本项目是 PaddleOCR-VL GGUF 的提纯版本，基于之前的 PaddleOCR-VL-half-GGUF 项目中的两阶段拆分策略。该策略将多模态模型拆分成「视觉编码器 + 语言模型」两部分，视觉侧保持 PyTorch，语言侧使用 GGUF 量化后通过 llama.cpp 系列工具直接加载。

相比原项目，本版本内容更加纯净，移除了冗余文件和复杂转换步骤，直接提供提纯后的模型文件和演示代码，便于快速部署和使用。

• 🎯 目标: 在消费级硬件上以最小的内存占用和延迟运行 PaddleOCR-VL
• 🧠 视觉侧: SiglipVisionModel + Projector (原生精度)
• 🗣️ 语言侧: Ernie4.5 → GGUF 量化 → llama-cpp-python 推理
• 🔌 接口: 兼容 OpenAI Chat Completions API
• 🧰 用途: 图片 OCR + 对话、文档理解等多模态任务

关键特性

能力	说明
推理速度	CPU 环境下可获得 2-5x 提升
架构解耦	视觉模块仍在 PyTorch 中运行,便于调试与扩展
API 兼容	保持与 OpenAI 风格接口一致,可无缝集成现有应用
本地化	全流程离线部署,无外部服务依赖
内存优化	使用微缩版视觉模型,节省约 7GB 内存

项目结构

PaddleOCR-VL-half-GGUF-pured/
├── demo_ppocrvl_gguf_server.py   # llama.cpp 后端服务器 (核心)
├── demo_ppocrvl_gguf_client.py    # 命令行客户端示例
├── requirements.txt               # 运行所需的 Python 依赖
├── README.md                      # 本文档
├── readme_example.md              # 详细示例和转换说明
├── gguf_model/                    # 转换后的 GGUF 模型文件
│   ├── llm_model.gguf             # FP16 精度 GGUF 模型
│   ├── llm_model_q4.gguf          # Q4 量化 GGUF 模型
│   └── llm_model_q8.gguf          # Q8 量化 GGUF 模型
└── vision_model/                  # 微缩版视觉模型文件
    ├── added_tokens.json
    ├── chat_template.jinja
    ├── image_processing.py
    ├── model_info.json
    ├── preprocessor_config.json
    ├── processing_paddleocr_vl.py
    ├── processor_config.json
    ├── special_tokens_map.json
    ├── tokenizer_config.json
    ├── tokenizer.json
    ├── tokenizer.model
    └── vision_model.pt

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动服务

# 启动多模态服务
python demo_ppocrvl_gguf_server.py

3. 测试客户端

# 在另一个终端中运行客户端测试
python demo_ppocrvl_gguf_client.py

API 调用示例

import requests

# 示例：发送包含图像的 OCR 请求
payload = {
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "OCR:"},
                {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
            ]
        }
    ]
}

response = requests.post("http://localhost:8000/v1/chat/completions", json=payload)
print(response.json())

配置参数

在 demo_ppocrvl_gguf_server.py 中可以调整以下参数：

VISION_MODEL_PATH = "vision_model"  # 视觉模型路径
GGUF_MODEL_PATH = "gguf_model/llm_model_q4.gguf"  # GGUF 模型路径
N_GPU_LAYERS = 0     # GPU 层数 (0=纯 CPU)
N_CTX = 4096         # 上下文窗口
N_THREADS = 8        # CPU 线程数

量化模型说明

项目提供三种量化等级的 GGUF 模型：

• llm_model.gguf: FP16 精度，质量最高，内存占用最大
• llm_model_q8.gguf: Q8 量化，平衡质量和内存
• llm_model_q4.gguf: Q4 量化，内存最小，推荐用于 CPU 推理

根据硬件条件选择合适的模型文件。

注意事项

• 本项目基于两阶段拆分策略，确保视觉和语言模型的解耦运行
• 相比原项目，去除了转换脚本和中间文件，提供即用型模型
• 更多信息参考 https://github.com/Liyulingyue/CreativeProjects/tree/main/PaddleOCR-VL-GGUF

许可证

本项目采用 Apache 2.0 许可证。