API за анотации
На тази страница
Обновено на 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 ноември: Предишният пример четешеpage.document_annotationна всяка страница; в SDKmistralaiверсия 3.7.0 това поле принадлежи към OCR отговора (ocr_response.document_annotation), докато страниците съдържат само своето съдържание и изображения; анотациите на изображенията се четат отimage.image_annotation.
Отвъд извличането на текст
OCR Ви предоставя суров текст: верен и пълен, но недиференциран. Получавате Markdown, а не данни. Анотациите правят следващата стъпка: те извличат структурирани данни от Вашите документи въз основа на схема, която дефинирате предварително. Вие описвате какво търсите, моделът го извлича автоматично и Вашето приложение получава типизирани полета вместо стена от текст, която да парсвате с регулярни изрази.
Две нива на анализ
Document AI прави разлика между два типа анотации в зависимост от мащаба, в който оперират.
Анотациите с ограничителна кутия (bbox_annotation) се фокусират върху изображенията и графиките, които OCR е изолирал. Моделът за компютърно зрение обработва всяка ограничителна кутия поотделно, за да опише съдържанието ѝ. В един годишен отчет този механизъм Ви позволява да описвате диаграми и схеми, да класифицирате изображения (снимка, лого, схема, графика) и да извличате текстово съдържание от вградени изображения – три части информация, които стандартното извличане на текст системно пропуска.
Анотациите на документи (document_annotation) третират файла като цяло. Моделът анализира извлечения Markdown заедно с първите осем изображения, след което връща това, което сте поискали: структурирани полета като име, дата или сума; типа на документа; обобщение на съдържанието; или отговор на конкретен въпрос. Това е инструментът за масова обработка, този, който ще интегрирате във Вашите работни потоци за фактури, формуляри и договори.
Pydantic схемата действа като договор
Анотациите разчитат на Pydantic модели, за да дефинират изходната структура. Всеки атрибут се превръща в поле за извличане, а неговото description служи като инструкция за модела: то носи толкова тежест, колкото и самото име на полето.
from pydantic import BaseModel, Field
from typing import Optional
class InvoiceExtraction(BaseModel):
vendor: str = Field(..., description="Vendor name")
invoice_number: str = Field(..., description="Invoice number")
issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
amount_excl_tax: float = Field(..., description="Amount excluding tax")
amount_incl_tax: float = Field(..., description="Amount including tax")
currency: str = Field(default="EUR", description="Currency (ISO code)")
Анотиране на цял документ
Извикването остава същото като при OCR: просто добавяте параметъра document_annotation_format, попълнен чрез response_format_from_pydantic_model(), който превежда Вашия модел в схема, която API може да използва. При връщане анотацията идва като JSON низ, който ревалидирате с Pydantic, за да получите безопасен Python обект.
import os
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
class InvoiceExtraction(BaseModel):
vendor: str = Field(..., description="Vendor name")
invoice_number: str = Field(..., description="Invoice number")
issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
amount_excl_tax: float = Field(..., description="Amount excluding tax")
amount_incl_tax: float = Field(..., description="Amount including tax")
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
},
document_annotation_format=response_format_from_pydantic_model(
InvoiceExtraction
)
)
# Анотацията на документа се носи от отговора, а не от всяка страница
if ocr_response.document_annotation:
invoice = InvoiceExtraction.model_validate_json(
ocr_response.document_annotation
)
print(f"Vendor: {invoice.vendor}")
print(f"Amount incl. tax: {invoice.amount_incl_tax}")
Описване на визуални елементи един по един
При изображенията принципът е идентичен, но параметърът се променя, а резултатите се четат от page.images, а не от самата страница. Обърнете внимание на include_image_base64=True: без него губите визуалните елементи, които моделът току-що е описал.
from pydantic import BaseModel, Field
from mistralai.extra import response_format_from_pydantic_model
class ImageDescription(BaseModel):
image_type: str = Field(
..., description="Type: graph, table, photo, logo, schematic"
)
description: str = Field(
..., description="Short description of the image in English"
)
relevant_content: str = Field(
..., description="Summary of the informative content of the image"
)
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
bbox_annotation_format=response_format_from_pydantic_model(
ImageDescription
),
include_image_base64=True
)
# Достъп до анотациите на изображенията
for page in ocr_response.pages:
for image in page.images:
if image.image_annotation:
desc = ImageDescription.model_validate_json(image.image_annotation)
print(f"Image {image.id}: {desc.image_type}")
print(f" Description: {desc.description}")
Нищо не Ви принуждава да избирате между двете: при илюстриран отчет обикновено ще искате както метаданните на документа, така и описанието на неговите диаграми, което едно единствено извикване покрива чрез предаване на двата формата.
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
bbox_annotation_format=response_format_from_pydantic_model(
ImageDescription
),
document_annotation_format=response_format_from_pydantic_model(
InvoiceExtraction
),
include_image_base64=True
)
Насочване на извличането чрез подкана (Prompt)
Схемата описва очакваната форма, а не контекста на документа. Когато Вашите полета са двусмислени – множество дати, множество суми, два подобни раздела – document_annotation_prompt помага за разрешаване на съмнението, като казва на модела естеството на документа и какво да приоритизира. При френски търговски договор това рамкиращо изречение често прави разликата между използваемо извличане и приблизително попълване.
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/contract.pdf"
},
document_annotation_format=response_format_from_pydantic_model(
ContractExtraction
),
document_annotation_prompt=(
"This document is a French commercial contract. "
"Extract information about the contracting parties, "
"the contract duration, and the main clauses."
)
)
Ключови изводи
- Два типа анотации:
bbox_annotationза изображения,document_annotationза целия документ - Pydantic схемите дефинират структурата на данните за извличане
- Използвайте
response_format_from_pydantic_model(), за да конвертирате схемата document_annotation_promptнасочва извличането с контекстуални инструкции- И двата типа могат да бъдат комбинирани в едно единствено извикване