DeepSeek-OCR-2代码实例：Python调用API实现PDF→结构化文本自动提取

1. 什么是DeepSeek-OCR-2？它能帮你解决什么实际问题？

你有没有遇到过这样的情况：手头有一堆扫描版PDF合同、发票、学术论文或产品说明书，想把里面的关键信息——比如公司名称、金额、日期、条款列表、表格数据——快速整理成Excel或数据库可读的格式？传统OCR工具要么识别错别字一堆，要么表格结构全乱，更别说处理多栏排版、手写批注、公式图表混排的复杂文档了。

DeepSeek-OCR-2就是为这类真实痛点而生的。它不是简单地“把图片变文字”，而是真正理解文档的视觉结构和语义逻辑。比如看到一份带页眉页脚、三栏新闻排版、中间插图加说明文字的PDF，它不会傻乎乎从左上角一路扫到右下角，而是先“看懂”哪是标题、哪是正文、哪是表格、哪是图注，再按人类阅读习惯组织输出顺序。

这背后的核心突破，是它采用的DeepEncoder V2动态重排技术——模型会根据图像内容智能决定信息处理路径。就像一个经验丰富的档案员，拿到一份文件先快速浏览布局，再分区域、分优先级地提取重点，而不是机械地逐行扫描。结果就是：一页复杂财报PDF，它只用不到1000个视觉Token就能精准建模，识别准确率在权威测试集OmniDocBench v1.5中达到91.09%，远超多数通用OCR方案。

更重要的是，它输出的不是一整段乱序文字，而是带层级、带结构、带语义标签的文本：标题自动标记为<h1>，表格原样保留行列关系，列表项带<li>，甚至能区分“甲方”“乙方”等法律主体。这意味着你拿到的不是原始OCR结果，而是可直接对接下游系统的结构化数据源。

2. 不只是网页体验：用Python代码调用API，把OCR能力嵌入你的工作流

很多用户第一次接触DeepSeek-OCR-2，是通过它自带的Gradio WebUI界面——上传PDF、点提交、几秒后看到带格式的文本结果，非常直观。但如果你需要批量处理上百份采购订单，或者把它集成进财务报销系统、合同审查平台，靠手动点页面显然不现实。

这时候，它的标准HTTP API接口就成为真正的生产力杠杆。你不需要部署整个WebUI，只需几行Python代码，就能让OCR能力像一个“智能文本提取服务”一样，安静地运行在你的脚本、定时任务或企业后台里。

整个过程清晰简单：

• PDF文件 → 本地读取并编码为base64
• 发送POST请求到API端点，附带文件和参数
• 接收JSON响应，直接解析出结构化文本、标题树、表格数据等字段
• 后续可自由存入数据库、生成Markdown报告、提取关键字段入库

没有复杂的环境配置，不依赖浏览器，不卡在前端加载，真正实现“所见即所得”的自动化。

3. 手把手实操：5分钟写出可运行的PDF结构化提取脚本

3.1 环境准备与依赖安装

我们用最轻量的方式启动——无需conda虚拟环境，只要Python 3.8+和两个基础库：

pip install requests python-magic

• requests：负责发送HTTP请求，调用API
• python-magic：智能识别PDF文件类型（避免因扩展名错误导致API拒绝）

小提示：如果你的PDF是扫描件（图片型PDF），确保文件本身已包含可读图像；如果是纯文本PDF，DeepSeek-OCR-2仍会进行结构分析，但OCR环节会跳过，速度更快。

3.2 核心代码：上传PDF并获取结构化结果

以下是一个完整、可直接复制运行的Python脚本。我们以一份模拟的《软件服务合同》PDF为例，展示如何调用API并解析返回结果：

# deepseek_ocr_api_demo.py
import requests
import base64
import json
import magic

