Implimenta Ċitazzjonijiet f'Python
F'din il-paġna
Aġġornat fit-3 ta’ Novembru, 2026 abbażi tal-gwida Citations & References ta’ Mistral: ir-riżultat tal-għodda jsegwi l-format iddokumentat—oġġett indikat bin-numru tas-sors, mingħajr oqsma
typejewreference_id—u l-reference_idsfir-risposta jiġu riżolti permezz ta’str(ref_id)f’dak l-oġġett. Sors: Citations & References.
Il-Pipeline Sħiħa taċ-Ċitazzjoni
Issa se tassambja pipeline RAG li tiċċita s-sorsi tagħha, mill-ewwel sejħa tal-API sal-istruttura tad-data li l-interfaċċa tiegħek tuża. Żomm dan il-prinċipju f’moħħok: il-mudell qatt ma jiġbed id-dokumenti huwa stess. Huwa jissinjala li għandu bżonn tfittxija, int twettaq dik it-tiftixa fil-bażi tad-data tiegħek stess, u mbagħad tirritorna l-estratti flimkien mal-identifikaturi tagħhom. Dan il-mixi u l-miġi jipproduċi tweġiba fejn kull affermazzjoni tibqa’ marbuta ma’ dokument reali.
Speċifikament, ċiklu sħiħ jeħtieġ żewġ sejħiet lejn chat.complete. L-ewwel waħda ttriggerja s-sejħa tal-għodda; it-tieni waħda tiġġenera t-tweġiba ċċitata ladarba s-sorsi jiġu injettati fl-istorja. Aħna se nimxu ma’ dan iċ-ċiklu billi nużaw każ sempliċi: assistent tad-dokumentazzjoni interna mistoqsi dwar l-aħjar prattiki għall-varar ta’ LLM.
Iddefinixxi l-Kuntratt tal-Mudell fil-Messaġġ tas-Sistema
Il-messaġġ tas-sistema jistabbilixxi l-kuntratt: wieġeb abbażi tas-sorsi pprovduti, iċċita b’mod sistematiku, u fuq kollox, ammeta meta l-informazzjoni tkun nieqsa minflok ma timla l-vojt. Din l-aħħar istruzzjoni tagħmel id-differenza fil-produzzjoni, għax it-tweġibiet għandhom it-tendenza li jiddevjaw fuq mistoqsijiet li mhumiex koperti sew fil-bażi tad-dokumentazzjoni.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Messaġġ tas-sistema li jħeġġeġ iċ-ċitazzjonijiet
system_message = {
"role": "system",
"content": (
"Int assistent tad-dokumentazzjoni. "
"Wieġeb il-mistoqsijiet billi tuża s-sorsi pprovduti. "
"Iċċita s-sorsi tiegħek b'mod sistematiku. "
"Jekk l-informazzjoni ma tkunx f'ebda sors, iddikjara dan b'mod espliċitu."
)
}
user_message = {
"role": "user",
"content": "X'inhu l-aħjar mod biex tiddispjaċċa LLM fil-produzzjoni?"
}
messages = [system_message, user_message]
Iddikjara l-Għodda tat-Tiftix
L-għodda tiddeskrivi kif tidher tfittxija ta’ dokument fis-sistema tiegħek: hawnhekk, funzjoni sempliċi search_documentation li tieħu mistoqsija ta’ test. L-ewwel sejħa ma tistennix tweġiba miktuba; tistenna li l-mudell jifformola l-mistoqsija li jqis rilevanti, u b’hekk tiffrankalek il-kitba ta’ saff ta’ riformulazzjoni.
reference_tool = {
"type": "function",
"function": {
"name": "search_documentation",
"description": "Ifittex fil-bażi tad-data tad-dokumentazzjoni",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Mistoqsija għat-tiftix"
}
},
"required": ["query"]
}
}
}
# L-ewwel sejħa: il-mudell jitlob li juża l-għodda
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Irritorna r-Riżultati fil-Format ta’ Referenza
Dan huwa l-pass strutturali. Ir-riżultati tal-magna tat-tiftix tiegħek jerġgħu lura f’ToolMessage li l-kontenut tiegħu huwa l-oġġett ta’ referenza mil-lezzjoni ta’ qabel: kull sors għandu numru ("0", "1"…), URL, titlu, u l-estratti magħżula. Dawn huma n-numri li l-mudell jerġa’ juża biex jimmarka ċ-ċitazzjonijiet tiegħu, u li l-frontend tiegħek se jirriżolva aktar tard f’links.
from mistralai.client.models import ToolMessage
# Riżultati tat-tiftix tad-dokumentazzjoni, fil-format ta' referenza ta' Mistral
references = {
"0": {
"url": "https://docs.example.com/deployment-guide",
"title": "Gwida għad-Dispiegament ta' LLM",
"snippets": [[
"Dejjem ikkonfigura limiti ta' rati biex tipproteġi s-servizz.",
"Immonitorja l-latency P99 u r-rati ta' żball kontinwament."
]],
"description": None,
"date": "2026-09-01",
"source": "docs"
},
"1": {
"url": "https://docs.example.com/security",
"title": "Sigurtà tal-Applikazzjonijiet tal-AI",
"snippets": [[
"Iffiltra l-inputs tal-utent biex tipprevjeni injezzjonijiet.",
"Qatt tesponi ċwievet tal-API fuq in-naħa tal-klijent."
]],
"description": None,
"date": "2026-08-15",
"source": "docs"
},
"2": {
"url": "https://docs.example.com/scaling",
"title": "Skalabbiltà u Prestazzjoni",
"snippets": [[
"Uża caching semantiku biex tnaqqas is-sejħiet tal-API.",
"Iddaqsja l-istanzi abbażi tat-traffiku massimu."
]],
"description": None,
"date": "2026-07-20",
"source": "docs"
}
}
# Żid is-sejħa tal-għodda u r-risposta fl-istorja
tool_call = response.choices[0].message.tool_calls[0]
messages.append(response.choices[0].message)
messages.append(
ToolMessage(
tool_call_id=tool_call.id,
name="search_documentation",
content=json.dumps(references, ensure_ascii=False)
)
)
Innota li l-messaġġ oriġinali tal-mudell jerġa’ jiġi injettat fl-istorja qabel il-ToolMessage: mingħajr dan il-par sejħa tal-għodda / riżultat tal-għodda, l-API tirrifjuta l-kontinwazzjoni. It-tieni sejħa m’għadhiex teħtieġ id-definizzjonijiet tal-għodda, peress li t-tiftix diġà sar.
# It-tieni sejħa: il-mudell jiġġenera tweġiba b'ċitazzjonijiet
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Separa t-Test mir-Referenzi
Ir-risposta ċċitata m’għadhiex sempliċiment stringa iżda sekwenza ta’ biċċiet li jalternaw proża u marki ta’ ċitazzjoni. Il-parsing jinvolvi li tgħaddi minn din is-sekwenza u tissepara: l-oġġetti TextChunk jerġgħu jibnu t-test li jista’ jinqara, filwaqt li l-oġġetti ReferenceChunk iwasslu l-reference_ids effettivament użati. Din id-distinzjoni tagħtik informazzjoni prezzjuża: eżattament liema sorsi uża l-mudell minn dawk li pprovdejt.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Testra t-test u r-referenzi minn tweġiba ċċitata."""
content_parts = response.choices[0].message.content
text_parts = []
cited_refs = set()
for chunk in content_parts:
if isinstance(chunk, TextChunk):
text_parts.append(chunk.text)
elif isinstance(chunk, ReferenceChunk):
for ref_id in chunk.reference_ids:
cited_refs.add(ref_id)
return {
"text": "".join(text_parts),
"references_used": list(cited_refs)
}
result = parse_cited_response(final_response)
print("=== Tweġiba ===")
print(result["text"])
print("\n=== Sorsi Ċċitati ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Ipprepara l-Wiri tal-Frontend
Li tiċċatta r-risposta f’test sempliċi jitlef il-pożizzjoni taċ-ċitazzjonijiet, u għalhekk il-valur tagħhom. Huwa aħjar li żżomm is-sekwenza u tarrikkixxiha: solvi kull ReferenceChunk kontra tabella ta’ referenza biex iġġib it-titlu u l-URL ta’ kull sors. L-interfaċċa tiegħek b’hekk tirċievi lista ordnata ta’ blokok li tista’ tirrendi bħala links li jistgħu jiġu kklikkjati, tooltips, jew numri ta’ ċitazzjoni interattivi, mingħajr qatt ma jkollha terġa’ tinterpreta t-test.
def format_for_frontend(response, reference_map):
"""Tifformat ir-risposta b'ċitazzjonijiet għall-frontend."""
content_parts = response.choices[0].message.content
formatted = []
for chunk in content_parts:
if isinstance(chunk, TextChunk):
formatted.append({
"type": "text",
"content": chunk.text
})
elif isinstance(chunk, ReferenceChunk):
refs = []
for ref_id in chunk.reference_ids:
source = reference_map.get(str(ref_id))
if source:
refs.append({
"id": ref_id,
"title": source["title"],
"url": source["url"]
})
formatted.append({
"type": "citation",
"references": refs
})
return formatted
Qabel ma tiftaħ dan il-pipeline għall-bażi sħiħa tad-dokumentazzjoni tiegħek, imxiha bi tlieta sa ħames sorsi biss, bħall-eżempju hawn fuq. Se tara immedjatament jekk il-mudell jiċċitax fil-post it-tajjeb, jekk jużax dokumenti multipli, jew jekk jeħilx sistematikament mal-ewwel wieħed, u b’hekk tippermettilek tikkoreġi l-messaġġ tas-sistema qabel ma l-imġiba tintilef fil-volum.
Punti Ewlenin
- Il-pipeline jsegwi fluss ta’ żewġ sejħiet: sejħa tal-għodda mbagħad tweġiba ċċitata
- Ir-referenzi jgħaddu permezz ta’
ToolMessage, f’oġġett indikat bin-numru tas-sors ("0","1"…) - Ir-risposta fih taħlita ta’
TextChunkuReferenceChunkli trid tiġi pproċessata - Iddisinja l-output biex il-frontend tiegħek ikun jista’ juri ċitazzjonijiet interattivi
- Ittestja b’3–5 sorsi biex tivvalida l-imġiba qabel ma tgħaddi għall-produzzjoni