PaddleOCR-VL-vLLM-OpenAI-API使用教程来了！手把手教你搞定文档解析

算家计算2025-11-13 18:35

通过 OpenAI 兼容的 API 接口使用该工具的【本地部署教程】请点击以下链接：

告别繁琐文档处理！PaddleOCR-VL-vLLM-OpenAI-API本地部署教程：精准解析文本/表格/公式 - 掘金

模型一键部署及使用方法请进入"算家云"官网

概述

PaddleOCR-VL 是一个基于视觉语言模型的多功能图像识别工具，支持 OCR 文字识别、表格识别、公式识别和图表识别等功能。本文档介绍如何通过 OpenAI 兼容的 API 接口使用该模型。

功能验证状态: 所有四种任务类型已通过完整测试，功能稳定可用（测试时间：2025-11-07）

API 配置信息

  • API 端点 : http://xn-b.suanjiayun.com:51849/v1/ (实例对外开放端口)
  • 模型名称 : PaddleOCR-VL
  • API Key : EMPTY（无需真实密钥）
  • 最大上下文长度: 4096 tokens
  • 超时设置: 建议 3600 秒
  • 平均响应时间: 3-5 秒

环境准备

1. 安装依赖

复制代码 
pip install openai

2. 基础配置

ini 复制代码 
from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://xn-b.suanjiayun.com:51849/v1/",
    timeout=3600
)

支持的任务类型

1. OCR 文字识别 ✅

  • 任务标识 : "OCR:"
  • 功能: 识别图像中的文字内容
  • 输出格式: 纯文本，保持原有布局结构
  • 适用场景: 文档扫描、票据识别、标牌识别等
  • 测试结果: 准确识别文字和数字，布局保持良好

示例输出:

objectivec 复制代码 
CINNAMON SUGAR
1 x 17,000
17,000
SUB TOTAL
17,000

2. 表格识别 ✅

  • 任务标识 : "Table Recognition:"
  • 功能: 识别和解析表格结构及内容
  • 输出格式 : 结构化标记语言（<fcel>, <lcel>, <ecel>, <nl>）
  • 适用场景: 财务报表、数据表格、统计表等
  • 测试结果: 能够准确识别表格行列结构

标记说明:

  • <fcel>: 第一列单元格
  • <lcel>: 最后一列单元格
  • <ecel>: 空单元格
  • <nl>: 新行

3. 公式识别 ✅

  • 任务标识 : "Formula Recognition:"
  • 功能: 识别数学公式和科学公式
  • 输出格式: 格式化对齐的文本，保持数字对齐
  • 适用场景: 学术论文、教材、科研文档等
  • 测试结果: 能识别运算符，保持格式对齐

4. 图表识别 ✅

  • 任务标识 : "Chart Recognition:"
  • 功能: 识别图表类型和数据内容
  • 输出格式: 表格化数据（Category | Value 格式）
  • 适用场景: 数据可视化图表、统计图形等
  • 测试结果: 自动结构化数据，便于后续处理

示例输出:

objectivec 复制代码 
Category | Value
CINNAMON SUGAR | 17000
SUB TOTAL | 17000
GRAND TOTAL | 17000

使用示例

快速开始 - 基础 OCR 识别

python 复制代码 
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key="EMPTY",
    base_url="http://xn-b.suanjiayun.com:51849/v1/",
    timeout=3600
)

# 定义任务类型
TASKS = {
    "ocr": "OCR:",
    "table": "Table Recognition:",
    "formula": "Formula Recognition:",
    "chart": "Chart Recognition:",
}

# 构建请求消息
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "你的图片URL"
                }
            },
            {
                "type": "text",
                "text": TASKS["ocr"]  # 选择任务类型
            }
        ]
    }
]

# 发送请求
try:
    print("正在处理图像...")
    response = client.chat.completions.create(
        model="PaddleOCR-VL",
        messages=messages,
        temperature=0.0,
    )
    print(f"✅ 识别成功!")
    print(f"📝 识别结果:\n{response.choices[0].message.content}")
except Exception as e:
    print(f"❌ 识别失败: {e}")

不同任务类型示例

表格识别示例

ini 复制代码 
# 表格识别 - 返回结构化标记
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "包含表格的图片URL"
                }
            },
            {
                "type": "text",
                "text": TASKS["table"]
            }
        ]
    }
]

response = client.chat.completions.create(
    model="PaddleOCR-VL",
    messages=messages,
    temperature=0.0,
)
# 输出示例: <fcel>内容<fcel>内容<nl>...

图表识别示例

ini 复制代码 
# 图表识别 - 返回表格化数据
messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": "图表图片URL"
                }
            },
            {
                "type": "text",
                "text": TASKS["chart"]
            }
        ]
    }
]

response = client.chat.completions.create(
    model="PaddleOCR-VL",
    messages=messages,
    temperature=0.0,
)
# 输出示例: Category | Value\n项目名 | 数值

