Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Implementácia citácií v Pythone

Lekcia 9 z 16 Aktualizované 3. novembra 2026 Pokročilý
Na tejto strane
  1. Kompletný pipeline citácií
  2. Definovanie kontraktu modelu v systémovej správe
  3. Deklarácia nástroja na vyhľadávanie
  4. Vrátanie výsledkov vo formáte referencií
  5. Oddelenie textu od referencií
  6. Príprava zobrazenia pre frontend
  7. Kľúčové poznatky

Aktualizované 3. novembra 2026 na základe príručky Mistral Citations & References: výsledok nástroja dodržiava zdokumentovaný formát – objekt indexovaný číslom zdroja bez polí type alebo reference_id – a reference_ids v odpovedi sa riešia pomocou str(ref_id) v rámci tohto objektu. Zdroj: Citations & References.

Kompletný pipeline citácií

Teraz zostavíš pipeline RAG, ktorý cituje svoje zdroje, od prvého volania API až po dátovú štruktúru, ktorú spotrebúva tvoje rozhranie. Maj na pamäti tento princíp: model nikdy sám nevyhľadáva dokumenty. Len signalizuje, že potrebuje vyhľadávanie, ty toto vyhľadávanie vykonáš vo svojej vlastnej databáze a následne vrátiš úryvky spolu s ich identifikátormi. Táto interakcia vytvára odpoveď, kde každé tvrdenie zostáva viazané na reálny dokument.

Konkrétne si celý cyklus vyžaduje dve volania chat.complete. Prvé spustí volanie nástroja; druhé vygeneruje citovanú odpoveď po vložení zdrojov do histórie. Prejdeme si tento cyklus na jednoduchom prípade: asistent pre internú dokumentáciu, ktorého sa opýtate na osvedčené postupy pri nasadzovaní LLM.

Definovanie kontraktu modelu v systémovej správe

Systémová správa stanovuje kontrakt: odpovedaj na základe poskytnutých zdrojov, systematicky cituj a predovšetkým priznaj, keď informácie chýbajú, namiesto toho, aby si medzeru vypĺňal vymyslenými údajmi. Práve tento posledný pokyn robí v produkcii rozdiel, pretože odpovede majú tendenciu sa odkláňať od pravdy pri otázkach, ktoré sú v databáze dokumentácie slabo pokryté.

from mistralai.client import Mistral
import json

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

# Systémová správa podporujúca citácie
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]

Deklarácia nástroja na vyhľadávanie

Nástroj opisuje, ako vyzerá vyhľadávanie dokumentov vo tvojom systéme: tu ide o jednoduchú funkciu search_documentation prijímajúcu textový dopyt. Prvé volanie neočakáva písomnú odpoveď; očakáva, že model sformuluje dopyt, ktorý považuje za relevantný, čím ťa ušetrí od písania vrstvy na preformulovanie.

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"]
        }
    }
}

# Prvé volanie: model požiada o použitie nástroja
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Vrátanie výsledkov vo formáte referencií

Toto je štrukturálny krok. Výsledky tvojho vyhľadávacieho engine sa vrátia v ToolMessage, ktorého obsahom je referenčný objekt z predchádzajúcej lekcie: každý zdroj má číslo ("0", "1"…), URL, názov a vybrané úryvky. Práve tieto čísla model znovu použije na označenie svojich citácií a ktoré tvoje frontendové rozhranie následne prevedie na odkazy.

from mistralai.client.models import ToolMessage

# Výsledky vyhľadávania v dokumentácii vo formáte referencií 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"
    }
}

# Pridanie volania nástroja a odpovede do histórie
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)
    )
)

Všimni si, že pôvodná správa modelu sa pred ToolMessage opäť vloží do histórie: bez tohto páru volanie nástroja / výsledok nástroja API odmietne pokračovanie. Druhé volanie už nepotrebuje definície nástrojov, keďže vyhľadávanie už prebehlo.

# Druhé volanie: model vygeneruje odpoveď s citáciami
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Oddelenie textu od referencií

Citovaná odpoveď už nie je jednoduchý reťazec, ale sekvencia chunkov striedajúcich prózu a značky citácií. Parsovanie zahŕňa prechod touto sekvenciou a triedenie: objekty TextChunk rekonštruujú čitateľný text, zatiaľ čo objekty ReferenceChunk dodávajú skutočne použité reference_ids. Toto rozlíšenie ti poskytuje cenné informácie: presne ktoré zdroje model použil z tých, ktoré si mu poskytol.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Extrahuje text a referencie z citovanej odpovede."""
    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("=== Odpoveď ===")
print(result["text"])
print("\n=== Citované zdroje ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Príprava zobrazenia pre frontend

Sploštenie odpovede na obyčajný text by stratilo pozíciu citácií, a tým aj ich hodnotu. Je lepšie zachovať sekvenciu a obohatiť ju: vyrieš každý ReferenceChunk proti tabuľke referencií, aby si preniesol názov a URL každého zdroja. Tvoje rozhranie tak dostane usporiadaný zoznam blokov, ktoré môže vykresliť ako klikateľné odkazy, bublinové nápovedy alebo interaktívne čísla citácií, bez toho, aby muselo text znovu interpretovať.

def format_for_frontend(response, reference_map):
    """Formátuje odpoveď s citáciami pre 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

Predtým, než tento pipeline otvoríš celej svojej databáze dokumentácie, spusti ho len s tromi až piatimi zdrojmi, ako v príklade vyššie. Okamžite uvidíš, či model cituje na správnom mieste, či využíva viacero dokumentov, alebo či sa systematicky drží toho prvého, čo ti umožní opraviť systémovú správu skôr, než sa toto správanie stratí v objeme dát.

Kľúčové poznatky

  • Pipeline nasleduje tok dvoch volaní: volanie nástroja a následne citovaná odpoveď
  • Referencie sa odovzdávajú cez ToolMessage v objekte indexovanom číslom zdroja ("0", "1"…)
  • Odpoveď obsahuje zmes TextChunk a ReferenceChunk na parsovanie
  • Štruktúruj výstup tak, aby tvoj frontend mohol zobrazovať interaktívne citácie
  • Testuj s 3–5 zdrojmi na overenie správania pred nasadením do produkcie