Implementarea citărilor în Python
Pe această pagină
Actualizat la 3 noiembrie 2026 pe baza ghidului Mistral Citations & References: rezultatul instrumentului respectă formatul documentat—un obiect indexat după numărul sursei, fără câmpurile
typesaureference_id—iarreference_idsdin răspuns se rezolvă prinstr(ref_id)în cadrul acelui obiect. Sursă: Citations & References.
Fluxul complet de citare
Veți asambla acum un pipeline RAG care își citează sursele, de la primul apel API până la structura de date consumată de interfața dumneavoastră. Rețineți acest principiu fundamental: modelul nu preia niciodată documente direct. El semnalează că are nevoie de o căutare, dumneavoastră executați acea căutare în propria bază de date, iar apoi returnați extrasele împreună cu identificatorii lor. Acest schimb produce un răspuns în care fiecare afirmație rămâne legată de un document real.
Mai exact, un ciclu complet necesită două apeluri către chat.complete. Primul declanșează apelul instrumentului; al doilea generează răspunsul citat odată ce sursele sunt injectate în istoric. Vom parcurge acest ciclu folosind un caz simplu: un asistent de documentație internă întrebat despre cele mai bune practici pentru implementarea unui LLM.
Definirea contractului modelului în mesajul de sistem
Mesajul de sistem stabilește contractul: răspundeți pe baza surselor furnizate, citați sistematic și, mai presus de toate, admiteți când informațiile lipsesc, în loc să completați golurile. Această ultimă instrucțiune face diferența în producție, deoarece răspunsurile tind să devieze la întrebările acoperite insuficient de baza de documentație.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Mesaj de sistem care încurajează citările
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]
Declararea instrumentului de căutare
Instrumentul descrie cum arată o căutare de documente în sistemul dumneavoastră: aici, o funcție simplă search_documentation care primește o interogare text. Primul apel nu se așteaptă la un răspuns scris; se așteaptă ca modelul să formuleze interogarea pe care o consideră relevantă, scutindu-vă de scrierea unui strat de reformulare.
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"]
}
}
}
# Primul apel: modelul solicită utilizarea instrumentului
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Returnarea rezultatelor în format de referință
Acesta este pasul structural. Rezultatele motorului de căutare revin într-un ToolMessage al cărui conținut este obiectul de referință din lecția anterioară: fiecare sursă are un număr ("0", "1"…), un URL, un titlu și extrasele selectate. Acestea sunt numerele pe care modelul le reutilizează pentru a-și marca citările și pe care frontend-ul dumneavoastră le va rezolva ulterior în link-uri.
from mistralai.client.models import ToolMessage
# Rezultatele căutării în documentație, în formatul de referință 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"
}
}
# Adăugarea apelului instrumentului și a răspunsului în istoric
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)
)
)
Rețineți că mesajul original al modelului este reinjectat în istoric înainte de ToolMessage: fără această pereche apel instrument / rezultat instrument, API-ul refuză continuarea. Al doilea apel nu mai are nevoie de definițiile instrumentelor, deoarece căutarea a avut deja loc.
# Al doilea apel: modelul generează un răspuns cu citări
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Separarea textului de referințe
Răspunsul citat nu mai este un simplu șir de caractere, ci o secvență de fragmente alternând proza și marcatorii de citare. Analiza implică parcurgerea acestei secvențe și sortarea: obiectele TextChunk reconstruiesc textul lizibil, în timp ce obiectele ReferenceChunk livrează reference_ids utilizați efectiv. Această distincție vă oferă informații valoroase: exact sursele pe care modelul le-a utilizat dintre cele furnizate de dumneavoastră.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Extrage textul și referințele dintr-un răspuns citat."""
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("=== Răspuns ===")
print(result["text"])
print("\n=== Surse citate ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Pregătirea afișării în frontend
Aplatizarea răspunsului în text simplu ar duce la pierderea poziției citărilor și, prin urmare, a valorii lor. Este mai bine să păstrați secvența și să o îmbogățiți: rezolvați fiecare ReferenceChunk față de un tabel de referințe pentru a transporta titlul și URL-ul fiecărei surse. Interfața dumneavoastră primește astfel o listă ordonată de blocuri pe care le poate reda ca link-uri clicabile, tooltip-uri sau numere de citare interactive, fără a fi nevoită să reinterpreteze vreodată textul.
def format_for_frontend(response, reference_map):
"""Formatează răspunsul cu citări pentru 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
Înainte de a deschide acest pipeline către întreaga bază de documentație, rulați-l cu doar trei până la cinci surse, ca în exemplul de mai sus. Veți vedea imediat dacă modelul citează la locul potrivit, dacă valorifică mai multe documente sau dacă se agață sistematic de prima, permițându-vă să corectați mesajul de sistem înainte ca comportamentul să se piardă în volum.
Puncte cheie
- Pipeline-ul urmează un flux cu două apeluri: apelul instrumentului, apoi răspunsul citat
- Referințele sunt transmise prin
ToolMessage, într-un obiect indexat după numărul sursei ("0","1"…) - Răspunsul conține un amestec de
TextChunkșiReferenceChunkde analizat - Structurați ieșirea astfel încât frontend-ul să poată afișa citări interactive
- Testați cu 3–5 surse pentru a valida comportamentul înainte de a trece la producție