Mistral OCR 3：使用 Mistral AI Studio 和 Python 的完整指南

Mistral 最新的 OCR 模型 Mistral OCR 3，能够以极高的保真度从各类文档中提取文本和内嵌图像。

在本文中，我将通过他们的 AI Studio 和 Python API，教您如何充分利用 Mistral OCR 3。我们还会构建一个小应用，把菜单照片变成交互式网站。

如果您想进一步学习如何使用 API 来构建 AI 工具，推荐查看Working with the OpenAI API 课程。

什么是 Mistral OCR？

OCR 是光学字符识别（Optical Character Recognition）的缩写，旨在将文档转换为文本。例如，它可以把一张手写便签的照片转换为文本，或将 PDF 中的表格转换为可搜索和编辑的真实文本表格。

Mistral OCR 3 是 Mistral AI 最新的文档理解模型，在真实世界文档上提供最先进的准确性与效率。它能高保真提取文本与内嵌图像，并通过 Markdown 输出与基于 HTML 的表格重建来保留结构，也可选择输出结构化 JSON。

Mistral OCR 3 在广泛的基准测试中优于所有竞争对手：

与 Mistral OCR 2 相比，它在表单、扫描文档、复杂表格和手写体上实现了 74% 的总体胜率，尤其在低质量扫描和密集布局上有显著提升。

想进一步了解 OCR 及 Mistral 的上一代模型，请查看这篇文章：Mistral OCR：包含实用示例的指南。

在 Mistral AI Studio 中使用 Mistral OCR 3

让我们来看看如何在 AI Studio 中设置并使用 Mistral OCR 3。

账户设置

Mistral OCR 3 可在其 AI Studio中使用。这是最容易上手的方式，因为它提供了友好的用户界面。

注册后，首先会提示我们创建一个组织：

起初，Mistral OCR 3 是锁定的，我们需要选择一个方案来解锁它：

可以选择免费方案，在该方案下，允许他们收集使用数据以改进服务，从而使用 Mistral OCR 3。或者，我们也可以输入信用卡信息并按用量计费。

没有订阅费，但将按每 1,000 页收取 2 美元或 1 美元，具体取决于是否使用批量请求。

解析我们的第一个文档

账户设置完成后，我们可以在 AI Studio 的“Document AI”标签中试用 Mistral OCR 3。

开始时，我们上传要执行 OCR 的文档或图像。我的示例是把一些文字和一个表格写在纸上并拍照上传。我的字迹相当潦草，所以我很好奇 Mistral OCR 3 是否能看懂。

选择文件后，会出现处理方式的选项。在第一个示例中，我保留了默认选项，直接点击右上角的“Run”按钮。

结果如下：

结果相当不错，但并不完美：

• 第一句有两个错误：“homd” 应为 “hand”，以及 “tarnible” 应为 “terrible”。
• 表格整体不错，但未能正确识别列名。表名 “OCR Benchmark Multilingual Chinese” 与 “Result” 列被合并了。
• 它能处理我手动划掉的错误这一点让我印象深刻。不过，如果我要用它来解析笔记，我更希望这些被识别出来并剔除。
• 最后，我用繁体中文写了一句话，它能识别大部分内容。但有一个“好”字被拆成了“女”和“子”，逗号被识别成了字母 “g”，句末也有一个错误。

探索解析选项

Mistral OCR 3 的一项优点是可以指定 JSON 结构来解析数据。这对解析表格尤其有用，因为我们可以指定列名及其数据类型，从而将各行作为 JSON 字典获取。

我们来尝试通过指定 JSON 架构，再次解析上一个示例中的表格。

要提供 JSON 架构，我们需要在运行 OCR 前选择 JSON schema 模式，而不是文本模式。

然后，我们可以通过代码或使用“Visual Builder”界面提供架构。对于手动使用模型的场景，我推荐第二种方式，更为简单。

添加字段时，需要指定：

• 名称
• 描述
• 数据类型
• 是否必填

此处我指定了两个字段：一个是模型名称，另一个是基准结果：

现在我们可以点击“Run”查看结果。不幸的是，这个例子没有成功。结果中只有我提供的架构本身，而非实际数据。

