Анотации на партиди
На тази страница
Обновено на 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от по-стари примери не съществува нито в документацията, нито в SDKmistralaiи тези примери биха се провалили. Източници: OCR Processor · Document QnA. Коригирано на 3 ноември 2026 г.: Предишният код четешеpage.document_annotationстраница по страница; в SDKmistralai3.7.0 анотацията на документа е едно поле в отговора (response.document_annotation), а анотацията на изображението се чете отimage.image_annotation.
Мащабиране
Обработката на един документ в даден момент работи добре за прототипиране. В производствена среда реалността е различна: счетоводният отдел получава стотици фактури ежедневно, а адвокатска кантора дигитализира хиляди документи по време на комплексна проверка (due diligence). Кодът трябва да се промени съответно – вече не става въпрос само за получаване на отговор, а за гарантиране, че никой документ няма да се загуби по пътя и че знаете точно кои са се провалили.
Започнете със последователна обработка
Започнете просто. Цикълът по-долу преминава през папка с PDF файлове, кодира всеки файл в base64, изпраща го до OCR двигателя със схемата за анотация и натрупва резултатите. Критичната част се крие в блока try/except: нечетима фактура или неуспешно API обаждане никога не трябва да прекъсват цялата партида. Регистрираме грешката с името на файла и продължаваме, като ви оставяме с окончателен списък, в който всеки запис има статус. Броячът, показван при всяка итерация, не е просто допълнение; когато обработвате триста файла, знанието за напредъка ви предпазва от рестартиране на задача, която вече е наполовина изпълнена.
import os
import json
import time
from pathlib import Path
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 ExtractionFacture(BaseModel):
fournisseur: str = Field(..., description="Supplier name")
numero: str = Field(..., description="Invoice number")
montant_ttc: float = Field(..., description="Total amount including tax")
date: str = Field(..., description="Date (YYYY-MM-DD)")
def traiter_dossier_factures(dossier: str) -> list[dict]:
"""Обработва всички фактури в дадена папка."""
resultats = []
chemin = Path(dossier)
fichiers = list(chemin.glob("*.pdf"))
print(f"Обработка на {len(fichiers)} файла...")
for i, fichier in enumerate(fichiers):
print(f" [{i+1}/{len(fichiers)}] {fichier.name}")
try:
import base64
with open(fichier, "rb") as f:
doc_b64 = base64.b64encode(f.read()).decode("utf-8")
response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
},
document_annotation_format=response_format_from_pydantic_model(
ExtractionFacture
),
table_format="markdown"
)
if response.document_annotation:
facture = ExtractionFacture.model_validate_json(
response.document_annotation
)
resultats.append({
"fichier": fichier.name,
"fournisseur": facture.fournisseur,
"numero": facture.numero,
"montant_ttc": facture.montant_ttc,
"date": facture.date,
"statut": "ok"
})
except Exception as e:
resultats.append({
"fichier": fichier.name,
"statut": "erreur",
"erreur": str(e)
})
return resultats
Паралелизиране без претоварване на API
Последователната обработка прекарва повечето време в чакане на мрежата. Асинхронните обаждания премахват тази загуба, стига да ограничите конкурентността: стартирането на триста заявки едновременно ще предизвика грешки за ограничаване на скоростта (rate-limit) и ще ви остави с недовършена партида. Семафорът asyncio се грижи точно за това – max_concurrent=5 означава максимум пет документа в процес на изпълнение по всяко време, независимо колко файла са на опашка. Индивидуалната функция запазва същата дисциплина като последователната версия: тя улавя изключенията и връща речник със статус, вместо да позволи на gather да се срине.
import os
import asyncio
import base64
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
async def traiter_document(chemin_fichier: Path, schema) -> dict:
"""Обработва документ асинхронно."""
try:
with open(chemin_fichier, "rb") as f:
doc_b64 = base64.b64encode(f.read()).decode("utf-8")
response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
},
document_annotation_format=response_format_from_pydantic_model(
schema
)
)
annotations = []
if response.document_annotation:
annotations.append(response.document_annotation)
return {
"fichier": chemin_fichier.name,
"annotations": annotations,
"statut": "ok"
}
except Exception as e:
return {
"fichier": chemin_fichier.name,
"statut": "erreur",
"erreur": str(e)
}
async def traiter_batch(
dossier: str,
schema,
max_concurrent: int = 5
) -> list[dict]:
"""Обработва папка с контролиран паралелизъм."""
chemin = Path(dossier)
fichiers = list(chemin.glob("*.pdf"))
semaphore = asyncio.Semaphore(max_concurrent)
async def traiter_avec_limite(fichier):
async with semaphore:
return await traiter_document(fichier, schema)
taches = [traiter_avec_limite(f) for f in fichiers]
resultats = await asyncio.gather(*taches)
return list(resultats)
# Execution
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))
Кога обемът оправдава пакетно извеждане (Batch Inference)
Отвъд определен праг въпросът се измества от скорост към цена. Mistral предлага специализирана услуга за пакетно извеждане (Batch Inference), която е по-икономична от индивидуалните обаждания. Подавате JSONL файл, съдържащ една заявка на ред. Полето custom_id – тук името на файла без разширението – ви позволява да свържете всеки отговор обратно с оригиналния документ, когато партидата приключи.
import json
def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
"""Подготвя JSONL файл за пакетна обработка."""
chemin = Path(dossier)
fichiers = list(chemin.glob("*.pdf"))
compte = 0
with open(sortie, "w") as f:
for fichier in fichiers:
with open(fichier, "rb") as pdf:
doc_b64 = base64.b64encode(pdf.read()).decode("utf-8")
requete = {
"custom_id": fichier.stem,
"model": "mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
}
}
f.write(json.dumps(requete) + "\n")
compte += 1
print(f"{compte} заявки подготвени в {sortie}")
return compte
Проследяване на случилото се
Масовата обработка без метрики е черна кутия. Малкият клас данни (dataclass) по-долу брои успехите и грешките, изчислява изминалото време и извежда скорост в документи за секунда. Тази скорост ви показва дали настройката ви за max_concurrent е оптимална, докато списъкът с неуспешните файлове захранва процеса ви за възстановяване при инциденти.
import time
from dataclasses import dataclass, field
@dataclass
class StatsBatch:
total: int = 0
succes: int = 0
erreurs: int = 0
temps_debut: float = field(default_factory=time.time)
fichiers_erreur: list = field(default_factory=list)
@property
def duree(self) -> float:
return time.time() - self.temps_debut
@property
def vitesse(self) -> float:
if self.duree > 0:
return self.succes / self.duree
return 0.0
def rapport(self) -> str:
return (
f"Обработката завърши за {self.duree:.1f}s\n"
f" Успехи: {self.succes}/{self.total}\n"
f" Грешки: {self.erreurs}\n"
f" Скорост: {self.vitesse:.2f} docs/s\n"
f" Неуспешни файлове: {self.fichiers_erreur}"
)
Накрая, експортирайте резултатите от скрипта. CSV отива в електронната таблица на счетоводния отдел, JSON – във вашето приложение; и в двата случая се уверете, че използвате кодиране UTF-8 и ensure_ascii=False, в противен случай вашите знаци с диакритика ще се появят като нечетими последователности за получателя.
import csv
import json
def exporter_csv(resultats: list[dict], chemin: str) -> None:
"""Експортира резултатите в CSV."""
if not resultats:
return
cles = resultats[0].keys()
with open(chemin, "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=cles)
writer.writeheader()
writer.writerows(resultats)
print(f"CSV експорт: {chemin}")
def exporter_json(resultats: list[dict], chemin: str) -> None:
"""Експортира резултатите в JSON."""
with open(chemin, "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"JSON експорт: {chemin}")
Ключови изводи
- Последователната обработка е подходяща за малки обеми с надеждна обработка на грешки
- Паралелната обработка с
asyncioи семафори ускорява работата с големи обеми - Услугата за пакетно извеждане (Batch Inference) на Mistral е най-рентабилното решение за много големи обеми
- Добавете мониторинг и отчети, за да проследявате напредъка и да идентифицирате грешки
- Експортирайте резултатите в CSV или JSON за интеграция с вашите системи