Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Implementiraj citate u Pythonu

Lekcija 9 od 16 Ažurirano 3. studenoga 2026. Napredno
Na ovoj stranici
  1. Cjeloviti pipeline za citate
  2. Definiraj ugovor modela u sistemskoj poruci
  3. Deklariraj alat za pretragu
  4. Vrati rezultate u formatu reference
  5. Odvoji tekst od referenci
  6. Pripremi prikaz na frontendu
  7. Ključne točke

Ažurirano 3. studenoga 2026. na temelju vodiča Mistral Citations & References: rezultat alata prati dokumentirani format—objekt indeksiran brojem izvora, bez polja type ili reference_id—a reference_ids u odgovoru razrješavaju se putem str(ref_id) unutar tog objekta. Izvor: Citations & References.

Cjeloviti pipeline za citate

Sada ćeš sastaviti RAG pipeline koji citira svoje izvore, od prvog API poziva do podatkovne strukture koju tvoje sučelje troši. Imaj na umu ovaj princip: model nikada sam ne dohvaća dokumente. On signalizira da treba pretragu, ti tu pretragu izvršiš u svojoj bazi podataka, a zatim vraćaš isječke zajedno s njihovim identifikatorima. Ta razmjena proizvodi odgovor u kojem svaka tvrdnja ostaje vezana uz stvarni dokument.

Konkretno, puni ciklus zahtijeva dva poziva funkciji chat.complete. Prvi pokreće poziv alata; drugi generira odgovor s citatima jednom kada se izvori ubace u povijest. Proći ćemo kroz ovaj ciklus koristeći jednostavan slučaj: asistenta za internu dokumentaciju kojeg pitaš o najboljim praksama za deploy LLM-a.

Definiraj ugovor modela u sistemskoj poruci

Sistemska poruka postavlja ugovor: odgovaraj na temelju priloženih izvora, sustavno citiraj i, iznad svega, priznaj kada informacija nedostaje umjesto da popunjavaš prazninu. Ova zadnja uputa čini razliku u produkciji jer odgovori imaju tendenciju skretanja kod pitanja koja su slabo pokrivena bazom dokumentacije.

from mistralai.client import Mistral
import json

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

# Sistemska poruka koja potiče 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]

Deklariraj alat za pretragu

Alat opisuje kako izgleda pretraga dokumenata u tvom sustavu: ovdje je to jednostavna funkcija search_documentation koja prima tekstualni upit. Prvi poziv ne očekuje pisani odgovor; očekuje da model formulira upit koji smatra relevantnim, štedeći ti pisanje sloja za reformulaciju.

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 poziv: model traži korištenje alata
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Vrati rezultate u formatu reference

Ovo je strukturni korak. Rezultati tvog tražilice vraćaju se u ToolMessage čiji je sadržaj referentni objekt iz prethodne lekcije: svaki izvor ima broj ("0", "1"…), URL, naslov i odabrane isječke. To su brojeve koje model ponovno koristi za označavanje svojih citata, a koje će tvoje frontend sučelje kasnije razriješiti u poveznice.

from mistralai.client.models import ToolMessage

# Rezultati pretrage dokumentacije, u Mistral referentnom formatu
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 poziv alata i odgovor u povijest
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)
    )
)

Imaj na umu da se izvorna poruka modela ponovno ubacuje u povijest prije ToolMessage: bez ovog para poziv alata / rezultat alata, API odbija nastavak. Drugi poziv više ne treba definicije alata jer je pretraga već obavljena.

# Drugi poziv: model generira odgovor s citatima
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Odvoji tekst od referenci

Odgovor s citatima više nije jednostavan niz znakova, već niz dijelova koji izmjenjuju prozu i oznake citata. Parsiranje uključuje prolazak kroz ovaj niz i sortiranje: objekti TextChunk rekonstruiraju čitljivi tekst, dok objekti ReferenceChunk dostavljaju stvarne reference_ids koji su korišteni. Ova razlika daje ti vrijedne informacije: točno koje je izvore model koristio među onima koje si mu pružio.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Izvlači tekst i reference iz odgovora s citatima."""
    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 izvori ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Pripremi prikaz na frontendu

Izravnavanje odgovora u običan tekst izgubilo bi poziciju citata, a time i njihovu vrijednost. Bolje je zadržati niz i obogatiti ga: razriješi svaki ReferenceChunk prema tablici referenci kako bi se prenijeli naslov i URL svakog izvora. Tvoje sučelje tako prima uređeni popis blokova koje može renderirati kao poveznice na koje se može kliknuti, alatne savjete ili interaktivne brojeve citata, bez potrebe da ikada ponovno tumači tekst.

def format_for_frontend(response, reference_map):
    """Formatira odgovor s citatima za 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

Prije nego što ovaj pipeline otvoriš svojoj punoj bazi dokumentacije, pokreni ga sa samo tri do pet izvora, kao u gornjem primjeru. Odmah ćeš vidjeti citira li model na pravom mjestu, koristi li više dokumenata ili se sustavno drži prvog, što ti omogućuje ispravak sistemske poruke prije nego se ponašanje izgubi u volumenu.

Ključne točke

  • Pipeline slijedi tok s dva poziva: poziv alata, zatim odgovor s citatima
  • Reference se prosljeđuju putem ToolMessage, u objektu indeksiranom brojem izvora ("0", "1"…)
  • Odgovor sadrži mješavinu TextChunk i ReferenceChunk za parsiranje
  • Strukturiraj izlaz tako da tvoj frontend može prikazati interaktivne citate
  • Testiraj s 3–5 izvora kako bi validirao ponašanje prije prelaska u produkciju