Implementacija citatov v Pythonu
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi vodnika Mistral Citations & References: rezultat orodja sledi dokumentirani obliki – objektu, indeksiranemu po številki vira, brez polj
typealireference_id– in sereference_idsv odgovoru razrešijo prekstr(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
ToolMessagev objektu, indeksiranem po številki vira ("0","1"…) - Odgovor vsebuje mešanico
TextChunkinReferenceChunkza 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