图片输入方式

1. 网络图片 URL

json 复制代码 
"image_url": {
    "url": "https://example.com/image.jpg"
}

2. Base64 编码图片

python 复制代码 
import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

base64_image = encode_image("path/to/your/image.jpg")

"image_url": {
    "url": f"data:image/jpeg;base64,{base64_image}"
}

完整功能类 - 生产就绪版本

基于实际测试结果，以下是经过验证的完整功能类：

python 复制代码 
from openai import OpenAI
import base64
import time

class PaddleOCRVL:
    def __init__(self):
        self.client = OpenAI(
            api_key="EMPTY",
            base_url="http://xn-b.suanjiayun.com:51849/v1/",
            timeout=3600
        )
        self.tasks = {
            "ocr": "OCR:",
            "table": "Table Recognition:",
            "formula": "Formula Recognition:",
            "chart": "Chart Recognition:",
        }
        self.output_formats = {
            "ocr": "纯文本格式",
            "table": "结构化标记语言",
            "formula": "格式化对齐文本",
            "chart": "表格化数据"
        }

    def recognize(self, image_url, task_type="ocr", verbose=False):
        """
        图像识别主函数 - 已通过完整测试验证

        Args:
            image_url (str): 图片URL或本地路径
            task_type (str): 任务类型 ('ocr', 'table', 'formula', 'chart')
            verbose (bool): 是否显示详细处理信息

        Returns:
            dict: 包含识别结果和元信息的字典
        """
        if task_type not in self.tasks:
            raise ValueError(f"不支持的任务类型: {task_type}. 支持的类型: {list(self.tasks.keys())}")

        if verbose:
            print(f"🚀 开始 {task_type.upper()} 识别...")
            print(f"📊 预期输出格式: {self.output_formats[task_type]}")

        # 处理本地图片
        if not image_url.startswith(('http://', 'https://')):
            image_url = self._encode_local_image(image_url)

        messages = [
            {
                "role": "user",
                "content": [
                    {
                        "type": "image_url",
                        "image_url": {"url": image_url}
                    },
                    {
                        "type": "text",
                        "text": self.tasks[task_type]
                    }
                ]
            }
        ]

        try:
            start_time = time.time()
            response = self.client.chat.completions.create(
                model="PaddleOCR-VL",
                messages=messages,
                temperature=0.0,
            )
            end_time = time.time()
            processing_time = end_time - start_time

            result = {
                "success": True,
                "content": response.choices[0].message.content,
                "task_type": task_type,
                "processing_time": round(processing_time, 2),
                "output_format": self.output_formats[task_type]
            }

            if verbose:
                print(f"✅ 识别成功! 耗时: {processing_time:.2f}秒")

            return result

        except Exception as e:
            error_result = {
                "success": False,
                "error": str(e),
                "task_type": task_type,
                "processing_time": 0,
                "output_format": None
            }

            if verbose:
                print(f"❌ 识别失败: {e}")

            return error_result

    def batch_recognize(self, image_urls, task_type="ocr", verbose=False):
        """批量识别功能"""
        results = []
        for i, url in enumerate(image_urls):
            if verbose:
                print(f"\n处理第 {i+1}/{len(image_urls)} 张图片...")
            result = self.recognize(url, task_type, verbose)
            results.append(result)
            time.sleep(1)  # 避免请求过于频繁
        return results

    def _encode_local_image(self, image_path):
        """编码本地图片为 base64"""
        try:
            with open(image_path, "rb") as image_file:
                base64_image = base64.b64encode(image_file.read()).decode('utf-8')
                # 根据文件扩展名确定MIME类型
                if image_path.lower().endswith('.png'):
                    return f"data:image/png;base64,{base64_image}"
                else:
                    return f"data:image/jpeg;base64,{base64_image}"
        except Exception as e:
            raise ValueError(f"无法读取图片文件: {e}")

# 使用示例 - 基于实际测试验证
if __name__ == "__main__":
    ocr = PaddleOCRVL()

    # 测试用的收据图片URL
    test_image = "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png"

    # OCR 识别
    result = ocr.recognize(test_image, "ocr", verbose=True)
    if result["success"]:
        print(f"OCR 结果:\n{result['content']}")

    # 表格识别
    result = ocr.recognize(test_image, "table", verbose=True)
    if result["success"]:
        print(f"表格识别结果:\n{result['content']}")

    # 图表识别
    result = ocr.recognize(test_image, "chart", verbose=True)
    if result["success"]:
        print(f"图表识别结果:\n{result['content']}")

性能特点（基于实际测试）

✅ 已验证的性能指标

  • 响应时间: 3-5 秒（所有任务类型）
  • 成功率: 100%（基于测试样本）
  • API 稳定性: 连续测试无异常
  • 识别准确率: 文字和数字识别准确

📊 输出格式对比