def pdf_to_structured_text(pdf_path: str, api_url: str = "http://localhost:7860/api/predict/"):
    """
    调用DeepSeek-OCR-2 API，将PDF转换为结构化文本
    
    Args:
        pdf_path: 本地PDF文件路径
        api_url: API服务地址（默认为本地Gradio启动地址）
    
    Returns:
        dict: 包含text、markdown、tables、headings等结构化字段的字典
    """
    # 1. 检查文件是否为有效PDF
    mime = magic.Magic(mime=True)
    file_type = mime.from_file(pdf_path)
    if "pdf" not in file_type.lower():
        raise ValueError(f"文件 {pdf_path} 不是有效的PDF格式，检测到类型：{file_type}")
    
    # 2. 读取PDF并编码为base64
    with open(pdf_path, "rb") as f:
        pdf_bytes = f.read()
    pdf_base64 = base64.b64encode(pdf_bytes).decode("utf-8")
    
    # 3. 构造API请求体（Gradio API标准格式）
    payload = {
        "data": [
            pdf_base64,           # 文件base64
            "text",               # 输出格式：text/markdown/json
            True,                 # 是否启用表格识别
            True,                 # 是否启用标题层级分析
            0.5                   # 置信度阈值（0.0~1.0，越高越严格）
        ],
        "event_data": None,
        "fn_index": 0,           # Gradio函数索引，对应webui中第一个按钮
        "trigger_id": 1
    }
    
    # 4. 发送请求
    try:
        response = requests.post(
            api_url,
            json=payload,
            timeout=300  # 给大PDF留足处理时间（5分钟）
        )
        response.raise_for_status()
        
        result = response.json()
        # Gradio返回结构：{"data": ["raw_text", "markdown_text", {...}]}
        if "data" not in result or len(result["data"]) < 3:
            raise ValueError("API返回格式异常，缺少预期字段")
            
        raw_text = result["data"][0] if isinstance(result["data"][0], str) else ""
        markdown_text = result["data"][1] if isinstance(result["data"][1], str) else ""
        structured_data = result["data"][2] if isinstance(result["data"][2], dict) else {}
        
        return {
            "raw_text": raw_text.strip(),
            "markdown": markdown_text.strip(),
            "structured": structured_data,
            "success": True
        }
        
    except requests.exceptions.Timeout:
        return {"error": "请求超时，请检查服务是否运行，或增大timeout参数", "success": False}
    except requests.exceptions.ConnectionError:
        return {"error": "无法连接到OCR服务，请确认 http://localhost:7860 是否已启动", "success": False}
    except Exception as e:
        return {"error": f"调用失败：{str(e)}", "success": False}

# === 使用示例 ===
if __name__ == "__main__":
    # 替换为你自己的PDF路径
    sample_pdf = "./sample_contract.pdf"
    
    print(" 正在调用DeepSeek-OCR-2 API处理PDF...")
    result = pdf_to_structured_text(sample_pdf)
    
    if result["success"]:
        print("\n 提取成功！以下是关键结构信息：")
        print(f"📄 原始文本长度：{len(result['raw_text'])} 字符")
        print(f" 检测到标题数量：{len(result['structured'].get('headings', []))}")
        print(f" 检测到表格数量：{len(result['structured'].get('tables', []))}")
        
        # 打印前3个标题（展示层级结构）
        if result['structured'].get('headings'):
            print("\n 文档标题结构：")
            for i, h in enumerate(result['structured']['headings'][:3]):
                indent = "  " * h.get("level", 0)
                print(f"{indent}• {h.get('text', 'N/A')} (级别 {h.get('level', 0)})")
        
        # 打印第一个表格的前两行（展示结构化能力）
        if result['structured'].get('tables'):
            table = result['structured']['tables'][0]
            print(f"\n 首张表格（{len(table.get('rows', []))} 行 × {len(table.get('headers', []))} 列）：")
            if table.get('headers'):
                print("   表头：", " | ".join(table['headers']))
            for row in table.get('rows', [])[:2]:
                print("   数据：", " | ".join(str(cell) for cell in row))
        
        # 保存Markdown结果（可直接渲染或转HTML）
        with open("output.md", "w", encoding="utf-8") as f:
            f.write(result["markdown"])
        print("\n Markdown格式结果已保存至 output.md")
        
    else:
        print(f"\n 处理失败：{result['error']}")

3.3 运行前必看：服务启动与参数说明

这段代码默认连接 http://localhost:7860/api/predict/ ——这是Gradio WebUI启动后的标准API地址。要让它跑起来，你需要先启动DeepSeek-OCR-2服务：

# 在项目根目录执行（假设已按官方指南克隆并安装）
python app.py --port 7860

你会看到类似这样的日志：

Running on local URL: http://127.0.0.1:7860
API is available at http://127.0.0.1:7860/api/predict/

此时，脚本就能正常通信。如果想改用远程服务器，只需修改 api_url 参数即可。

几个关键参数说明（都在payload里）：

• "text"：输出格式，选 "markdown" 可获得带标题、列表、代码块的富文本；选 "json" 可获得最完整的结构化数据（含坐标、置信度）
• True/False 开关：控制是否启用表格识别、标题分析，关闭可提速，适合纯文字文档
• 0.5：置信度阈值，数值越高，只保留高确定性结果，减少噪声；数值越低，召回率更高，适合模糊扫描件

4. 结构化结果深度解析：不只是文字，更是可编程的数据

DeepSeek-OCR-2返回的structured字段，才是真正体现其“智能”之处。它不是一个扁平字符串，而是一个嵌套的、带语义的JSON对象。我们来拆解一个典型响应：

