如何用 Python 串接 Mistral OCR

這篇教你用 Python 串接 Mistral OCR，完成雲端 PDF、在地檔案與圖片掃描的文字擷取，並把結果保存成可再處理的結構化輸出。

這篇給要把 PDF、掃描檔、收據照片轉成可用文字與版面的開發者看。你照著做完，會得到一組可直接執行的 Python 流程，能處理遠端 PDF、上傳本機檔案、保留 Markdown 結構，還能把圖片一併存下來。

你也會完成 API 金鑰設定、驗證輸出結果，並建立一個可延伸到正式環境的 OCR 範例專案。整篇都是照做型步驟，適合第一次接 Mistral OCR 的人。

開始之前

• Python 3.9+
• pip 23+
• Mistral AI 帳號，先登入 La Plateforme
• Mistral API key
• 可連網，因為這是雲端 OCR
• 可測試的 PDF、JPG 或 PNG 檔案
• Git 版本控制工具，若你要保存範例專案

先把套件裝在獨立虛擬環境，避免和其他專案的依賴衝突。這樣你之後重跑 OCR 範例時，也比較容易重現相同結果。

Step 1: 建立 Python 虛擬環境

目的：先做出乾淨的執行環境，讓 Mistral SDK 可以獨立安裝，不會被其他專案套件干擾。

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install mistralai python-dotenv datauri

驗收：執行 python -c "import mistralai; print('ok')"，你應該看到 ok，代表 SDK 已經安裝成功。

Step 2: 儲存 API 金鑰

目的：把憑證放進環境變數，避免直接寫進程式碼或上傳到版本庫。Mistral OCR 需要先通過驗證，才可以處理文件。

cat > .env <<'EOF'
MISTRAL_API_KEY=your_api_key_here
EOF

cat > .gitignore <<'EOF'
.env
.venv
EOF

驗收：你應該看到 .env 與 .venv 被 Git 忽略，且在 Mistral 控制台中可確認 API key 已啟用。

Step 3: 初始化 OCR 用戶端

目的：讀取環境變數並建立已驗證的客戶端物件，讓腳本具備呼叫 OCR 端點的能力。

from dotenv import load_dotenv
from mistralai import Mistral
import os

load_dotenv()
api_key = os.environ["MISTRAL_API_KEY"]
client = Mistral(api_key=api_key)
print("client-ready")

驗收：執行後你應該看到 client-ready。如果沒有出現，先檢查 .env 是否真的有讀到金鑰。

Step 4: 擷取遠端 PDF 內容

目的：直接對公開 PDF 進行 OCR，快速確認整條流程是否正常，不必先處理檔案上傳。

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2501.00663"
    }
)

print(len(ocr_response.pages))
print(ocr_response.pages[0].markdown[:800])

驗收：你應該看到頁數大於 0，並且前幾段 Markdown 會包含標題、段落或圖表引用，而不是一整坨平面文字。

Step 5: 上傳本機檔案並保存圖片

目的：處理存在你電腦上的 PDF，並把文件中的圖片一併保留下來。這一步適合私人文件、內網文件或不能公開上傳的資料。

from datauri import parse

uploaded = client.files.upload(
    file={"file_name": "report.pdf", "content": open("report.pdf", "rb")},
    purpose="ocr"
)
signed_url = client.files.get_signed_url(file_id=uploaded.id)

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={"type": "document_url", "document_url": signed_url.url},
    include_image_base64=True
)

for page in ocr_response.pages:
    for img in page.images:
        data = parse(img.image_base64)
        with open(img.id, "wb") as f:
            f.write(data.data)

驗收：你應該看到一或多個圖片檔寫入磁碟，例如 img-0.jpeg。同時 Markdown 仍保有內文與圖像位置，代表版面資訊有被保留。

Step 6: 測試掃描圖並檢查品質

目的：對掃描檔或手機拍照圖做 OCR，確認輸出是否保留標題、表格結構與可讀文字。這一步能幫你判斷哪些文件可直接自動化，哪些還需要清理規則。

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "image_url",
        "image_url": "https://example.com/receipt.png"
    }
)

print(ocr_response.pages[0].markdown)

驗收：你應該看到與畫面內容相符的文字，而不是只有零碎字元。若是發票或收據，品項與總金額應該仍然可讀，足以交給後續解析流程。

常見錯誤

• API key 遺失或過期。修法：重新檢查 .env 裡的 MISTRAL_API_KEY，必要時到控制台重新產生金鑰。
• 把本機路徑直接丟進 document_url。修法：先上傳檔案，再使用 client.files.get_signed_url() 回傳的連結。
• 以為 OCR 只會回傳純文字。修法：改成讀取 Markdown 結構與圖片引用，再決定要不要保留標題、表格與圖示。

接下來可以看什麼

當基本 OCR 流程跑通後，下一步可以加入分段切塊、表格欄位抽取與驗證規則，讓文件輸出變成可搜尋知識、可解析發票欄位，或可供檢索的內容。若你要做更大的文件管線，可以再接向量資料庫、Markdown 表格解析器與低信心頁面的人工複核流程。