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

API за анотации

Урок 9 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Отвъд извличането на текст
  2. Две нива на анализ
  3. Pydantic схемата действа като договор
  4. Анотиране на цял документ
  5. Описване на визуални елементи един по един
  6. Насочване на извличането чрез подкана (Prompt)
  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 ноември: Предишният пример четеше page.document_annotation на всяка страница; в SDK mistralai версия 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 насочва извличането с контекстуални инструкции
  • И двата типа могат да бъдат комбинирани в едно единствено извикване