Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-API tal-Annotazzjonijiet

Lezzjoni 9 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Aktar mill-Estrazzjoni tat-Test
  2. Żewġ Livelli ta’ Analiżi
  3. L-Iskema Pydantic Taġixxi bħala l-Kuntratt
  4. L-Annotazzjoni ta’ Dokument Sħiħ
  5. Id-Deskrizzjoni tal-Viżwali Waħda waħda
  6. Gwida tal-Estrazzjoni b’Prompt
  7. Punti Ewlenin

Aġġornat fit-2 ta’ Novembru, 2026 — OCR. L-OCR 4.0 (mistral-ocr-4-0) ġie rtirat fit-30 ta’ Settembru, 2026. Uża l-OCR 4.1 (mistral-ocr-4-1), li ilu disponibbli ġeneralment mill-31 ta’ Awwissu bl-istess prezz, jew l-alias mistral-ocr-latest, li jipponta lejh mis-16 ta’ Lulju. L-OCR 4.1 iżid punteġġi ta’ kunfidenza fil-livell tal-blokki. Addendum mit-3 ta’ Novembru: L-eżempju preċedenti kien jaqra page.document_annotation fuq kull paġna; fl-SDK mistralai 3.7.0, dan il-qasam jappartjeni għar-rispons tal-OCR (ocr_response.document_annotation), filwaqt li l-paġni fihom biss il-kontenut u l-immaġnijiet tagħhom; l-annotazzjonijiet tal-immaġni jinqraw minn image.image_annotation.

Aktar mill-Estrazzjoni tat-Test

L-OCR jagħtitek test raw: fidil u sħiħ, iżda mingħajr differenzazzjoni. Tikseb Markdown, mhux dejta. L-annotazzjonijiet jieħdu l-pass li jmiss: jestrattu dejta strutturata mid-dokumenti tiegħek ibbażata fuq skema li tiddefinixxi minn qabel. Tiddeskrivi x’inhu qed tfittex, il-mudell jestrah awtomatikament, u l-applikazzjoni tiegħek tirċievi oqsma ttajpjjati minflok ħajt ta’ test li trid tanalizza b’espressjonijiet regolari.

Żewġ Livelli ta’ Analiżi

Id-Document AI jiddistingwi bejn żewġ tipi ta’ annotazzjonijiet ibbażati fuq l-iskala li fuqha joperaw.

L-annotazzjonijiet tal-kaxxa tal-limitu (bbox_annotation) jiffukaw fuq l-immaġnijiet u l-grafika li l-OCR iżola. Il-mudell tal-viżjoni jipproċessa kull kaxxa tal-limitu individwalment biex jiddeskrivi l-kontenut tagħha. F’rapport annwali, dan il-mekkaniżmu jħallik tiddeskrivi grafiċi u dijagrammi, tikklassifika immaġnijiet (ritratt, logo, skematiku, grafu), u testratti kontenut testwali minn immaġnijiet inkorporati—tliet biċċiet ta’ informazzjoni li l-estrazzjoni standard tat-test titlifha sistematikament.

L-annotazzjonijiet tad-dokument (document_annotation) jittrattaw il-fajl bħala totalità. Il-mudell janalizza l-Markdown estratt flimkien mal-ewwel tmien immaġnijiet, imbagħad jirritorna dak li tlift: oqsma strutturati bħal isem, data, jew ammont; it-tip tad-dokument; sommarju tal-kontenut; jew tweġiba għal mistoqsija speċifika. Dan huwa l-għodda għall-ipproċessar bil-kwantità, dik li se tikkonnettja mal-flussi tax-xogħol tal-fatturi, il-formoli u l-kuntratti tiegħek.

L-Iskema Pydantic Taġixxi bħala l-Kuntratt

L-annotazzjonijiet jiddependu fuq mudelli Pydantic biex jiddefinixxu l-istruttura tal-output. Kull attribut isir qasam li għandu jiġi estratt, u d-description tiegħu sservi bħala istruzzjoni għall-mudell: iġorr daqsxejn l-istess piż bħall-isem tal-qasam innifsu.

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)")

L-Annotazzjoni ta’ Dokument Sħiħ

Is-sejħa tibqa’ l-istess bħall-OCR: sempliċiment iżżid il-parametru document_annotation_format, mimli minn response_format_from_pydantic_model(), li jittrasforma l-mudell tiegħek f’iskema li l-API tista’ tuża. Fir-ritorn, l-annotazzjoni tasal bħala stringa JSON, li terġa’ tivvalida ma’ Pydantic biex tikseb oġġett Python sikur.

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
    )
)

# L-annotazzjoni tad-dokument tinġarr mir-rispons, mhux minn kull paġna
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}")

Id-Deskrizzjoni tal-Viżwali Waħda waħda

Għall-immaġnijiet, il-prinċipju huwa identiku iżda l-parametru jinbidel, u r-riżultati jinqraw minn page.images minflok mill-paġna nnifisha. Innota include_image_base64=True: mingħajru, titlef il-viżwali li l-mudell għadu kemm iddeskriva.

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
)

# Aċċess għall-annotazzjonijiet tal-immaġni
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}")

Xejn ma jfurzak tagħżel bejn iż-żewġ: fuq rapport illustrat, ġeneralment se tkun trid kemm il-metadejta tad-dokument kif ukoll id-deskrizzjoni tal-grafiki tiegħu, li sejħa waħda tkopri billi tgħaddi ż-żewġ formati.

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
)

Gwida tal-Estrazzjoni b’Prompt

Skema tiddeskrivi l-forma mistennija, mhux il-kuntest tad-dokument. Meta l-oqsma tiegħek ikunu ambigwi—diversi dati, diversi ammonti, żewġ taqsimiet simili—document_annotation_prompt jgħin biex issolvi d-dubju billi jgħid lill-mudell in-natura tad-dokument u x’għandu jipprivileġġja. Fuq kuntratt kummerċjali Franċiż, din is-sentenza ta’ qafas spiss tagħmel id-differenza bejn estrazzjoni użabbli u mimli approssimattiv.

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."
    )
)

Punti Ewlenin

  • Żewġ tipi ta’ annotazzjonijiet: bbox_annotation għall-immaġnijiet, document_annotation għad-dokument kollu
  • L-iskemi Pydantic jiddefinixxu l-istruttura tad-dejta li għandha tiġi estratta
  • Uża response_format_from_pydantic_model() biex tikkonverti l-iskema
  • Il-document_annotation_prompt jiggwida l-estrazzjoni b’istruzzjonijiet kuntestwali
  • Iż-żewġ tipi jistgħu jiġu kkombinati f’sejħa waħda