Teosta tsiteerimine Pythonis
Sellel lehel
Uuendatud 3. novembril 2026, tuginedes Mistrali Citations & References juhendile: tööriista tulemus järgib dokumenteeritud vormingut – objekt, mis on indekseeritud allika numbri järgi, ilma väljadeta
typevõireference_id– ning vastuses olevadreference_idslahendatakse selle objekti sees kasutadesstr(ref_id). Allikas: Citations & References.
Terve tsiteerimise torustik
Nüüd paned kokku RAG-torustiku, mis tsiteerib oma allikaid, alates esimesest API-kutsust kuni andmestruktuurini, mida sinu liides tarbib. Pidage meeles seda põhimõtet: mudel ise dokumente ei hangita. See annab märku, et vajab otsingut; sina teostad selle otsingu oma andmebaasis ja seejärel tagastad lõigud koos nende identifikaatoritega. See edasi-tagasi suhtlus loob vastuse, kus iga väide jääb seotuks reaalse dokumendiga.
Täpsemalt öeldes nõuab täielik tsükkel kahte chat.complete väljakutset. Esimene käivitab tööriista kutse; teine genereerib tsiteeritud vastuse, kui allikad on ajaloosse sisestatud. Käime selle tsükli läbi lihtsa näite varal: sisene dokumentatsiooniassistent, kellelt küsitakse LLM-i kasutuselevõtu parimaid tavasid.
Määratle mudeli leping süsteemsõnumis
Süsteemsõnum seab lepingu: vasta pakutud allikate põhjal, tsiteeri süstemaatiliselt ja mis kõige tähtsam – tunnistage, kui teave puudub, selle asemel et lünki välja mõelda. See viimane juhiste osa teeb tootmises vahet, sest vastused kipuvad kalduma kõrvale küsimustes, mida dokumentatsiooni baas halvasti kajastab.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Tsiteerimist soodustav süsteemsõnum
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]
Määratle otsingutööriist
Tööriist kirjeldab, kuidas dokumentide otsing sinu süsteemis välja näeb: siin lihtne funktsioon search_documentation, mis võtab vastu tekstipäringu. Esimene väljakutse ei oota kirjalikku vastust; see ootab, et mudel formuleeriks päringu, mida ta peab asjakohaseks, säästes sind ümberformuleerimise kihi kirjutamisest.
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"]
}
}
}
# Esimene väljakutse: mudel taotleb tööriista kasutamist
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Tagasta tulemused viitevormingus
See on struktuurne samm. Sinu otsingumootori tulemused saabuvad ToolMessage’ina, mille sisuks on eelmises õppetükis käsitletud viiteobjekt: igal allikal on number ("0", "1"…), URL, pealkiri ja valitud lõigud. Need on numbrid, mida mudel kasutab oma tsiteeringute märkimiseks ja mida sinu kasutajaliides hiljem linkideks lahendab.
from mistralai.client.models import ToolMessage
# Dokumentatsiooni otsingutulemused Mistrali viitevormingus
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"
}
}
# Lisa tööriista kutse ja vastus ajaloosse
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)
)
)
Pane tähele, et mudeli algne sõnum sisestatakse ajaloossa uuesti enne ToolMessage’i: ilma selle tööriista kutse ja tulemuse paarita keeldub API jätkamisest. Teine väljakutse ei vaja enam tööriista definitsioone, kuna otsing on juba toimunud.
# Teine väljakutse: mudel genereerib tsiteeringutega vastuse
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Eralda tekst viidetest
Tsiteeritud vastus ei ole enam lihtne string, vaid jadade jada, kus vahelduvad proosa ja tsiteerimismärgid. Parsimine hõlmab selle jada läbimist ja sorteerimist: TextChunk objektid rekonstrueerivad loetava teksti, samas kui ReferenceChunk objektid edastavad tegelikult kasutatud reference_ids. See eristus annab sulle väärtuslikku teavet: täpselt milliseid allikaid mudel sinu pakututest kasutas.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Eemaldab teksti ja viited tsiteeritud vastusest."""
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("=== Vastus ===")
print(result["text"])
print("\n=== Tsiteeritud allikad ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Valmista ette kasutajaliidese kuva
Vastuse lamestamine lihttekstiks kaotaks tsiteeringute asukoha ja seeläbi ka nende väärtuse. Parem on jada säilitada ja seda rikastada: lahenda iga ReferenceChunk viitetabeli vastu, et kaasata iga allika pealkiri ja URL. Sinu liides saab seega järjestatud plokkide loendi, mida saab renderdada klõpsatavate linkidena, tööriistadena või interaktiivsete tsiteerimisnumbritena, ilma et peaks teksti kunagi uuesti tõlgendama.
def format_for_frontend(response, reference_map):
"""Vormindab vastuse tsiteeringutega kasutajaliidese jaoks."""
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
Enne kui avad selle torustiku kogu oma dokumentatsiooni baasile, käivita see vaid kolme kuni viie allikaga, nagu ülaltoodud näites. Näed kohe, kas mudel tsiteerib õiges kohas, kas ta kasutab mitut dokumenti või kas ta jääb süstemaatiliselt kinni esimesse, võimaldades sul süsteemsõnumit parandada enne, kui käitumine suure mahuga kaduma läheb.
Peamised punktid
- Torustik järgib kahe väljakutse voogu: tööriista kutse, seejärel tsiteeritud vastus
- Viidetakse edasi
ToolMessagekaudu objektina, mis on indekseeritud allika numbri järgi ("0","1"…) - Vastus sisaldab segamini
TextChunkjaReferenceChunkobjekte, mida tuleb parsida - Struktureeri väljund nii, et sinu kasutajaliides saaks kuvada interaktiivseid tsiteeringuid
- Testi 3–5 allikaga, et käitumist enne tootmisse viimist valideerida