我怀疑也许是我用法不当。为确认，我截取了维基百科上的一个示例表格的截图，再次尝试。

我指定了四列，最后一列设为可选：

这次成功了。似乎在解析失败时，JSON 结果会直接返回所提供的架构。这也意味着，尽管能以文本形式渲染，我的手写表格仍未能按 JSON 解析成功。

使用 Python 调用 Mistral OCR 3

本节我们将探索如何使用 Python 与 Mistral OCR 3 API 交互。这提供了更大的灵活性，例如可以把输出与其他 AI 模型结合以处理提取的数据。

当我们在 AI Studio 上传文件时，“Run” 按钮旁有一个 “Code” 按钮。点击它可以查看若改用 API 执行该操作所需的代码。

示例如下：

不过，所给的 Python 代码并不完全准确。例如，它定义了一个名为 encode_file 的函数，但随后调用的是 encode。这些都是小的不一致之处，但会导致代码无法即取即用。

别担心，我们会详细讲解如何使用 API。要了解更多 API 细节，建议查看官方文档。

API 设置

首先需要在“API Keys”标签中创建一个 API 密钥，并将该密钥复制到与 Python 脚本同一文件夹下名为 .env 的新文件中。

接着安装所需依赖：

pip install mistralai python-dotenv技术支持

对图像执行 OCR

下面这个 Python 脚本会加载本地 JPEG 图像，执行 OCR，并将结果保存为 markdown 文件：

import sys
import base64
import os
from mistralai import Mistral
from dotenv import load_dotenv

# Load the API key from the .env file
load_dotenv()

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

# Load a file as base 64
def encode_file(file_path):
    with open(file_path, "rb") as pdf_file:
        return base64.b64encode(pdf_file.read()).decode('utf-8')

# Perform OCR on and image
def process_image_ocr(file_path):
    base64_file = encode_file(file_path)
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "image_url",
            "image_url": f"data:image/jpeg;base64,{base64_file}" 
        },
        include_image_base64=True
    )
    for index, page in enumerate(ocr_response.pages):
        with open(f"page{index}.md", "wt") as f:
            f.write(page.markdown)

if __name__ == "__main__":
    # Load the input file from the arguments
    file_path = sys.argv[1]
    process_image_ocr(file_path)技术支持

对 PDF 执行 OCR

当输入为 PDF 而非图像时，唯一变化的是 document 字段的取值。对于 JPEG 图像，我们使用：

document={
  "type": "image_url",
   "image_url": f"data:image/jpeg;base64,{base64_file}" 
},技术支持

对于 PDF，我们改用：

document={
  "type": "document_url",
  "document_url": f"data:application/pdf;base64,{base64_file}" 
},技术支持

下面是一个用于处理 PDF 的完整函数：

def process_pdf_ocr(file_path):
    base64_file = encode_file(file_path)
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{base64_file}" 
        },
        include_image_base64=True
    )
    process_pages(ocr_response)技术支持

编写通用版本

为 PDF 和 JPEG 各写一个处理函数有些繁琐，也不是最佳实践，因为两者共享了大量代码。

为避免重复，我们编写了一个改进的通用函数，使用 mimetypes 包来识别所提供文件的类型并相应构建 API 请求。我们还更新了代码以保存文档中识别出的图像。

最终版本如下：

import sys
import os
import base64
import mimetypes
import datauri
from mistralai import Mistral
from dotenv import load_dotenv
# Load the API key from the .env file
load_dotenv()
# Initialize the Mistral client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# List the supported image types
SUPPORTED_IMAGE_TYPES = {
    "image/jpeg",
    "image/png",
    "image/webp",
    "image/tiff",
}
PDF_MIME = "application/pdf"
# Load a file as base 64
def encode_file(file_path: str) -> str:
    with open(file_path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")
# Build the document payload depending on the type of data contained in the file
def build_document_payload(file_path: str) -> dict:
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type:
        raise ValueError(f"Could not determine MIME type for {file_path}")
base64_file = encode_file(file_path)
if mime_type == PDF_MIME:
        return {
            "type": "document_url",
            "document_url": f"data:{mime_type};base64,{base64_file}",
        }
if mime_type in SUPPORTED_IMAGE_TYPES:
        return {
            "type": "image_url",
            "image_url": f"data:{mime_type};base64,{base64_file}",
        }
raise ValueError(f"Unsupported file type: {mime_type}")
# Generic function to process OCR on a file
def process_ocr(file_path: str, output_filename: str = "output.md"):
    document = build_document_payload(file_path)
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document=document,
        include_image_base64=True,
    )
    process_pages(ocr_response, output_filename)
