Implementēt citēšanu Python valodā
Šajā lapā
Atjaunināts 2026. gada 3. novembrī, pamatojoties uz Mistral Citēšanas un atsauces rokasgrāmatu: rīka rezultāts atbilst dokumentētajam formātam — tas ir objekts, indeksēts pēc avota numura, bez laukiem
typevaireference_id— unreference_idsatbildē tiek atrisināti, izmantojotstr(ref_id)šajā objektā. Avots: Citēšana un atsauces.
Pilns citēšanas darbplūsmas cikls
Tagad tu izveidosi RAG darbplūsmu, kas citē savus avotus, sākot no pirmā API izsaukuma līdz datu struktūrai, ko patērē tava saskarne. Paturi prātā šo principu: modelis nekad pats nefetchē dokumentus. Tas signalizē, ka tam nepieciešama meklēšana; tu veic šo meklēšanu savā datubāzē un pēc tam atgriež izrakstus kopā ar to identifikatoriem. Šī abpusējā saziņa rada atbildi, kurā katrs apgalvojums ir saistīts ar reālu dokumentu.
Konkrēti, pilns cikls prasa divus chat.complete izsaukumus. Pirmais ierosina rīka izsaukumu; otrais ģenerē citētu atbildi, kad avoti ir ievietoti vēsturē. Mēs iziesim cauri šim ciklam, izmantojot vienkāršu gadījumu: iekšējās dokumentācijas asistents, kuram jautāts par labāko praksi LLM izvietošanai.
Definē modeļa līgumu sistēmas ziņojumā
Sistēmas ziņojums nosaka līgumu: atbildi, balstoties uz sniegtajiem avotiem, sistemātiski citē un, pats galvenais, atzīsti, kad informācijas trūkst, nevis aizpildi tukšumus. Šī pēdējā instrukcija ražošanas vidē ir izšķiroša, jo atbildes mēdz novirzīties, ja jautājumi dokumentācijas bāzē ir slikti apskatīti.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Sistēmas ziņojums, kas mudina citēt
system_message = {
"role": "system",
"content": (
"Tu esi dokumentācijas asistents. "
"Atbildi uz jautājumiem, izmantojot sniegtos avotus. "
"Sistemātiski citē savus avotus. "
"Ja informācijas nevienā avotā nav, to skaidri norādi."
)
}
user_message = {
"role": "user",
"content": "Kāda ir labākā prakse LLM izvietošanai ražošanas vidē?"
}
messages = [system_message, user_message]
Deklarē meklēšanas rīku
Rīks apraksta, kā izskatās dokumentu meklēšana tavā sistēmā: šeit tā ir vienkārša funkcija search_documentation, kas pieņem teksta vaicājumu. Pirmais izsaukums negaida rakstisku atbildi; tas sagaida, ka modelis formulēs vaicājumu, ko uzskata par atbilstošu, tādējādi atbrīvojot tevi no pārfrazēšanas slāņa rakstīšanas.
reference_tool = {
"type": "function",
"function": {
"name": "search_documentation",
"description": "Meklē dokumentācijas datubāzē",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Meklēšanas vaicājums"
}
},
"required": ["query"]
}
}
}
# Pirmais izsaukums: modelis pieprasa izmantot rīku
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Atgriež rezultātus atsauces formātā
Šis ir strukturālais solis. Tava meklēšanas dzinēja rezultāti atgriežas ToolMessage formātā, kura saturs ir atsauces objekts no iepriekšējās nodarbības: katram avotam ir numurs ("0", "1"…), URL, nosaukums un atlasītie izraksti. Tie ir numuri, kurus modelis atkārtoti izmanto, lai atzīmētu savas citācijas, un kurus tava frontenda daļa vēlāk pārvērsīs saitēs.
from mistralai.client.models import ToolMessage
# Dokumentācijas meklēšanas rezultāti Mistral atsauces formātā
references = {
"0": {
"url": "https://docs.example.com/deployment-guide",
"title": "LLM izvietošanas rokasgrāmata",
"snippets": [[
"Vienmēr konfigurējiet ātruma ierobežojumus, lai aizsargātu servisu.",
"Pastāvīgi uzraugiet P99 latentumu un kļūdu rādītājus."
]],
"description": None,
"date": "2026-09-01",
"source": "docs"
},
"1": {
"url": "https://docs.example.com/security",
"title": "AI lietotņu drošība",
"snippets": [[
"Filtrējiet lietotāju ievades, lai novērstu injicēšanu.",
"Nekad neizpaudiet API atslēgas klienta pusē."
]],
"description": None,
"date": "2026-08-15",
"source": "docs"
},
"2": {
"url": "https://docs.example.com/scaling",
"title": "Mērogojamība un veiktspēja",
"snippets": [[
"Izmantojiet semantisko kešatmiņu, lai samazinātu API izsaukumus.",
"Pielāgojiet instances lielumu atbilstoši maksimālajai slodzei."
]],
"description": None,
"date": "2026-07-20",
"source": "docs"
}
}
# Pievieno rīka izsaukumu un atbildi vēsturei
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)
)
)
Ņem vērā, ka modeļa sākotnējais ziņojums tiek atkārtoti ievietots vēsturē pirms ToolMessage: bez šī rīka izsaukuma un rīka rezultāta pāra API atteiks turpinājumu. Otrajam izsaukumam vairs nav nepieciešamas rīku definīcijas, jo meklēšana jau ir veikta.
# Otrais izsaukums: modelis ģenerē atbildi ar citātēm
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Atdala tekstu no atsauces
Citētā atbilde vairs nav vienkārša virkne, bet gan fragmentu secība, kurā mainās proza un citēšanas zīmes. Parsēšana ietver šīs secības apgaitu un šķirošanu: TextChunk objekti rekonstruē lasāmo tekstu, savukārt ReferenceChunk objekti nodrošina faktiski izmantotos reference_ids. Šī atšķirība sniedz tev vērtīgu informāciju: tieši kurus avotus modelis izmantoja no tiem, ko tu nodrošināji.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Iegūst tekstu un atsauces no citētas atbildes."""
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("=== Atbilde ===")
print(result["text"])
print("\n=== Citētie avoti ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Sagatavo attēlošanu frontendā
Atbildes saplacināšana vienkāršā tekstā zaudētu citātu pozīcijas un līdz ar to to vērtību. Labāk ir saglabāt secību un to bagātināt: atrisini katru ReferenceChunk, salīdzinot to ar atsauču tabulu, lai pārnestu katra avota nosaukumu un URL. Tava saskarne tādējādi saņem sakārtotu bloku sarakstu, ko tā var attēlot kā noklikšķināmas saites, rīka padomus vai interaktīvus citātu numurus, nekad nepārinterpretējot tekstu.
def format_for_frontend(response, reference_map):
"""Formatē atbildi ar citātēm frontendam."""
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
Pirms atver šo darbplūsmu visai savai dokumentācijas bāzei, palaid to tikai ar trim līdz pieciem avotiem, kā tas ir parādīts iepriekšējā piemērā. Tu uzreiz redzēsi, vai modelis citē pareizajā vietā, vai tas izmanto vairākus dokumentus, vai arī sistemātiski pieturas pie pirmā, ļaujot tev labot sistēmas ziņojumu, pirms uzvedība pazūd lielos apjomos.
Galvenās atziņas
- Darbplūsma seko divu izsaukumu plūsmai: rīka izsaukums, pēc tam citēta atbilde
- Atsauces tiek nodotas caur
ToolMessageobjektā, kas indeksēts pēc avota numura ("0","1"…) - Atbilde satur
TextChunkunReferenceChunkjaukumu, kas jāparsē - Strukturē izeju tā, lai tavs frontends varētu attēlot interaktīvas citācijas
- Testē ar 3–5 avotiem, lai validētu uzvedību pirms pārejas uz ražošanas vidi