Pipeline ta' Produzzjoni
F'din il-paġna
Aġġornament 2 ta’ Novembru, 2026 — OCR. L-OCR 4.0 (
mistral-ocr-4-0) ġie rtirat fit-30 ta’ Settembru, 2026. Uża OCR 4.1 (mistral-ocr-4-1), li ilu disponibbli ġeneralment mill-31 ta’ Awwissu bl-istess prezz, jew l-aliasmistral-ocr-latest, li jipponta lejh mis-16 ta’ Lulju. L-OCR 4.1 iżid punteġġi ta’ kunfidenza fil-livell tal-blokki. Addendum 3 ta’ Novembru, 2026: PDF lokali jiġi trażmess f’base64 bħala{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; it-tipdocument_base64minn eżempji aktar antiki ma jeżistix la fid-dokumentazzjoni u lanqas fl-SDKmistralai, u dawk l-eżempji kienu jfallu. Sorsi: OCR Processor · Document QnA. Ikkoreġut fit-3 ta’ Novembru, 2026: Il-kodiċi qabel kien jaqrapage.document_annotationpaġna b’paġna; fl-SDKmistralai3.7.0, l-annotazzjoni tad-dokument hija qasam wieħed fir-risposta (response.document_annotation), u l-annotazzjoni ta’ stampa tinqara minnimage.image_annotation.
Mill-Prova ta’ Kunċett għall-Produzzjoni
Tagħallimt kif tuża l-OCR, l-annotazzjonijiet u d-Document AI QnA. Jifdal lakuna għalja: id-distanza bejn skript li jaħdem fuq il-laptop tiegħek u servizz li s-sħab tiegħek jiddependu fuqu kull filgħodu. Din il-lezzjoni finali tgħaqqad il-blokki tal-bini preċedenti f’pipeline robusta, sħiħa b’irkupru mill-iżbalji, monitoraġġ u kontroll tal-ispejjeż.
Is-Sitt Komponenti ta’ Pipeline Sħiħa
- Kju tal-Inġestjoni: Jirċievi u jipprijoritizza d-dokumenti.
- Ipproċessar Minn Qabel: Jivvalida, jikkonverti l-formati u jtejjeb l-istampi.
- OCR + Annotazzjonijiet: Jestrah it-test u d-data strutturata.
- Ipproċessar Wara: Jivvalida, inaddaf u jarricchixxi d-data.
- Ħażna: Bażijiet tad-data, ħżunijiet vettorjali u arkivjar.
- Interfaċċa tal-Mistoqsijiet: API tal-QnA, dashboards u integrazzjonijiet.
Il-kodiċi f’din il-lezzjoni jkopri l-qalba tal-katina—il-passi 3 u 4—għax hemmhekk jikkonċentraw id-diffikultajiet operattivi.
Klassi li Tinkapsula l-Ipproċessar
Il-klassi PipelineDocumentAI tissettja konfigurazzjoni darba għal dejjem—l-iskema tal-annotazzjoni, il-format tat-tabella, u n-numru ta’ tentattivi—imbagħad tapplikaha għal kull dokument. Tliet mekkaniżmi jistħoqqilhom attenzjoni. L-ewwel, it-tentattiv mill-ġdid b’backoff esponenzjali (time.sleep(2 ** tentative)) ibiegħed it-tentattivi b’sekonda, imbagħad tnejn, imbagħad erba’. Dan jagħti żmien lis-saturazzjoni tranżitorja tal-API biex issolvi ruħha minflok ma taggravaha. It-tieni, il-logging isegwi kull suċċess bin-numru ta’ paġni u t-tul ta’ żmien tiegħu, u kull falliment bin-numru tat-tentattiv tiegħu; mingħajr dawn il-linji, se ssib l-inċidenti biss meta ċ-ċentru tal-kontijiet iċempellek. Fl-aħħar, id-dizzjunarju stats jipprovdi r-rapport ta’ tmiem il-batch.
Innota li l-metodu dejjem jirritorna ResultatTraitement, anke wara li jintemmu t-tentattivi kollha: min sejjaħ qatt m’għandu jittratta eċċezzjoni, sempliċiment jaqra l-qasam erreur.
import os
import time
import base64
import logging
from pathlib import Path
from dataclasses import dataclass, field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
from typing import Optional
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("document_ai_pipeline")
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
@dataclass
class ResultatTraitement:
fichier: str
pages: int = 0
texte: str = ""
annotations: Optional[dict] = None
duree_secondes: float = 0.0
erreur: Optional[str] = None
class PipelineDocumentAI:
def __init__(
self,
schema_annotation=None,
table_format: str = "markdown",
max_retries: int = 3,
):
self.schema_annotation = schema_annotation
self.table_format = table_format
self.max_retries = max_retries
self.stats = {"total": 0, "succes": 0, "erreurs": 0}
def traiter_document(self, chemin: str) -> ResultatTraitement:
"""Jipproċessa dokument b'tentattiv mill-ġdid u monitoraġġ."""
debut = time.time()
self.stats["total"] += 1
for tentative in range(self.max_retries):
try:
# Aqra u kkodifika
with open(chemin, "rb") as f:
doc_b64 = base64.b64encode(f.read()).decode("utf-8")
# Parametri tas-sejħa
params = {
"model": "mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
},
"table_format": self.table_format,
}
if self.schema_annotation:
params["document_annotation_format"] = (
response_format_from_pydantic_model(
self.schema_annotation
)
)
# Sejħa tal-OCR
response = client.ocr.process(**params)
# Estrai t-test
texte = "\n\n".join(
p.markdown for p in response.pages
)
# Estrai l-annotazzjonijiet
annotations = None
if self.schema_annotation:
if response.document_annotation:
annotations = response.document_annotation
duree = time.time() - debut
self.stats["succes"] += 1
logger.info(
f"OK: {chemin} ({len(response.pages)} paġni, "
f"{duree:.1f}s)"
)
return ResultatTraitement(
fichier=chemin,
pages=len(response.pages),
texte=texte,
annotations=annotations,
duree_secondes=duree,
)
except Exception as e:
logger.warning(
f"Tentattiv {tentative + 1}/{self.max_retries} "
f"falla għal {chemin}: {e}"
)
if tentative < self.max_retries - 1:
time.sleep(2 ** tentative) # Backoff esponenzjali
# It-tentattivi kollha fallew
self.stats["erreurs"] += 1
return ResultatTraitement(
fichier=chemin,
duree_secondes=time.time() - debut,
erreur="Falliment wara t-tentattivi kollha",
)
def traiter_dossier(self, dossier: str) -> list[ResultatTraitement]:
"""Jipproċessa l-PDFs kollha f'folder."""
chemin = Path(dossier)
fichiers = sorted(chemin.glob("*.pdf"))
resultats = []
for fichier in fichiers:
resultat = self.traiter_document(str(fichier))
resultats.append(resultat)
return resultats
def rapport(self) -> str:
"""Jiġġenera rapport tal-ipproċessar."""
return (
f"Dokumenti pproċessati: {self.stats['total']}\n"
f"Suċċessi: {self.stats['succes']}\n"
f"Żbalji: {self.stats['erreurs']}\n"
f"Rata ta' suċċess: "
f"{self.stats['succes']/max(self.stats['total'],1)*100:.1f}%"
)
Fil-prattika, l-istess klassi tkopri ż-żewġ ħtiġijiet: meta tiġi istanzjata mingħajr skema, sempliċiment testrahi t-test; meta tiġi istanzjata b’mudell Pydantic, tipproduċi wkoll data strutturata.
# Pipeline sempliċi (OCR biss)
pipeline = PipelineDocumentAI(table_format="markdown")
resultats = pipeline.traiter_dossier("./factures/")
print(pipeline.rapport())
# Pipeline b'annotazzjonijiet
from pydantic import BaseModel, Field
class ExtractionFacture(BaseModel):
fournisseur: str = Field(..., description="Isem il-fornitur")
montant_ttc: float = Field(..., description="Ammont bil-VAT")
date: str = Field(..., description="Data (YYYY-MM-DD)")
pipeline_annote = PipelineDocumentAI(
schema_annotation=ExtractionFacture,
table_format="markdown"
)
resultats = pipeline_annote.traiter_dossier("./factures/")
Antiċipazzjoni tal-Kont
Il-kontroll tal-ispejjeż huwa essenzjali fil-produzzjoni, u jibda billi tifhem għal xiex qed tiġi fatturat.
| Oġġett | Bażi tal-Fatturazzjoni |
|---|---|
| OCR | Għal kull paġna pproċessata |
| Annotazzjonijiet | Inklużi fis-sejħa tal-OCR (l-ebda kost addizzjonali) |
| QnA | Tokens tal-input/output ibbażati fuq il-mudell taċ-chat |
| Embeddings | Tokens tal-input |
Il-fatt li l-annotazzjonijiet ma jinvolvux kost addizzjonali jbiddel id-disinn: estrai l-metadejta matul il-pass tal-OCR minflok ma tmexxi sejħa separata tal-LLM wara. Il-funzjoni ta’ stima hawn taħt tippermettilek tipprezza proġett qabel ma tniedih; ir-rati tagħha huma figuri ta’ ordni ta’ kobor li għandek taġġusta, filwaqt li t-tabella ta’ referenza ppubblikata ta’ Mistral tibqa’ l-awtorità.
def estimer_cout(
nombre_pages: int,
avec_qna: bool = False,
modele_qna: str = "mistral-small-latest"
) -> dict:
"""Jistma l-kost tal-ipproċessar."""
# Rati approssimattivi (iċċekkja r-rati attwali)
cout_ocr_par_page = 0.001 # Aġġusta skont it-tier
cout_qna_par_1k_tokens = {
"mistral-small-latest": 0.001,
"mistral-large-latest": 0.008,
}
cout_ocr = nombre_pages * cout_ocr_par_page
cout_qna = 0.0
if avec_qna:
# Stima: ~500 token għal kull paġna medjament
tokens_estimes = nombre_pages * 500
cout_qna = (
tokens_estimes / 1000
* cout_qna_par_1k_tokens.get(modele_qna, 0.001)
)
return {
"cout_ocr": round(cout_ocr, 4),
"cout_qna": round(cout_qna, 4),
"cout_total": round(cout_ocr + cout_qna, 4),
}
Monitoraġġ tas-Saħħa tas-Servizz
Pipeline tiddegrada bil-mod u b’mod silenzjuż: fornitur ġdid jibgħat skansijiet ta’ kwalità fqira, ir-rata tal-iżbalji titla’ minn 2% għal 15%, u ħadd ma jinnota sakemm jingħalaq ix-xahar. Erba’ metriki biżżejjed biex jinstab id-drift—il-volum ipproċessat, it-tul medju, ir-rata tal-iżbalji u l-kost stmat—dment li temettihom sistematikament u tibgħathom lill-għodda tas-soltu tiegħek, kemm jekk Datadog, Prometheus jew oħra.
import json
from datetime import datetime
def log_metrique(nom: str, valeur: float, tags: dict = None) -> None:
"""Jirreġistra metrika ta' monitoraġġ."""
metrique = {
"timestamp": datetime.utcnow().isoformat(),
"nom": nom,
"valeur": valeur,
"tags": tags or {}
}
# Fil-produzzjoni: ibgħat lejn Datadog, Prometheus, eċċ.
logger.info(f"METRIQUE: {json.dumps(metrique)}")
# Eżempji ta' metriki biex issegwi
log_metrique("ocr.pages_traitees", 150, {"batch": "factures_mars"})
log_metrique("ocr.duree_moyenne_secondes", 2.3)
log_metrique("ocr.taux_erreur", 0.02)
log_metrique("ocr.cout_estime_usd", 0.15)
Fejn Imur Wara
Issa għandek il-bażiċi biex tibni sistema sħiħa ta’ Document AI, u diversi estensjonijiet jiftħu skont il-limitazzjonijiet tiegħek. Volumi għoljin ħafna jiġġustifikaw dispjegament on-premise tal-mudell OCR fuq GPU ddedikata; dokumenti speċifiċi ħafna għan-negozju tiegħek jistgħu jimmotivaw fine-tuning, suġġett li għandu jiġi indirizzat direttament ma’ Mistral. Fuq in-naħa tal-integrazzjoni, l-isfida hija li tgħaqqad il-pipeline mas-sistemi eżistenti tiegħek—ERP, CRM—u tibni dashboard biex it-timijiet tiegħek ikunu jistgħu jistaqsu d-dokumenti huma stess mingħajr ma jgħaddu minnek. L-aħħar pass huwa li tneħħi t-trigger manwali: il-pipeline tiġi eżegwita awtomatikament meta jaslu dokumenti ġodda.
Sommarju tal-Kors
Dawn is-sittax-il lezzjoni ħaduk matul iċ-ċiklu kollu. Bdejt bil-fondamenti—x’inhu d-Document AI, il-mudell OCR 4, u l-każijiet ta’ użu—qabel ma għaddajt għal OCR avvanzat bl-API, l-estrazzjoni tat-tabelli, l-intestaturi/pijedi tal-paġna u l-ottimizzazzjoni. L-annotazzjonijiet tawlek imbagħad l-estrazzjoni strutturata, l-ipproċessar bil-batch u l-kontroll tal-konformità, segwit mid-Document QnA, li fetaħ l-istaqsar bil-lingwa naturali, minn dokumenti iżolati għal korpora indiċjati f’RAG. Issa għandek il-blokki tal-bini meħtieġa biex tgħammar il-ġestjoni tad-dokumenti tal-organizzazzjoni tiegħek b’Mistral Document AI.
Punti Ewlenin
- Pipeline ta’ produzzjoni tinkludi tentattiv mill-ġdid, logging, monitoraġġ u ġestjoni tal-ispejjeż.
- Il-backoff esponenzjali jipproteġi kontra żbalji tranżitorji tal-API.
- Stma l-ispejjeż tiegħek qabel ma tiskala (OCR għal kull paġna, QnA għal kull token).
- Il-monitoraġġ kontinwu jippermettilek tiskopri d-degradazzjoni tal-prestazzjoni.
- Id-Document AI jkopri ċ-ċiklu tal-ħajja sħiħ tad-dokument, mill-inġestjoni sal-operazzjoni.
Ittestja l-Għarfien Tiegħek
OCR, annotazzjonijiet, QnA: ivvalida l-katina sħiħa tad-dokumenti.
1. X'jipproduċi l-API tal-OCR ta' Mistral minn dokument?
Tweġiba: Il-kontenut strutturat tad-dokument—test, tabelli, layout—lest għall-użu programmatiku: l-OCR 4 jaqra d-dokument bħala sors ta’ data, mhux bħala stampa.
2. X'inhu l-għan tal-API tal-Annotazzjonijiet?
Tweġiba: Biex testrahi metadata strutturata skont l-iskema tiegħek (oqsma tal-fattura, klawżoli tal-kuntratt)—jew individwalment jew f’batch għal volumi għoljin.
3. X'jippermetti d-Document QnA?
Tweġiba: Li tagħmel mistoqsijiet bil-lingwa naturali dwar dokument wieħed jew aktar u tikseb tweġibiet ibbażati fuq il-kontenut tagħhom—is-saff konversazzjonali fuq l-estrazzjoni.
4. Kif tottimizza l-preċiżjoni tal-OCR?
Tweġiba: Permezz tal-kwalità tal-input (riżoluzzjoni, ċarezza, orjentazzjoni) u l-ġestjoni ta’ żoni diffiċli—intestaturi, piedi tal-paġna, paġnar—li l-kors jgħallmek timmaniġġja b’mod espliċitu.
5. Għaliex tgħaqqad l-OCR mar-RAG?
Tweġiba: L-OCR jibdel id-dokumenti skannjati f’test indiċjabbli, filwaqt li r-RAG jagħmilhom suġġetti għal mistoqsijiet fuq skala kbira: flimkien, jippermettu tfittxija semantika madwar arkivji sħaħ.
Estrazzjoni, annotazzjoni, mistoqsija-u-tweġiba, indiċjar: il-pipeline ta’ produzzjoni hawn fuq tgħaqqad ir-raba’ flimkien—il-karta tiegħek issir bażi tad-data.