3步用Mistral OCR 4.1把扫描件、PDF变成结构化文本：带坐标、带置信度，每千页只要3.5欧元

纸质合同、扫描书页、截图里的表格——想把这些变成机器能读的文本，传统 OCR 只能给你一坨没结构的文字。Mistral OCR 4.1 今天登上了 Hacker News 热榜：它在 OCR 基础上增加了段落级边界框（BBox）、结构块标签和块级置信度，输出直接是带版面的结构化结果，还能顺便做文档问答。价格是 3.5 欧元/千页（带标注 4.38 欧元/千页）。

这篇教程带你 3 步跑通：从零开始，把一份 PDF 变成带坐标的 JSON。

前置条件

– Python 3.9+

– 一个 Mistral 平台账号（console.mistral.ai 注册，免费额度够跑通教程）

– 一个可被公网访问的文档 URL（API 直接抓取 URL，本地文件需要先传到对象存储）

第 1 步：安装 SDK 并配置密钥

pip install mistralai

然后配置 API Key（不要写死在代码里，用环境变量）：

export MISTRAL_API_KEY="你的密钥"

第 2 步：写 Python 调用脚本

新建 `ocr_demo.py`：

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.ocr.process(
    model="mistral-ocr-4.1",
    document={
        "type": "document_url",
        "document_url": "https://example.com/your-contract.pdf",
    }
)

for page in response.pages:
    print(f"--- 第 {page.index} 页 ---")
    print(page.markdown[:500])
    # 每个文本块带边界框和置信度
    for block in page.blocks:
        print(block.type, block.bbox, round(block.confidence, 2))

第 3 步：运行并验证

python ocr_demo.py

成功标准：控制台输出每一页的 Markdown 文本，并且每个块都带有 bbox 坐标（例如 `[0.12, 0.30, 0.45, 0.38]`）和 0 到 1 的置信度。

如果只想快速看效果，也可以直接在 Mistral 的 OCR Playground 里拖一份文件，不用写代码。

进阶：把结果存成结构化文件

import json

result = {
    "pages": [
        {
            "index": p.index,
            "markdown": p.markdown,
            "blocks": [
                {"type": b.type, "bbox": b.bbox, "text": getattr(b, "text", "")}
                for b in p.blocks
            ],
        }
        for p in response.pages
    ]
}

with open("ocr_result.json", "w", encoding="utf-8") as f:
    json.dump(result, f, ensure_ascii=False, indent=2)

这样得到的 JSON 可以直接喂给 RAG 系统、知识库或自动化流程。

常见失败与处理

| 问题 | 原因 | 解决 |

|——|——|——|

| 401 认证失败 | 密钥错误或未设置环境变量 | 检查 `echo $MISTRAL_API_KEY`，确认从控制台复制的是 API Key 而非项目 ID |

| 404 抓不到文档 | URL 不可公网访问 | 换用公开链接，或先把文件传到 S3/OSS 再传 URL |

| 大文件超时 | 页数过多 | 拆分成每份 50 页以内分批处理，官方支持批处理接口 |

| 置信度普遍偏低 | 扫描件模糊 | 先做图像增强，或用标注版接口拿到更细的块信息 |

段落级 BBox 到底有什么用

传统 OCR 输出”整页文本”，你还要靠换行和空格猜版面结构；Mistral OCR 4.1 的每个块都带 bbox 坐标（左、上、右、下）和置信度，等于把版面分析也一起做了。实际价值有两个：

1. 还原版面：拿到坐标后可以按原位置重建页面，双栏论文、表格、页眉页脚都不会乱；

2. 质量门禁：置信度低于阈值的块自动标记为”需人工复核”，批量录入时把低置信度条目挑出来单独处理，准确率可控。

下面这个函数演示如何按置信度过滤，只保留高置信度内容：

def keep_confident(blocks, threshold=0.85):
    return [b for b in blocks if getattr(b, "confidence", 1.0) >= threshold]

什么时候用它

– 最合适：发票/合同批量录入、书页数字化、带版面的科研论文抽取、RAG 前处理；

– 不划算：纯文字网页直接抓 HTML 就行，没必要走 OCR；

– 对比：Tesseract 免费但无结构、无置信度；云端通用 OCR 便宜但表格/公式识别弱；Mistral OCR 4.1 的优势是结构感知 + 语言模型级语义理解。

一句话：如果你的工作流里”扫描件转结构化数据”还靠人工，花 10 分钟跑通这个脚本，可能直接省掉一个岗位的重复劳动。

— END —
LC 智趣厅 · 科技与生活的交点
ihygg.cn