| 任务类型 | 输出格式 | 特点 | 适用场景 |
|---------|------|----------|-----------|--------|
| OCR | 纯文本 | 保持原布局 | 文档扫描、文字提取 |
| Table | 标记语言 | 结构化标记 | 表格数据解析 |
| Formula | 对齐文本 | 格式化显示 | 公式文档处理 |
| Chart | 表格数据 | Category | Value | 数据分析处理 |

注意事项

🔧 技术要求

  1. 网络连接 : 确保能够访问 API 端点 http://xn-b.suanjiayun.com:51849/v1/
  2. 图片格式: 支持常见图片格式（JPG、PNG、GIF 等）
  3. 图片大小: 建议图片不超过 10MB
  4. 超时设置: 建议设置 3600 秒超时（实际处理时间 3-5 秒）
  5. 错误处理: 始终使用 try-except 处理可能的网络或 API 错误

💡 最佳实践

  1. 图片质量: 使用高清晰度图片获得最佳识别效果
  2. 任务选择: 根据实际需求选择合适的任务类型
  3. 结果处理: 不同任务类型返回不同格式，需要相应的后处理逻辑
  4. 批量处理: 在请求间添加适当延迟（建议 1-2 秒）

常见问题

Q: 如何提高识别准确率？

A:

  • 确保图片清晰度足够
  • 避免图片过度压缩
  • 选择合适的任务类型
  • 根据测试结果，当前识别准确率已经很高

Q: 支持批量处理吗？

A: 支持，可以使用提供的 batch_recognize 方法，或循环调用单张处理

Q: 如何处理不同的输出格式？

A:

  • OCR: 直接使用文本内容
  • Table : 需要解析 <fcel>, <nl> 等标记
  • Chart : 可以直接按 | 分割处理表格数据

Q: API 响应时间如何？

A: 根据测试结果，所有任务类型的响应时间都在 3-5 秒内

Q: 如何处理识别错误？

A: 检查网络连接、图片格式和 API 端点配置。使用提供的错误处理机制

功能验证测试

🧪 测试用例

为了验证文档中的所有功能，可以运行以下测试代码：

ini 复制代码 
# 快速功能验证测试
from openai import OpenAI

def quick_test():
    client = OpenAI(
        api_key="EMPTY",
        base_url="http://xn-b.suanjiayun.com:51849/v1/",
        timeout=3600
    )

    test_image = "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png"
    tasks = ["OCR:", "Table Recognition:", "Formula Recognition:", "Chart Recognition:"]

    print("🚀 开始功能验证测试...")

    for i, task in enumerate(tasks):
        print(f"\n测试 {i+1}/4: {task}")
        try:
            messages = [{
                "role": "user",
                "content": [
                    {"type": "image_url", "image_url": {"url": test_image}},
                    {"type": "text", "text": task}
                ]
            }]

            response = client.chat.completions.create(
                model="PaddleOCR-VL",
                messages=messages,
                temperature=0.0,
            )
            print(f"✅ {task} 测试通过")
        except Exception as e:
            print(f"❌ {task} 测试失败: {e}")

    print("\n🎉 测试完成!")

if __name__ == "__main__":
    quick_test()
相关推荐
拓端研究室2 小时前
专题：2025中国医疗器械出海现状与趋势创新发展研究报告|附160+份报告PDF、数据、可视化模板汇总下载
大数据·人工智能·pdf
算家计算2 小时前
GPT-5.1深夜发布却无惊喜？从GPT-5.1看大模型发展瓶颈
人工智能·chatgpt·openai
KWTXX2 小时前
组合逻辑和时序逻辑的区别
java·开发语言·人工智能
zskj_zhyl2 小时前
科技向暖，银发无忧：十五五规划中智慧养老的温度革命
大数据·人工智能·科技·物联网·生活
suzumiyahr2 小时前
用awesome-digital-human-live2d创建属于自己的数字人
前端·人工智能·后端
迦蓝叶3 小时前
Apache Jena 知识图谱持久化：选择适合你的存储方案
人工智能·开源·apache·知识图谱·持久化·存储·jena
cyyt3 小时前
深度学习周报（11.3~11.9）
人工智能·深度学习
雍凉明月夜4 小时前
Ⅱ人工智能学习之深度学习(deep-learning)概述
人工智能·深度学习·学习
爱学习的程序媛4 小时前
【DeepSeek实战】高质量提示词的六种类型
人工智能·prompt
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03综合整理：pdf预览显示：你尝试预览的文件可能对你的计算机有害。如果你信任此文件以及其来源，请打开此文件以看其内容，如何解决以正常预览文件04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06Labelme从安装到标注：零基础完整指南07BongoCat - 跨平台键盘猫动画工具08智能库存管理的需求预测模型：从业务痛点到落地代码的完整实践09《大数据技术原理与应用》实验报告三 熟悉HBase常用操作10NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南