Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Implementacija citatov v Pythonu

Lekcija 9 od 16 Posodobljeno 3. november 2026 Napredni
Na tej strani
  1. Celoten potek dela za citate
  2. Opredelitev pogodbe modela v sistemskem sporočilu
  3. Deklaracija iskalnega orodja
  4. Vrnitev rezultatov v formatu referenc
  5. Ločevanje besedila od referenc
  6. Priprava prikaza za spletno vmesnik
  7. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi vodnika Mistral Citations & References: rezultat orodja sledi dokumentirani obliki – objektu, indeksiranemu po številki vira, brez polj type ali reference_id – in se reference_ids v odgovoru razrešijo prek str(ref_id) znotraj tega objekta. Vir: Citations & References.

Celoten potek dela za citate

Zdaj boš sestavil cevovod RAG, ki navaja svoje vire, od prvega klica API-ja do podatkovne strukture, ki jo porabi tvoje vmesnik. Imej v mislih to načelo: model nikoli sam ne pridobiva dokumentov. Samo sporoči, da potrebuje iskanje; ti to iskanje izvedeš v svoji bazi podatkov in nato vrneš izseke skupaj z njihovimi identifikatorji. Ta izmenjava proizvede odgovor, kjer je vsaka trditev povezana z realnim dokumentom.

Natančneje, celoten cikel zahteva dva klica chat.complete. Prvi sproži klic orodja; drugi ustvari citiran odgovor, ko so viri vstavljeni v zgodovino. Ta cikel bomo prikazali na preprostem primeru: notranji asistent za dokumentacijo, ki ga vprašamo o najboljših praksah za uvajanje LLM.

Opredelitev pogodbe modela v sistemskem sporočilu

Sistemsko sporočilo določa pogodbo: odgovarjaj na podlagi priloženih virov, sistematično navajaj citate in predvsem priznaj, ko informacije manjkajo, namesto da bi zapolnjeval vrzeli. Zadnji navodilo naredi razliko v proizvodnem okolju, saj se odgovori nagibajo k odstopanju pri vprašanjih, ki so v bazi dokumentacije slabo pokrita.

from mistralai.client import Mistral
import json

client = Mistral(api_key="your-api-key")

# Sistemsko sporočilo, ki spodbuja citiranje
system_message = {
    "role": "system",
    "content": (
        "You are a documentation assistant. "
        "Answer questions using the provided sources. "
        "Cite your sources systematically. "
        "If the information is not in any source, state this explicitly."
    )
}

user_message = {
    "role": "user",
    "content": "What are the best practices for deploying an LLM in production?"
}

messages = [system_message, user_message]

Deklaracija iskalnega orodja

Orodje opisuje, kako izgleda iskanje dokumentov v tvojem sistemu: tukaj preprosta funkcija search_documentation, ki sprejme besedilno poizvedbo. Prvi klic ne pričakuje napisanega odgovora; pričakuje, da model oblikuje poizvedbo, ki se mu zdi relevantna, kar te reši pisanja plasti za preoblikovanje.

reference_tool = {
    "type": "function",
    "function": {
        "name": "search_documentation",
        "description": "Searches the documentation database",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Search query"
                }
            },
            "required": ["query"]
        }
    }
}

# Prvi klic: model zahteva uporabo orodja
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Vrnitev rezultatov v formatu referenc

To je strukturni korak. Rezultati tvojega iskalnika se vrnejo v ToolMessage, katerega vsebina je referenčni objekt iz prejšnje lekcije: vsak vir ima številko ("0", "1"…), URL, naslov in izbrane izseke. To so številke, ki jih model ponovno uporabi za označevanje svojih citatov in ki jih bo tvoje spletno vmesnik kasneje razrešil v povezave.

from mistralai.client.models import ToolMessage

# Rezultati iskanja dokumentacije v formatu referenc Mistral
references = {
    "0": {
        "url": "https://docs.example.com/deployment-guide",
        "title": "LLM Deployment Guide",
        "snippets": [[
            "Always configure rate limits to protect the service.",
            "Monitor P99 latency and error rates continuously."
        ]],
        "description": None,
        "date": "2026-09-01",
        "source": "docs"
    },
    "1": {
        "url": "https://docs.example.com/security",
        "title": "AI Application Security",
        "snippets": [[
            "Filter user inputs to prevent injections.",
            "Never expose API keys on the client side."
        ]],
        "description": None,
        "date": "2026-08-15",
        "source": "docs"
    },
    "2": {
        "url": "https://docs.example.com/scaling",
        "title": "Scalability and Performance",
        "snippets": [[
            "Use semantic caching to reduce API calls.",
            "Size instances based on peak traffic."
        ]],
        "description": None,
        "date": "2026-07-20",
        "source": "docs"
    }
}

# Dodaj klic orodja in odgovor v zgodovino
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)
    )
)

Upoštevaj, da se izvirno sporočilo modela ponovno vstavi v zgodovino pred ToolMessage: brez tega para klic orodja / rezultat orodja API zavrne nadaljevanje. Drugi klic ne potrebuje več definicij orodij, saj je iskanje že potekalo.

# Drugi klic: model ustvari odgovor s citati
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Ločevanje besedila od referenc

Citiran odgovor ni več preprost niz, ampak zaporedje kosov, ki izmenjujejo prozo in oznake citatov. Razčlenjevanje vključuje prehajanje tega zaporedja in razvrščanje: objekti TextChunk rekonstruirajo berljivo besedilo, medtem ko objekti ReferenceChunk dostavijo dejansko uporabljene reference_ids. Ta razlika ti daje dragocene informacije: točno katere vire je model uporabil med tistimi, ki si jih zagotovil.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Izloči besedilo in reference iz citiranega odgovora."""
    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("=== Odgovor ===")
print(result["text"])
print("\n=== Citirani viri ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Priprava prikaza za spletno vmesnik

Sploščitev odgovora v navadno besedilo bi izgubila položaj citatov in s tem njihovo vrednost. Bolje je ohraniti zaporedje in ga obogatiti: razreši vsak ReferenceChunk glede na tabelo referenc, da preneseš naslov in URL vsakega vira. Tvoj vmesnik tako prejme urejen seznam blokov, ki jih lahko prikaže kot klikljive povezave, oblačke z napisi ali interaktivne številke citatov, ne da bi moral kdaj koli ponovno razlagati besedilo.

def format_for_frontend(response, reference_map):
    """Oblikuje odgovor s citati za spletno vmesnik."""
    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

Preden odpreš ta cevovod svoji polni bazi dokumentacije, ga zaženi le s tremi do petimi viri, kot v zgornjem primeru. Takoj boš videl, ali model citira na pravem mestu, ali izkorišča več dokumentov ali se sistematično drži prvega, kar ti omogoča, da popraviš sistemsko sporočilo, preden se obnašanje izgubi v obsegu.

Ključne ugotovitve

  • Cevovod sledi toku dveh klicev: klic orodja, nato citiran odgovor
  • Reference se posredujejo prek ToolMessage v objektu, indeksiranem po številki vira ("0", "1"…)
  • Odgovor vsebuje mešanico TextChunk in ReferenceChunk za razčlenjevanje
  • Strukturiraj izhod tako, da lahko tvoje spletno vmesnik prikaže interaktivne citate
  • Testiraj s 3–5 viri, da potrdiš obnašanje, preden preideš v proizvodno okolje