Przejdź do głównej treści
Polski— Wybierz język
Menu

Anotacje wsadowe

Lekcja 11 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Skalowanie procesu
  2. Zacznij od przetwarzania sekwencyjnego
  3. Równoległość bez przeciążania API
  4. Kiedy duża objętość uzasadnia wnioskowanie wsadowe
  5. Śledzenie tego, co się wydarzyło
  6. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 r. — OCR. Model OCR 4.0 (mistral-ocr-4-0) został wycofany 30 września 2026 r. Używaj OCR 4.1 (mistral-ocr-4-1), ogólnie dostępnego od 31 sierpnia w tej samej cenie, lub aliasu mistral-ocr-latest, który wskazuje na niego od 16 lipca. OCR 4.1 dodaje wyniki pewności na poziomie bloku. Dodatkowa informacja z 3 listopada 2026 r.: Lokalny plik PDF jest przesyłany w formacie base64 jako {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; typ document_base64 ze starszych przykładów nie istnieje ani w dokumentacji, ani w SDK mistralai, a takie przykłady zakończyłyby się niepowodzeniem. Źródła: OCR Processor · Document QnA. Skorygowano 3 listopada 2026 r.: Poprzedni kod odczytywał page.document_annotation strona po stronie; w SDK mistralai w wersji 3.7.0 adnotacja dokumentu jest pojedynczym polem w odpowiedzi (response.document_annotation), a adnotację obrazu odczytuje się z image.image_annotation.

Skalowanie procesu

Przetwarzanie jednego dokumentu na raz sprawdza się podczas tworzenia prototypów. W środowisku produkcyjnym rzeczywistość wygląda inaczej: dział księgowości otrzymuje setki faktur dziennie, a kancelaria prawna digitalizuje tysiące dokumentów w ramach due diligence. Kod musi zostać odpowiednio dostosowany – nie chodzi już tylko o uzyskanie odpowiedzi, ale o zapewnienie, że żaden dokument nie zaginie po drodze i że dokładnie wiesz, które z nich nie zostały przetworzone poprawnie.

Zacznij od przetwarzania sekwencyjnego

Na początku zachowaj prostotę. Poniższa pętla iteruje po folderze z plikami PDF, koduje każdy plik w formacie base64, wysyła go do silnika OCR ze schematem adnotacji i gromadzi wyniki. Kluczowym elementem jest blok try/except: nieczytelna faktura lub nieudane wywołanie API nigdy nie mogą przerwać całego wsadu. Rejestrujemy błąd wraz z nazwą pliku i kontynuujemy działanie, dzięki czemu na końcu otrzymujesz listę, w której każdy wpis posiada pole status. Licznik wyświetlany w każdej iteracji to nie tylko miły dodatek; przy przetwarzaniu trzystu plików wiedza o postępie pracy uchroni Cię przed restartowaniem zadania, które jest już w połowie wykonane.

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]:
    """Przetwarza wszystkie faktury w folderze."""
    resultats = []
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    print(f"Przetwarzanie {len(fichiers)} plików...")

    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

Równoległość bez przeciążania API

Przetwarzanie sekwencyjne spędza większość czasu na oczekiwaniu na odpowiedź sieciową. Wywołania asynchroniczne eliminują tę stratę, pod warunkiem że ograniczysz współbieżność: uruchomienie trzystu żądań jednocześnie wywoła błędy limitu częstotliwości (rate-limit) i pozostawi Cię z niedokończonym wsadem. Semfor asyncio zajmuje się właśnie tym – max_concurrent=5 oznacza maksymalnie pięć dokumentów przetwarzanych jednocześnie, niezależnie od liczby plików w kolejce. Pojedyncza funkcja zachowuje tę samą dyscyplinę co wersja sekwencyjna: przechwytuje wyjątki i zwraca słownik ze statusem, zamiast pozwalać, by gather uległ awarii.

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:
    """Przetwarza dokument asynchronicznie."""
    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]:
    """Przetwarza folder z kontrolowaną równoległością."""
    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)

# Wykonanie
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))

Kiedy duża objętość uzasadnia wnioskowanie wsadowe

Po przekroczeniu pewnego progu pytanie zmienia się z kwestii szybkości na kwestię kosztów. Mistral oferuje dedykowaną usługę Batch Inference, która jest bardziej ekonomiczna niż pojedyncze wywołania. Przesyłasz plik JSONL zawierający jedno żądanie w każdej linii. Pole custom_id – tutaj nazwa pliku bez rozszerzenia – pozwala odwzorować każdą odpowiedź na oryginalny dokument po zakończeniu przetwarzania wsadu.

import json

def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
    """Przygotowuje plik JSONL do przetwarzania wsadowego."""
    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"Przygotowano {compte} żądań w pliku {sortie}")
    return compte

Śledzenie tego, co się wydarzyło

Przetwarzanie masowe bez metryk to czarna skrzynka. Poniższa mała klasa danych zlicza sukcesy i błędy, oblicza upłynięty czas i wyznacza prędkość w dokumentach na sekundę. Prędkość ta informuje Cię, czy ustawienie max_concurrent jest optymalne, natomiast lista nieudanych plików zasila proces odzyskiwania po incydentach.

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"Przetwarzanie zakończone w {self.duree:.1f}s\n"
            f"  Sukcesy: {self.succes}/{self.total}\n"
            f"  Błędy: {self.erreurs}\n"
            f"  Prędkość: {self.vitesse:.2f} dok./s\n"
            f"  Nieudane pliki: {self.fichiers_erreur}"
        )

Na końcu wyeksportuj wyniki skryptu. Plik CSV trafi do arkusza kalkulacyjnego działu księgowości, a JSON do Twojej aplikacji; w obu przypadkach upewnij się, że użyto kodowania UTF-8 i parametru ensure_ascii=False, w przeciwnym razie znaki akcentowane pojawią się dla odbiorcy jako nieczytelne sekwencje.

import csv
import json

def exporter_csv(resultats: list[dict], chemin: str) -> None:
    """Eksportuje wyniki do formatu 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"Eksport CSV: {chemin}")


def exporter_json(resultats: list[dict], chemin: str) -> None:
    """Eksportuje wyniki do formatu JSON."""
    with open(chemin, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

    print(f"Eksport JSON: {chemin}")

Kluczowe wnioski

  • Przetwarzanie sekwencyjne sprawdza się przy małych wolumenach dzięki solidnej obsłudze błędów
  • Przetwarzanie równoległe z użyciem asyncio i semforów przyspiesza pracę przy dużych wolumenach
  • Usługa Batch Inference od Mistral to najbardziej opłacalne rozwiązanie przy bardzo dużych wolumenach
  • Dodaj monitorowanie i raportowanie, aby śledzić postępy i identyfikować błędy
  • Eksportuj wyniki do formatu CSV lub JSON w celu integracji z Twoimi systemami