Anotacje wsadowe
Na tej stronie
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 aliasumistral-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,…"}; typdocument_base64ze starszych przykładów nie istnieje ani w dokumentacji, ani w SDKmistralai, 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_annotationstrona po stronie; w SDKmistralaiw wersji 3.7.0 adnotacja dokumentu jest pojedynczym polem w odpowiedzi (response.document_annotation), a adnotację obrazu odczytuje się zimage.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
asyncioi 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