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

OCR API на Mistral

Урок 4 от 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.

Единна точка за достъп

Цялото извличане на данни от документи преминава през един крайна точка: /v1/ocr, или нейният еквивалент в Python SDK: client.ocr.process(). Независимо дали обработвате снимка на касова бележка или годишен отчет от 800 страници, извикването е едно и също. В този урок ще разгледаме подробно как да го конфигурирате, трите начина за подаване на документ и какво връща той като резултат.

Инсталация и конфигурация

Инсталацията изисква само една команда:

pip install mistralai

След това инициализирайте клиента с Вашия API ключ:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

Този подход работи за бърз тест в бележник (notebook), но крие риск от случайно публикуване на ключа Ви. Веднага щом кодът напусне Вашата машина, използвайте променлива на средата:

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

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

Ще използваме втория вариант във всички следващи уроци.

Параметри на извикването

Извикването client.ocr.process() изисква само два параметъра: model, който винаги трябва да бъде зададен на "mistral-ocr-latest", и document, който описва файла за обработка в една от трите форми, детайлизирани по-долу.

Останалите параметри адаптират изходните данни към Вашите нужди:

  • table_format: Формат на таблиците (null, "markdown", "html")
  • include_image_base64: True, за да получавате изображения в base64
  • bbox_annotation_format: Схема за анотация на ограничаващите кутии (bounding boxes)
  • document_annotation_format: Схема за пълна анотация на документа
  • document_annotation_prompt: Инструкции на високо ниво за анотацията

Първите два параметъра се отнасят до самото OCR и ще ги разгледате в следващите уроци. Последните три са свързани с анотациите, които ще обсъдим започвайки от Урок 9; засега просто запомнете, че те Ви позволяват да заявите структурирано извличане в същото извикване, без нужда от второ връщане към сървъра.

Три начина за изпращане на документ

Първият начин, чрез публичен URL, е най-директен, когато файлът вече е достъпен онлайн – публикуван отчет или прикачен файл, съхраняван в публично хранилище:

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

Вторият начин е необходим за документи, които се намират на Вашата машина или в частно хранилище. Трябва да ги кодирате в base64 и да ги изпратите в тялото на заявката. Това е методът по подразбиране за всичко поверително, тъй като не се налага излагане на URL адрес:

import base64

with open("my_document.pdf", "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}"
    }
)

Третият начин използва Files API. Качвате файла веднъж, получавате неговия ID и след това го използвате в своите извиквания. Предимството се проявява при големи документи или когато един и същи файл трябва да бъде обработван многократно – извличане чрез OCR днес, анотация с различна схема утре: не е необходимо да прехвърляте отново 40 MB при всеки опит.

# Качване на файла
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

# Използване на качения файл
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "file_id",
        "file_id": uploaded_file.id
    }
)

Четене на отговора

Отговорът предоставя списък със страници, като всяка страница съдържа своето съдържание заедно с метаданните си. Един минимален цикъл е достатъчен, за да проверите дали извличането е преминало успешно:

for page in ocr_response.pages:
    print(f"Page {page.index}")
    print(f"Content: {page.markdown[:200]}...")
    print(f"Images: {len(page.images)} found")
    print(f"Header: {page.header}")
    print(f"Footer: {page.footer}")
    print(f"Dimensions: {page.dimensions}")

Направете си навик да стартирате подобен цикъл върху примерен документ, преди да мащабирате процеса до индустриални нива: това ще Ви покаже за три секунди дали броят на страниците съвпада, дали са открити изображения и дали заглавките и долните колонтитули са правилно изолирани от основния текст.

Ограничения и грешки

Три ограничения регулират използването: максимум 50 MB на файл, 1000 страници на документ и входни формати PDF, PNG, JPEG, AVIF, PPTX и DOCX. Върху това се наслагва ограничаване на честотата (rate limiting), с праг, който зависи от Вашия абонаментен план – точка, която трябва да проверите преди масова паралелизация, в противен случай рискувате Вашите извиквания да бъдат отхвърлени при внезапен скок в трафика.

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

from mistralai.client import Mistral
from mistralai.client.errors import SDKError

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

try:
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": "https://example.com/document.pdf"
        }
    )
except SDKError as e:
    print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Разграничаването на двете нива на изключения е полезно: SDKError Ви предоставя статус код, въз основа на който да решите дали да повторите опита – код 429 трябва да бъде повторен след забавяне, докато код 400 – никога, – докато общият блок улавя локални проблеми, като липсващ файл или невъзможно кодиране.

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

  • Крайната точка за OCR е client.ocr.process() с модел mistral-ocr-latest
  • Три метода за изпращане: публичен URL, base64, качен файл
  • Незадължителните параметри контролират формата на таблиците и включването на изображения
  • Отговорът е структуриран страница по страница с Markdown, изображения и метаданни
  • Спазвайте ограниченията от 50 MB и 1000 страници на документ