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

Implimenta Ċitazzjonijiet f'Python

Lezzjoni 9 / 16 Aġġornat 3 ta’ Novembru 2026 Avvanzat
F'din il-paġna
  1. Il-Pipeline Sħiħa taċ-Ċitazzjoni
  2. Iddefinixxi l-Kuntratt tal-Mudell fil-Messaġġ tas-Sistema
  3. Iddikjara l-Għodda tat-Tiftix
  4. Irritorna r-Riżultati fil-Format ta’ Referenza
  5. Separa t-Test mir-Referenzi
  6. Ipprepara l-Wiri tal-Frontend
  7. Punti Ewlenin

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 type jew reference_id—u l-reference_ids fir-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’ TextChunk u ReferenceChunk li 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