Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Pipeline ta' Produzzjoni

Lezzjoni 16 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Mill-Prova ta’ Kunċett għall-Produzzjoni
  2. Is-Sitt Komponenti ta’ Pipeline Sħiħa
  3. Klassi li Tinkapsula l-Ipproċessar
  4. Antiċipazzjoni tal-Kont
  5. Monitoraġġ tas-Saħħa tas-Servizz
  6. Fejn Imur Wara
  7. Sommarju tal-Kors
  8. Punti Ewlenin
  9. Ittestja l-Għarfien Tiegħek

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-alias mistral-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-tip document_base64 minn eżempji aktar antiki ma jeżistix la fid-dokumentazzjoni u lanqas fl-SDK mistralai, u dawk l-eżempji kienu jfallu. Sorsi: OCR Processor · Document QnA. Ikkoreġut fit-3 ta’ Novembru, 2026: Il-kodiċi qabel kien jaqra page.document_annotation paġna b’paġna; fl-SDK mistralai 3.7.0, l-annotazzjoni tad-dokument hija qasam wieħed fir-risposta (response.document_annotation), u l-annotazzjoni ta’ stampa tinqara minn image.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

  1. Kju tal-Inġestjoni: Jirċievi u jipprijoritizza d-dokumenti.
  2. Ipproċessar Minn Qabel: Jivvalida, jikkonverti l-formati u jtejjeb l-istampi.
  3. OCR + Annotazzjonijiet: Jestrah it-test u d-data strutturata.
  4. Ipproċessar Wara: Jivvalida, inaddaf u jarricchixxi d-data.
  5. Ħażna: Bażijiet tad-data, ħżunijiet vettorjali u arkivjar.
  6. 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ġġettBażi tal-Fatturazzjoni
OCRGħal kull paġna pproċessata
AnnotazzjonijietInklużi fis-sejħa tal-OCR (l-ebda kost addizzjonali)
QnATokens tal-input/output ibbażati fuq il-mudell taċ-chat
EmbeddingsTokens 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.