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()
相关推荐
文心快码BaiduComate20 小时前
百度云与光本位签署战略合作：用AI Agent 重构芯片研发流程
前端·人工智能·架构
风象南21 小时前
Claude Code这个隐藏技能，让我告别PPT焦虑
人工智能·后端
Mintopia1 天前
OpenClaw 对软件行业产生的影响
人工智能
陈广亮1 天前
构建具有长期记忆的 AI Agent：从设计模式到生产实践
人工智能
会写代码的柯基犬1 天前
DeepSeek vs Kimi vs Qwen —— AI 生成俄罗斯方块代码效果横评
人工智能·llm
Mintopia1 天前
OpenClaw 是什么？为什么节后热度如此之高？
人工智能
爱可生开源社区1 天前
DBA 的未来？八位行业先锋的年度圆桌讨论
人工智能·dba
叁两1 天前
用opencode打造全自动公众号写作流水线，AI 代笔太香了！
前端·人工智能·agent
前端付豪1 天前
LangChain记忆：通过Memory记住上次的对话细节
人工智能·python·langchain
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03OpenClaw + 飞书（Feishu）环境搭建指南04【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆05Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services06OpenClaw优化飞书API 额度已耗尽问题07Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤08Window 10部署openclaw报错node.exe : npm error code 12809小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）10OpenClaw大龙虾机器人完整安装教程