Το API Σχολιασμών (Annotations 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σε κάθε σελίδα· στο SDKmistralai3.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 βοηθά στην επίλυση της αμφιβολίας λέγοντας στο μοντέλο τη φύση του εγγράφου και τι να δώσει προτεραιότητα. Σε μια γαλλική εμπορική σύμβαση, αυτή η προτασιακή πλαισίωση συχνά κάνει τη διαφορά μεταξύ μιας usable εξαγωγής και μιας κατά προσέγγιση συμπλήρωσης.
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καθοδηγεί την εξαγωγή με οδηγίες πλαισίου - Και οι δύο τύποι μπορούν να συνδυαστούν σε μια ενιαία κλήση