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

Случаи на използване на анотации

Урок 12 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Анотации за всяка роля
  2. Сортиране преди обработка
  3. Четене на договор като юрист
  4. Автоматична проверка на съответствието
  5. Да не загубите нищо преди индексирането
  6. Ключови изводи

Актуализация от 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. Коригирано на 3 ноември 2026 г.: Предишният код четеше page.document_annotation страница по страница; в mistralai SDK 3.7.0 анотацията на документа е едно поле в отговора (response.document_annotation), а анотацията на изображението се чете от image.image_annotation.

Анотации за всяка роля

Анотациите на Document AI трансформират неструктурираните документи в действащи данни. Механизмът е винаги един и същ – схема, подкана, извикване – но това, което извличате, се променя радикално в зависимост от ролята. Този урок разглежда четири конкретни реализации: класификация в началото на конвейера, анализ на клаузи в договори, проверки за регулаторно съответствие и обогатяване на RAG индекс.

Сортиране преди обработка

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

import os
from enum import Enum
from pydantic import BaseModel, Field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

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

class TypeDocument(str, Enum):
    INVOICE = "facture"
    PURCHASE_ORDER = "bon_commande"
    CONTRACT = "contrat"
    REPORT = "rapport"
    LETTER = "courrier"
    FORM = "formulaire"
    ID_DOCUMENT = "piece_identite"
    OTHER = "autre"

class Classification(BaseModel):
    document_type: TypeDocument = Field(
        ..., description="Identified document type"
    )
    confidence: float = Field(
        ..., description="Confidence score between 0 and 1"
    )
    language: str = Field(
        ..., description="Primary language (ISO 639-1 code)"
    )
    summary: str = Field(
        ..., description="One-sentence summary of the content"
    )

def classify_document(document_base64: str) -> Classification:
    """Automatically classifies a document."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            Classification
        ),
        document_annotation_prompt=(
            "Identify the type of this document and provide "
            "a summary of its content."
        )
    )

    if response.document_annotation:
        return Classification.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Четене на договор като юрист

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

Полето risk заслужава предупреждение: то представлява оценка, генерирана от модел, полезна за приоритизиране на прегледа от юрист, но никога за неговата замяна.

from pydantic import BaseModel, Field
from typing import Optional

class Clause(BaseModel):
    title: str = Field(..., description="Title or number of the clause")
    content: str = Field(..., description="Summary of the clause content")
    clause_type: str = Field(
        ..., description="Type: confidentiality, termination, "
        "non-compete, liability, payment, other"
    )
    risk: str = Field(
        ..., description="Risk level: low, medium, high"
    )

class ContractAnalysis(BaseModel):
    parts: list[str] = Field(
        ..., description="Names of the contracting parts"
    )
    signature_date: Optional[str] = Field(
        None, description="Signature date (YYYY-MM-DD)"
    )
    duration: Optional[str] = Field(
        None, description="Contract duration"
    )
    key_clauses: list[Clause] = Field(
        ..., description="Identified main clauses"
    )
    amount: Optional[float] = Field(
        None, description="Total amount if mentioned"
    )
    jurisdiction: Optional[str] = Field(
        None, description="Applicable jurisdiction"
    )

def analyze_contract(document_base64: str) -> ContractAnalysis:
    """Analyzes a contract and extracts main clauses."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ContractAnalysis
        ),
        document_annotation_prompt=(
            "Analyze this commercial contract. Identify the parts, "
            "the main clauses, and evaluate the risk level "
            "of each clause."
        )
    )

    if response.document_annotation:
        return ContractAnalysis.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Автоматична проверка на съответствието

Регулаторният контрол е особено подходящ за анотации, тъй като критериите са изписани черно на бяло в закона. За френска фактура подканата изброява задълженията за проверка – задължителни споменавания (SIRET, вътреобщностен ДДС, условия за плащане, глоби за забавено плащане), форматиране на сумата, дата на издаване – а схемата налага за всеки критерий булев вердикт, придружен от неговото обосноваване. Вие получавате обща оценка и препоръки за подобрение, което е достатъчно, за да блокирате несъответстваща фактура, преди тя да влезе в платежния цикъл.

from pydantic import BaseModel, Field

class CompliancePoint(BaseModel):
    criterion: str = Field(..., description="Compliance criterion checked")
    compliant: bool = Field(..., description="True if compliant, False otherwise")
    justification: str = Field(
        ..., description="Explanation of compliance or non-compliance"
    )

class ComplianceAudit(BaseModel):
    document_type: str = Field(..., description="Type of document audited")
    compliance_points: list[CompliancePoint] = Field(
        ..., description="Compliance points checked"
    )
    global_score: float = Field(
        ..., description="Global compliance score (0-100)"
    )
    recommendations: list[str] = Field(
        ..., description="Improvement recommendations"
    )

def audit_invoice_compliance(document_base64: str) -> ComplianceAudit:
    """Verifies invoice compliance according to French rules."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ComplianceAudit
        ),
        document_annotation_prompt=(
            "Verify the compliance of this invoice according to "
            "French legal obligations: mandatory mentions "
            "(SIRET, intra-community VAT, payment terms, "
            "late payment penalties), amount formatting, issue date."
        )
    )

    if response.document_annotation:
        return ComplianceAudit.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Да не загубите нищо преди индексирането

Един последен случай на използване, по-скромен, но решаващ: подготовка на съдържание за RAG индекс. Индекс, изграден единствено върху Markdown, губи всичко, което е било визуално, и Вашите търсения никога няма да открият графиката, съдържаща ключовата цифра. Функцията по-долу рекомбинира, страница по страница, текста и описанието на всяко изображение, след което добавя метаданните, извлечени от документа, в един единствен блок, готов за разделяне на части (chunks).

def enrich_for_rag(ocr_response) -> str:
    """Enriches OCR content with annotations for RAG."""
    parts = []

    for page in ocr_response.pages:
        # Text content
        parts.append(page.markdown)

        # Image annotations (replace images with their description)
        for image in page.images:
            if image.image_annotation:
                parts.append(
                    f"[Description of {image.id}]: {image.image_annotation}"
                )

    # Document annotation: a single one, carried by the response
    if ocr_response.document_annotation:
        parts.append(
            f"[Extracted Metadata]: {ocr_response.document_annotation}"
        )

    return "\n\n".join(parts)

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

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

  • Автоматичната класификация пренасочва документите към правилния обработващ конвейер
  • Извличането на клаузи от договори идентифицира рискове и ключови точки
  • Проверката за съответствие автоматизира регулаторните одити
  • Обогатяването чрез анотации подобрява качеството на RAG индексирането
  • Всеки случай на използване се свежда до добре проектирана Pydantic схема и адаптирана подкана