{
  "headings": [
    {"text": "甲方：北京智算科技有限公司", "level": 1, "page": 1},
    {"text": "第一条 服务内容", "level": 2, "page": 1},
    {"text": "1.1 基础技术服务", "level": 3, "page": 1}
  ],
  "tables": [
    {
      "headers": ["服务项目", "单价（元）", "数量", "小计"],
      "rows": [
        ["AI模型部署支持", 8000, 1, 8000],
        ["月度运维保障", 3000, 12, 36000]
      ],
      "page": 2,
      "bbox": [120, 340, 520, 420]
    }
  ],
  "lists": [
    {
      "type": "numbered",
      "items": [
        "乙方应于合同签订后5个工作日内完成环境搭建。",
        "甲方需提供测试数据集不少于1000条。"
      ]
    }
  ],
  "footnotes": [
    {"text": "注：本合同有效期自2025年3月1日起至2026年2月28日止。", "page": 5}
  ]
}

这个结构意味着：

• 你可以用 for h in data['headings'] if h['level'] == 1: 快速提取所有一级标题，做文档摘要
• 用 pandas.DataFrame(table['rows'], columns=table['headers']) 一行代码把表格转成DataFrame，直接分析
• 用 re.findall(r'甲方：(.+?)，', data['raw_text']) 结合结构化字段定位，精准抽取签约方名称
• 甚至可以基于bbox坐标，在原始PDF上高亮标注识别区域（配合PyMuPDF）

这才是真正的“结构化”——不是OCR完再用正则硬扒，而是模型在识别时就同步构建了语义图谱。

5. 实战技巧与避坑指南：让OCR稳定又高效

5.1 PDF预处理：什么时候该做，怎么做？

DeepSeek-OCR-2对输入质量很友好，但以下两类PDF建议预处理：

PDF类型	问题表现	推荐操作	工具推荐
超大文件（>50MB）	上传慢、内存溢出、超时	拆分单页PDF或压缩图像	pdfimages -list input.pdf 查看图像分辨率；gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook -dNOPAUSE -dQUIET -dBATCH -sOutputFile=output.pdf input.pdf
加密PDF	API直接报错“无法读取”	移除密码（需有权限）	qpdf --decrypt --password=yourpass input.pdf output.pdf

经验之谈：对于扫描件，分辨率保持在200-300 DPI最佳。低于150 DPI文字易粘连；高于400 DPI徒增计算负担，识别提升微乎其微。

5.2 错误排查：常见报错与速查方案

报错信息	最可能原因	30秒解决法
ConnectionError: Failed to establish a new connection	服务未启动或端口不对	运行 curl http://localhost:7860 看是否返回HTML；检查 app.py 启动日志中的port
{'error': 'Invalid base64 string'}	PDF读取失败或编码错误	用 base64 -i sample.pdf | head -c 50 检查前50字符是否为合法base64（含A-Za-z0-9+/=）
{'error': 'No tables detected'}	表格线被抹掉或为图片表格	在payload中将表格开关设为True，并降低置信度阈值至0.3
返回文本为空或极短	PDF是纯矢量文本（非扫描）且未启用文本提取	确认payload中fn_index为0（对应OCR主函数），而非其他预览函数

5.3 性能优化：批量处理不卡顿

单次调用没问题，但处理100份PDF怎么办？别用for循环串行请求——太慢。用concurrent.futures并行：

from concurrent.futures import ThreadPoolExecutor, as_completed

pdf_list = ["a.pdf", "b.pdf", "c.pdf", ...]  # 你的PDF列表

with ThreadPoolExecutor(max_workers=3) as executor:
    # 提交所有任务
    future_to_pdf = {
        executor.submit(pdf_to_structured_text, pdf): pdf 
        for pdf in pdf_list
    }
    
    # 收集结果
    for future in as_completed(future_to_pdf):
        pdf_name = future_to_pdf[future]
        try:
            result = future.result()
            if result["success"]:
                print(f" {pdf_name} 处理完成")
                # 保存结果到独立文件...
            else:
                print(f"  {pdf_name} 失败：{result['error']}")
        except Exception as e:
            print(f"💥 {pdf_name} 异常：{e}")

注意：max_workers=3 是安全值。vLLM推理本身已高度优化，过多并发反而因GPU显存争抢导致整体变慢。实测3~5路并发吞吐最高。

6. 总结：让OCR从“工具”变成你工作流里的“默认能力”

回顾整个过程，你其实只做了三件事：
1⃣ 理解本质：DeepSeek-OCR-2不是OCR引擎，而是“文档理解引擎”——它输出的是带语义的结构，不是冷冰冰的字符流；
2⃣ 掌握接口：用5行核心代码封装API调用，把复杂模型变成一个pdf_to_structured_text()函数；
3⃣ 落地结构：从structured['tables']里直接拿DataFrame，从headings里一键生成目录，从footnotes里提取备注——所有下游开发都变得极其轻量。

这正是AI工程化的价值：不追求炫技，而在于把前沿能力，封装成工程师随手可调、业务方无缝接入的稳定模块。下次当你再收到一邮箱PDF待处理时，不用打开网页、不用复制粘贴、不用忍受格式错乱——只要运行一个脚本，喝杯咖啡的功夫，结构化数据已静静躺在你的CSV或数据库里。

技术的意义，从来不是让人仰望，而是让人忘记它的存在，只专注于真正重要的事。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。