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

Анотации на партиди

Урок 11 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Мащабиране
  2. Започнете със последователна обработка
  3. Паралелизиране без претоварване на API
  4. Кога обемът оправдава пакетно извеждане (Batch Inference)
  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 страница по страница; в SDK mistralai 3.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 за интеграция с вашите системи