# Save an image to a local file
def save_image(image):
    parsed = datauri.parse(image.image_base64)
    with open(image.id, "wb") as f:
        f.write(parsed.data)
# Process all pages from the OCR response
def process_pages(ocr_response, output_filename: str):
    with open(output_filename, "wt") as f:
        for page in ocr_response.pages:
            f.write(page.markdown)
            for image in page.images:
                save_image(image)
if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python ocr.py <file>")
        sys.exit(1)
process_ocr(sys.argv[1])技术支持

该版本需要使用 datauri 包以保存 Mistral OCR 3 识别出的图像，可通过以下命令安装：

pip install datauri技术支持

提供 JSON 架构

前面我们了解到，Mistral OCR 3 允许提供 JSON 架构来解析数据。在通过 API 使用时也同样支持该功能。

为此，我们需要在发起请求时，将 JSON 架构提供给 document_annotation_format 参数。下面是一个针对两列 model 和 result（对应手写示例表格）的 JSON 架构示例。

document_annotation_format={
    "name": "response_schema",
    "schemaDefinition": {
        "properties": {
            "model": {
                "type": "string",
	         "description": "The name of the model"
             },
             "result": {
	         "type": "number",
	         "description": "The benchmark result"
	     }
         },
         "required": [
             "model"
         ]
    }
}技术支持

结构始终类似。我们需要在 properties 字段下为每一列添加一个条目，包含数据类型信息以及用于帮助模型识别数据的描述。

然后在 required 字段中列出所有必填字段。

要将其与代码配合使用，最简便的方法是把架构存为 JSON 文件，并用 json 包加载。

Mistral OCR 3 项目灵感

使用 API 的一大优势是可以在 Mistral OCR 3 之上构建应用。本节为您提供一些可供扩展的项目想法。

支出追踪应用

我们已经学习了如何对图像执行 OCR。基于此，可以构建一个应用：拍摄购物小票，使用 Mistral OCR 3 处理图像中的数据，并提取一个 JSON 字典，列出小票上的商品及其价格。

随后可将这些支出自动分类并写入数据库，便于用户跟踪消费。

文档语音阅读器

我们可以将 Mistral OCR 3 与文本转语音（TTS）AI 结合，创建文档语音阅读器。用户选择一个文本 PDF，发送至 Mistral OCR 3 处理，然后将结果文本发送给 OpenAI Audio API 或 Eleven Labs 等 TTS 模型。

由于 Mistral OCR 3 也支持图像，它还能处理照片，让用户拍下文档并随时随地收听。

想了解更多文本转语音内容，推荐以下资源：

• OpenAI 的 Audio API：含演示项目的指南
• ElevenLabs API 新手指南：将文本与语音转化为动态音频体验

结语

无论您是在 AI Studio 中试验，还是通过 Python 集成，Mistral OCR 3 都是将现实世界文档转化为可用文本与结构化数据的高效实用工具。

它在扫描页、表单与表格上表现突出，能通过 Markdown 与图像保留布局，并在需要结构化时支持 JSON 架构。不过，正如我们所见，潦草的手写体与含糊的表头仍可能导致问题，而失败的架构解析会直接返回架构本身。

API 在解决小的不一致后相当直接易用。通过通用文件处理器与图像保存功能，也便于集成到小型应用或流程中。若只是试用，Studio 是最快路径；若用于生产，请考虑成本模型，尽量使用批处理，并为边缘情况添加校验。

在此基础上，您可以不断迭代：调优架构、与其他模型联动输出，构建如小票解析器或音频阅读器等专注型工具，让模型承担繁重工作，而您专注于可靠性与体验。