Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Implementace citací v Pythonu

Lekce 9 z 16 Aktualizováno 3. listopadu 2026 Pokročilý
Na této stránce
  1. Kompletní pipeline pro citace
  2. Definice kontraktu modelu v systémové zprávě
  3. Deklarace vyhledávacího nástroje
  4. Vrácení výsledků ve formátu referencí
  5. Oddělení textu od referencí
  6. Příprava zobrazení na frontendu
  7. Klíčové poznatky

Aktualizováno 3. listopadu 2026 na základě příručky Mistral Citations & References: výsledek nástroje odpovídá zdokumentovanému formátu – objekt indexovaný číslem zdroje bez polí type nebo reference_id – a reference_ids v odpovědi se řeší pomocí str(ref_id) uvnitř tohoto objektu. Zdroj: Citations & References.

Kompletní pipeline pro citace

Nyní sestavíš RAG pipeline, která cituje své zdroje, od prvního volání API až po datovou strukturu, kterou spotřebovává tvé rozhraní. Měj na paměti tento princip: model nikdy sám nefetchuje dokumenty. Pouze signalizuje, že potřebuje vyhledávání, ty toto vyhledávání provedeš ve své vlastní databázi a následně vrátíš úryvky spolu s jejich identifikátory. Tato interakce vytváří odpověď, kde každé tvrzení zůstává svázáno s reálným dokumentem.

Konkrétně vyžaduje úplný cyklus dvě volání chat.complete. První spustí volání nástroje; druhé vygeneruje citovanou odpověď, jakmile jsou zdroje vloženy do historie. Projdeme si tento cyklus na jednoduchém příkladu: interní asistent pro dokumentaci dotázaný na osvědčené postupy pro nasazení LLM.

Definice kontraktu modelu v systémové zprávě

Systémová zpráva stanovuje kontrakt: odpovídej na základě poskytnutých zdrojů, systematicky cituj a především přiznej, když informace chybí, místo abys mezeru vyplňoval. Právě tento poslední pokyn dělá v produkci rozdíl, protože odpovědi mají tendenci se odchýlit u otázek, které jsou v databázi dokumentace špatně pokryty.

from mistralai.client import Mistral
import json

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

# Systémová zpráva podporující citace
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]

Deklarace vyhledávacího nástroje

Nástroj popisuje, jak vypadá vyhledávání dokumentů ve tvém systému: zde jednoduchá funkce search_documentation přijímající textový dotaz. První volání neočekává písemnou odpověď; očekává, že model formuluje dotaz, který považuje za relevantní, čímž tě ušetří psaní vrstvy pro přeformulování.

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

# První volání: model požádá o použití nástroje
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Vrácení výsledků ve formátu referencí

Toto je strukturální krok. Výsledky tvého vyhledávacího stroje se vrátí v ToolMessage, jehož obsahem je referenční objekt z předchozí lekce: každý zdroj má číslo ("0", "1"…), URL, název a vybrané úryvky. Právě tato čísla model znovu použije k označení svých citací a které tvé frontend následně převede na odkazy.

from mistralai.client.models import ToolMessage

# Výsledky vyhledávání v dokumentaci ve formátu reference 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"
    }
}

# Přidání volání nástroje a odpovědi do historie
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í zpráva modelu je znovu vložena do historie před ToolMessage: bez tohoto páru volání nástroje / výsledku nástroje API pokračování odmítne. Druhé volání již nepotřebuje definice nástrojů, protože vyhledávání již proběhlo.

# Druhé volání: model vygeneruje odpověď s citacemi
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Oddělení textu od referencí

Citovaná odpověď již není jednoduchý řetězec, ale sekvence chunků střídajících prózu a značky citací. Parsování zahrnuje průchod touto sekvencí a třídění: objekty TextChunk rekonstruují čitelný text, zatímco objekty ReferenceChunk dodávají skutečně použité reference_ids. Toto rozlišení ti poskytuje cenné informace: přesně které zdroje model mezi těmi, které jsi poskytl, použil.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Extrahuje text a reference z citované odpovědi."""
    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("=== Odpověď ===")
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']}")

Příprava zobrazení na frontendu

Zploštění odpovědi na prostý text by ztratilo pozici citací, a tím i jejich hodnotu. Lepší je zachovat sekvenci a obohatit ji: vyřeš každý ReferenceChunk proti tabulce referencí, abys přenesl název a URL každého zdroje. Tvé rozhraní tak obdrží uspořádaný seznam bloků, které může vykreslit jako klikatelné odkazy, tooltipy nebo interaktivní čísla citací, aniž by muselo text znovu interpretovat.

def format_for_frontend(response, reference_map):
    """Formátuje odpověď s citacemi pro 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

Než tuto pipeline otevřeš své celé databázi dokumentace, spusť ji pouze se třemi až pěti zdroji, jako v příkladu výše. Okamžitě uvidíš, zda model cituje na správném místě, zda využívá více dokumentů, nebo zda se systematicky drží toho prvního, což ti umožní opravit systémovou zprávu dříve, než se toto chování ztratí v objemu dat.

Klíčové poznatky

  • Pipeline následuje tok dvou volání: volání nástroje, poté citovaná odpověď
  • Reference jsou předávány přes ToolMessage v objektu indexovaném číslem zdroje ("0", "1"…)
  • Odpověď obsahuje směs TextChunk a ReferenceChunk k parsování
  • Strukturovej výstup tak, aby tvůj frontend mohl zobrazit interaktivní citace
  • Otestuj chování se 3–5 zdroji před nasazením do produkce