Премини към основното съдържание
Български— Изберете език
Меню

Първото ви OCR обаждане в Python

Урок 5 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. От теория към код
  2. Минималният скрипт
  3. Обработка на файл от вашия компютър
  4. Запазване на извлечените данни
  5. Случаят с изолирано изображение
  6. Реконструиране на илюстриран документ
  7. Ключови изводи

Обновено на 2 ноември 2026 г. — OCR. OCR 4.0 (mistral-ocr-4-0) беше прекратен на 30 септември 2026 г. Използвайте OCR 4.1 (mistral-ocr-4-1), който е общодостъпен от 31 август на същата цена, или псевдонима mistral-ocr-latest, който сочи към него от 16 юли. OCR 4.1 добавя оценки за надеждност на ниво блок. Допълнение от 3 ноември 2026 г.: Локален PDF се предава в base64 като {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; типът document_base64 от по-стари примери не съществува нито в документацията, нито в SDK на mistralai и тези примери биха се провалили. Източници: OCR Processor · Document QnA.

От теория към код

Вече познавате крайната точка и нейните параметри. Време е да напишете пълен скрипт, който извлича текст от PDF файл – от първия ред за импортиране до Markdown файла, запазен на вашия диск. Ще започнем с най-простия случай – публичен документ, след което ще преминем към това, с което ще се сблъскате на практика: локални файлове, изолирани изображения и илюстрирани документи, които изискват реконструкция.

Две предварителни условия, вече разгледани, но заслужаващи проверка, преди да загубите десет минути в грешка при удостоверяване:

pip install mistralai
export MISTRAL_API_KEY="your-api-key"

Минималният скрипт

Ето пълното извличане на PDF, достъпен онлайн. Три полезни реда: създаване на екземпляр на клиента, извикване на process и итерация през страниците.

import os
from mistralai.client import Mistral

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

# OCR call on a public PDF
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://arxiv.org/pdf/2201.04234"
    }
)

# Display the number of pages
print(f"Number of pages: {len(ocr_response.pages)}")

# Display the content of each page
for page in ocr_response.pages:
    print(f"\n--- Page {page.index + 1} ---")
    print(page.markdown)

Обърнете внимание на page.index + 1: индексът, върнат от API, започва от нула, докато вашите потребители броят от едно. Това е малко отместване, стига да го имате предвид, но източник на трайно объркване, когато го откриете в доклад, доставен на клиент.

Обработка на файл от вашия компютър

В реалния живот документите рядко пристигат чрез публичен URL адрес. Вие ги притежавате на диска си, те са поверителни, затова ги кодирате в base64. Следният скрипт обработва фактура от доставчик и конкатенира всички страници в един единствен текстов блок:

import os
import base64
from mistralai.client import Mistral

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

# Read and encode the local file
file_path = "supplier_invoice.pdf"

with open(file_path, "rb") as f:
    document_base64 = base64.b64encode(f.read()).decode("utf-8")

# OCR call
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    }
)

# Concatenate all text
full_text = "\n\n".join(
    page.markdown for page in ocr_response.pages
)

print(full_text)

Конкатенацията чрез "\n\n".join(...) работи добре за дисплей или търсене в пълен текст. Тя обаче изтрива границата между страниците: ако по-късно трябва да цитирате източник или да насочите потребител към правилната страница на договор, запазете структурата страница по страница, вместо този единен блок.

Запазване на извлечените данни

Всяко OCR обаждане струва пари и отнема време. Повторното изпълнение на извличането на същия двеста-страничен доклад, защото сте забравили да запазите резултата, е грешка, която правите само веднъж. Функцията по-долу записва Markdown във файл, маркирайки прекъсванията на страниците с коментар и разделител:

import os
import base64
from mistralai.client import Mistral

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

def extract_pdf(pdf_path: str, output_path: str) -> None:
    """Extracts text from a PDF and saves it as Markdown."""

    with open(pdf_path, "rb") as f:
        document_base64 = base64.b64encode(f.read()).decode("utf-8")

    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        }
    )

    with open(output_path, "w", encoding="utf-8") as f:
        for page in ocr_response.pages:
            f.write(f"<!-- Page {page.index + 1} -->\n\n")
            f.write(page.markdown)
            f.write("\n\n---\n\n")

    print(f"Extraction complete: {len(ocr_response.pages)} pages")
    print(f"Result saved to: {output_path}")


# Usage
extract_pdf("annual_report.pdf", "annual_report.md")

HTML коментарът <!-- Page N --> е невидим в изгледа след рендиране, но остава наличен във файла: можете да го намерите чрез регулярен израз, за да реконструирате номерацията на страниците по време на индексиране.

Случаят с изолирано изображение

OCR 4 не се ограничава само до PDF файлове. Снимка на фактура, направена с телефон, сканирана разписка, екранна снимка – всички се изпращат по същия начин, използвайки типа image_base64:

import os
import base64
from mistralai.client import Mistral

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

# Encode an image
with open("scanned_invoice.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode("utf-8")

# OCR call on an image
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "image_base64",
        "image_base64": image_base64
    }
)

# A single "page" for an image
print(ocr_response.pages[0].markdown)

Отговорът запазва същата форма: списък със страници, който в този случай съдържа само една. Следователно вашият код за обработка остава идентичен, независимо от типа на входния файл, което значително опростява смесените конвейери.

Реконструиране на илюстриран документ

Върнатият Markdown препраща към изображения като ![imageN.jpg](imageN.jpg), без да ги вгражда. Ако искате самостоятелен файл – доклад, четим офлайн, или визуализация за изпращане по имейл – поискайте изображенията в base64 и заменете всяко препращане с data URI:

import os
import base64
import re
from mistralai.client import Mistral

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

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

for page in ocr_response.pages:
    markdown = page.markdown

    # Replace image references with base64
    for image in page.images:
        placeholder = f"![{image.id}]({image.id})"
        data_uri = f"![{image.id}](data:image/jpeg;base64,{image.image_base64})"
        markdown = markdown.replace(placeholder, data_uri)

    print(markdown[:500])

Полученият файл нараства бързо, тъй като base64 тежи около една трета повече от оригиналния двоичен формат. Запазете тази реконструкция за документи, които трябва да направите самостоятелни, и поддържайте изображенията като отделни файлове във вашите конвейери за индексиране.

Преди да продължите, вземете документ, който притежавате – фактура, договор, сканирана страница – и го пуснете през скрипта за локално извличане. Сравнете получения Markdown с оригинала ред по ред: несъответствията, които откриете, лошо реконструирана таблица или заглавие, погълнато от основния текст, са точно проблемите, които следващите три урока ще ви научат да обработвате.

Ключови изводи

  • OCR обаждането отнема 3 реда: клиент, процес, четене на страници
  • Използвайте base64 за локални файлове, URL за публични документи
  • Резултатът е структуриран Markdown, готов за употреба
  • Извлечените изображения могат да бъдат комбинирани отново с текста
  • Винаги запазвайте вашите извличания, за да избегнете повторни API обаждания