OCR API на Mistral
На тази страница
Обновено на 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, за да получавате изображения в base64bbox_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 страници на документ