Passi Li Jmiss: Document AI, Sejħiet tal-Funzjonijiet, u Pipelines Multimodali
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026 abbażi tal-paġna Document QnA ta’ Mistral u l-SDK
mistralai3.7.0: l-eżempju jistaqsi dokument bl-użu ta’ mudell ta’ chat (mistral-small-latest), mhux il-mudell OCR, udocument_image_limitmhuwiex parametru għalchat.complete(is-sejħa kienet tonqos); il-limiti tal-paġni huma stabbiliti f’client.ocr.process. Sors: Document QnA.
Lil hinn mill-API tal-Viżjoni
Issa tgħallimt il-fundamentali tal-API tal-Viżjoni ta’ Mistral: tibgħat stampi permezz ta’ URL u Base64, tanalizza ċ-ċarts, twettaq OCR, testra data strutturata, u tqabbel l-istampi. Din il-bażi għandha limitu naturali—s’issa, il-mudell dejjem ħares lejn stampa u rritorna test, qatt ma ħa azzjoni. Din il-lezzjoni finali taqsam dik il-fruntiera f’tliet stadji: is-servizz speċjalizzat għad-dokumenti, is-sejħiet tal-funzjonijiet li jbidlu l-analiżi f’azzjoni, u l-pipelines li jgħaqqduhom flimkien.
Mistral Document AI (OCR 4)
Għal ħtiġijiet avvanzati ta’ OCR, Mistral toffri Document AI, servizz speċjalizzat fl-ipproċessar tad-dokumenti. Filwaqt li l-API tal-Viżjoni tittratta stampi individwali, Document AI jaħdem fuq skala ta’ dokument: jittratta PDFs b’ħafna paġni u janalizza fajls twal f’daqqa waħda. Jimmaniġġja layouts kumplessi—kolonni, intestaturi u piè di paġna, tabelli mbejjna—u jippreserva l-istruttura, b’output li jżomm il-ġerarkija tad-dokument ta’ titli, paragrafi, u listi. Fl-aħħar nett, il-preċiżjoni tal-OCR tiegħu hija ottimizzata kemm għat-test stampat kif ukoll għal dak miktub bl-idejn.
Eżempju ta’ Sejħa ta’ Document AI
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Analizza PDF b'Document AI
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Extract the full content of this document while preserving the structure."
},
{
"type": "document_url",
"document_url": "https://example.com/annual-report.pdf"
}
]
}
]
)
print(response.choices[0].message.content)
Id-differenza minn kull ma ktibt s’issa tinsab fit-tip tal-element: document_url minflok image_url, moqri minn mudell standard ta’ chat (mistral-small-latest fid-dokumentazzjoni ta’ Mistral). Id-dokument m’għandux ikun akbar minn 50 MB u għandu jkun fih mhux aktar minn 1,000 paġna. Biex tipproċessa biss parti minn rapport annwali ta’ 300 paġna, uża l-endpoint tal-OCR (client.ocr.process) minflok, fejn il-parametri pages u image_limit jillimitaw ix-xogħol.
Meta tuża Document AI vs. API tal-Viżjoni
| Ħtieġa | API tal-Viżjoni | Document AI |
|---|---|---|
| Ritratt ta’ fattura | Biżżejjed | Eċċessiv |
| PDF ta’ 50 paġna | Mhux appoġġjat | Ideali |
| Tabella mbejjna kumplessa | Approssimattiva | Preċiża |
| Screenshot ta’ interfaċċja | Ideali | Mhux xieraq |
| Dokument miktub bl-idejn | Bażiku | Ottimizzat |
Ftakar fir-regola ġenerali: uża l-API tal-Viżjoni għal dak li twieled bħala stampa, u Document AI għal dak li twieled bħala dokument.
Viżjoni + Sejħiet tal-Funzjonijiet
S’issa, il-kodiċi tiegħek kien jirċievi tweġiba u jiddeċiedi x’jagħmel biha. Is-sejħiet tal-funzjonijiet jreġġgħu lura din ir-relazzjoni: inti tipprovdi lill-mudell b’lista ta’ azzjonijiet disponibbli, u huwa jagħżel liema sejħa jagħmel ibbażat fuq l-immaġni. Din hija ċ-ċavetta biex tibni aġenti viżwali awtonomi.
Iċ-ċiklu għandu erba’ passi:
- Inti tibgħat stampa + definizzjonijiet tal-funzjonijiet
- Il-mudell janalizza l-immaġni u jiddeċiedi liema funzjoni sejjaħ
- Inti tesegwixxi l-funzjoni u tirritorna r-riżultat
- Il-mudell jifformula tweġiba finali
Eżempju: Aġent tal-Ipproċessar tal-Fatturi
Ikkunsidra dipartiment tal-kontabbiltà li jirċievi fatturi bil-posta. Żewġ riżultati huma possibbli: il-fattura hija valida u trid tiġi rreġistrata, jew għandha anomaliја u trid tiġi sinjalata. Għalhekk niddefinixxu żewġ għodod, bil-parametri u l-oqsma meħtieġa tagħhom.
import json
# Iddefinixxi l-għodod disponibbli
outils = [
{
"type": "function",
"function": {
"name": "enregistrer_facture",
"description": "Enregistre une facture dans le système comptable",
"parameters": {
"type": "object",
"properties": {
"emetteur": {"type": "string", "description": "Nom de l'émetteur"},
"numero": {"type": "string", "description": "Numéro de facture"},
"date": {"type": "string", "description": "Date d'émission (YYYY-MM-DD)"},
"montant_ttc": {"type": "number", "description": "Montant TTC en euros"},
"tva": {"type": "number", "description": "Montant de la TVA"}
},
"required": ["emetteur", "numero", "date", "montant_ttc"]
}
}
},
{
"type": "function",
"function": {
"name": "signaler_anomalie",
"description": "Signale une anomalie sur une facture (doublons, montants incohérents)",
"parameters": {
"type": "object",
"properties": {
"type_anomalie": {"type": "string"},
"description": {"type": "string"}
},
"required": ["type_anomalie", "description"]
}
}
}
]
# Ibgħat l-immaġni bl-għodod
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Vous êtes un assistant comptable. Analysez les factures et utilisez les outils appropriés."
},
{
"role": "user",
"content": [
{"type": "text", "text": "Traitez cette facture."},
{"type": "image_url", "image_url": encoder_image("factures/facture-2024-0042.jpg")}
]
}
],
tools=outils,
tool_choice="auto"
)
# Immaniġġja s-sejħa tal-funzjoni
if response.choices[0].message.tool_calls:
appel = response.choices[0].message.tool_calls[0]
nom_fonction = appel.function.name
arguments = json.loads(appel.function.arguments)
print(f"Fonction appelée : {nom_fonction}")
print(f"Arguments : {json.dumps(arguments, indent=2, ensure_ascii=False)}")
Ifformula l-qasam description għal kull funzjoni bir-reqqa: il-mudell jibbaża l-għażla tiegħu fuq dan, mhux fuq l-isem. Deskrizzjoni vaga toħloq aġent li jsejjaħ il-funzjoni ħażina.
Pipelines Multimodali
Pipeline multimodali tgħaqqad diversi passi ta’ pproċessar billi tikkombina viżjoni, test, u għodod. Il-valur tagħha huwa kemm ekonomiku kif ukoll organizzattiv: kull pass jimpjega strettament il-mudell meħtieġ.
Eżempju: Pipeline tal-Ipproċessar tal-Posta
Il-posta li tidħol għal SME taħlit bejn fatturi, kwotazzjonijiet, kuntratti, u reklami. Il-klassifikazzjoni tagħhom tispiċċa ftit; l-analiżi dettaljata tagħhom tispiċċa aktar. Għalhekk il-pipeline tibda b’sortjar bl-użu ta’ mudell ħafif, u tinvolvi lill-Large biss fuq dokumenti li jiġġustifikawh.
def mail_pipeline(image_path):
"""Pipeline complet : classification -> extraction -> action."""
# Pass 1: Klassifikazzjoni (mudell ħafif)
classification = client.chat.complete(
model="mistral-small-latest",
response_format={"type": "json_object"},
messages=[{
"role": "user",
"content": [
{"type": "text", "text": 'Classifiez ce document : {"type": "facture|devis|contrat|courrier|autre", "urgence": "haute|moyenne|basse"}'},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
info = json.loads(classification.choices[0].message.content)
print(f"Type : {info['type']} | Urgence : {info['urgence']}")
# Pass 2: Estrazzjoni dettaljata (mudell qawwi, biss jekk meħtieġ)
if info["type"] == "facture":
extraction = client.chat.complete(
model="mistral-large-latest",
response_format={"type": "json_object"},
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Extrayez toutes les données de cette facture en JSON : emetteur, numero, date, lignes, total_ht, tva, total_ttc."},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
data = json.loads(extraction.choices[0].message.content)
return {"classification": info, "données": data}
# Pass 3: Sommarju għal tipi oħra
summary = client.chat.complete(
model="mistral-small-latest",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Résumez le contenu de ce document en 3 phrases maximum."},
{"type": "image_url", "image_url": encoder_image(image_path)}
]
}]
)
return {"classification": info, "summary": summary.choices[0].message.content}
# Ipproċessa lott ta' posta
from pathlib import Path
for file in sorted(Path("courrier/").glob("*.jpg")):
print(f"\n--- {file.name} ---")
result = mail_pipeline(file)
print(json.dumps(result, indent=2, ensure_ascii=False))
F’lott fejn wieħed minn kull ħames oġġetti huwa fattura, erbgħa minn ħames dokumenti qatt ma jaraw il-mudell għali, għal kwalità finali identika.
Sommarju tal-Kors
Matul dawn it-12-il lezzjoni, mort mill-mekkaniżmu għall-applikazzjoni. L-ewwel fhimt l-arkitettura multimodali u x’jiġri eżattament meta stampa tidħol fil-mudell, imbagħad tgħallimt tagħżel il-varjant adattat għax-xogħol tiegħek—Large, Small, jew Ministral. Imbagħad tgħallimt tibgħat l-istampi permezz ta’ URL u Base64, waħda waħda jew f’lotti. Fuq din il-bażi, affrontajt l-użi li jiffurmaw il-biċċa l-kbira tax-xogħol reali: l-analiżi taċ-ċarts, il-qari tat-test permezz tal-OCR, l-estrazzjoni ta’ data strutturata, u t-tqabbil tal-istampi għall-kontroll tal-kwalità u t-traċċar tal-evoluzzjoni. Fl-aħħar nett, tgħallimt tottimizza s-sejħiet tiegħek għall-ispejjeż, il-latency, u l-affidabbiltà, u tintegra l-viżjoni f’pipelines akbar grazzi għas-sejħiet tal-funzjonijiet.
Passi Li Jmiss
Erba’ direzzjonijiet jestendu din it-triq b’mod naturali. L-ewwel, Document AI, li l-OCR 4 tiegħu jittratta dokumenti li l-API tal-Viżjoni ma tistax tappoġġja. Imbagħad, l-aġenti, li jgħaqqdu l-viżjoni u s-sejħiet tal-funzjonijiet biex jinbnew sistemi li jiddeċiedu u jaġixxu. Imbagħad il-fine-tuning, jekk l-istampi tiegħek għandhom speċifiċitajiet li l-ebda mudell ġeneralista ma jaf—katalgu ta’ partijiet industrijali, formola interna. Fl-aħħar nett, il-Batch API, iddisinjat biex jipproċessa eluf ta’ stampi bi spiża mnaqqsa meta l-ħin ta’ rispons mhuwiex kritiku. Fit-tul, kapaċitajiet multimodali avvanzati se jiftħu t-triq għall-vidjo u l-awdjo meta jkunu disponibbli.
Punti Ewlenin
- Document AI (OCR 4) huwa l-kumplament naturali għall-API tal-Viżjoni għal dokumenti kumplessi u PDFs
- Is-sejħiet tal-funzjonijiet ibiddlu l-viżjoni f’aġent awtonomu kapaċi jaġixxi fuq id-data estratta
- Pipeline multimodali tgħaqqad il-klassifikazzjoni (Small) u l-estrazzjoni (Large) biex tottimizza l-kwalità u l-ispejjeż
- L-API tal-Viżjoni ta’ Mistral hija blokka fundamentali għall-bini ta’ applikazzjonijiet moderni tal-AI
Ittestja l-Għarfien Tiegħek
Viżjoni permezz tal-API: ħames mistoqsijiet biex tirranġa l-pipeline.
1. Kif tibgħat stampa lill-API ta' Mistral?
Tweġiba: Permezz ta’ URL jew kodifikata f’Base64, f’messaġġ b’kontenut imħallat ta’ test + stampa—u stampi multipli jistgħu jivvjaġġaw fl-istess messaġġ għat-tqabbil.
2. X'tippermetti l-viżjoni lil hinn mid-deskrizzjoni?
Tweġiba: Analiżi taċ-ċarts, OCR (traskrizzjoni ta’ test minn stampi), u estrazzjoni ta’ data strutturata—l-immaġni ssir sors ta’ data, mhux illustrazzjoni.
3. Kif tagħmel l-estrazzjoni strutturata minn stampa affidabbli?
Tweġiba: Speċifika l-iskema mistennija b’mod preċiż (oqsma, format), itlob kompletezza jew ammissjoni ta’ nuqqas, u vverifika valuri kritiċi—il-viżjoni tiġi ppruvokata bħat-test.
4. Liema limiti għandek iżżomm f'moħħok?
Tweġiba: Il-kwalità tal-immaġni tikkundizzjona kollox (riżoluzzjoni, ċarezza); test żgħir ħafna u layouts kumplessi jgħejjew lill-mudell—ottimizza l-input qabel ma tlum l-output.
5. X'inhuma s-segwiti naturali ta' dan il-kors?
Tweġiba: Document AI għal dokumenti sħaħ, sejħiet tal-funzjonijiet biex tgħaqqad l-estrazzjoni mas-sistemi tiegħek, u pipelines multimodali li jgħaqqdu kollox flimkien.
URL jew Base64, prompts preċiżi, inputs bir-reqqa: il-pipeline tal-viżjoni huwa lest—il-passi li jmiss jintegrawh fl-applikazzjonijiet tiegħek.