Implementare le citazioni in Python
In questa pagina
Aggiornato il 3 novembre 2026 sulla base della guida Citations & References di Mistral: il risultato dello strumento segue il formato documentato—un oggetto indicizzato per numero di fonte, senza campi
typeoreference_id—e ireference_idsnella risposta vengono risolti tramitestr(ref_id)all’interno di quell’oggetto. Fonte: Citations & References.
La pipeline completa delle citazioni
Ora assemblerai una pipeline RAG che cita le proprie fonti, dalla prima chiamata API alla struttura dati consumata dalla tua interfaccia. Tieni a mente questo principio: il modello non recupera mai i documenti da solo. Segnala che ha bisogno di una ricerca, tu esegui quella ricerca nel tuo database e poi restituisci gli estratti insieme ai loro identificativi. Questo scambio produce una risposta in cui ogni affermazione rimane legata a un documento reale.
Nello specifico, un ciclo completo richiede due chiamate a chat.complete. La prima attiva la chiamata allo strumento; la seconda genera la risposta citata una volta che le fonti sono state inserite nella cronologia. Analizzeremo questo ciclo utilizzando un caso semplice: un assistente per la documentazione interna interrogato sulle migliori pratiche per il deploy di un LLM.
Definire il contratto del modello nel messaggio di sistema
Il messaggio di sistema stabilisce il contratto: rispondere basandosi sulle fonti fornite, citare sistematicamente e, soprattutto, ammettere quando le informazioni mancano invece di colmare il vuoto. Quest’ultima istruzione fa la differenza in produzione, perché le risposte tendono a divagare su domande poco coperte dalla base documentale.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Messaggio di sistema che incoraggia le citazioni
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]
Dichiarare lo strumento di ricerca
Lo strumento descrive come appare una ricerca documentale nel tuo sistema: qui, una semplice funzione search_documentation che accetta una query testuale. La prima chiamata non si aspetta una risposta scritta; si aspetta che il modello formuli la query che ritiene rilevante, risparmiandoti la scrittura di un livello di riformulazione.
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"]
}
}
}
# Prima chiamata: il modello richiede di utilizzare lo strumento
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Restituire i risultati nel formato di riferimento
Questo è il passo strutturale. I risultati del tuo motore di ricerca tornano in un ToolMessage il cui contenuto è l’oggetto di riferimento visto nella lezione precedente: ogni fonte ha un numero ("0", "1"…), un URL, un titolo e gli estratti selezionati. Questi sono i numeri che il modello riutilizza per segnare le sue citazioni e che il tuo frontend risolverà successivamente in link.
from mistralai.client.models import ToolMessage
# Risultati della ricerca documentale, nel formato di riferimento 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"
}
}
# Aggiungere la chiamata allo strumento e la risposta alla cronologia
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)
)
)
Nota che il messaggio originale del modello viene reinserito nella cronologia prima del ToolMessage: senza questa coppia chiamata allo strumento / risultato dello strumento, l’API rifiuta la continuazione. La seconda chiamata non ha più bisogno delle definizioni degli strumenti, poiché la ricerca è già avvenuta.
# Seconda chiamata: il modello genera una risposta con citazioni
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Separare il testo dai riferimenti
La risposta citata non è più una semplice stringa, ma una sequenza di chunk che alternano prosa e marcatori di citazione. L’analisi comporta l’attraversamento di questa sequenza e l’ordinamento: gli oggetti TextChunk ricostruiscono il testo leggibile, mentre gli oggetti ReferenceChunk forniscono i reference_ids effettivamente utilizzati. Questa distinzione ti offre informazioni preziose: esattamente quali fonti il modello ha usato tra quelle che hai fornito.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Estrae testo e riferimenti da una risposta citata."""
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("=== Risposta ===")
print(result["text"])
print("\n=== Fonti citate ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Preparare la visualizzazione frontend
Appiattire la risposta in testo semplice farebbe perdere la posizione delle citazioni e, di conseguenza, il loro valore. È meglio mantenere la sequenza e arricchirla: risolvere ogni ReferenceChunk rispetto a una tabella di riferimento per portare il titolo e l’URL di ogni fonte. La tua interfaccia riceve così una lista ordinata di blocchi che può renderizzare come link cliccabili, tooltip o numeri di citazione interattivi, senza dover mai reinterpretare il testo.
def format_for_frontend(response, reference_map):
"""Formatta la risposta con citazioni per il 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
Prima di aprire questa pipeline alla tua intera base documentale, eseguila con solo tre-cinque fonti, come nell’esempio sopra. Vedrai immediatamente se il modello cita nel punto giusto, se sfrutta più documenti o se si aggrappa sistematicamente al primo, permettendoti di correggere il messaggio di sistema prima che il comportamento vada perso nel volume.
Punti chiave
- La pipeline segue un flusso a due chiamate: chiamata allo strumento, poi risposta citata
- I riferimenti vengono passati tramite
ToolMessage, in un oggetto indicizzato per numero di fonte ("0","1"…) - La risposta contiene un mix di
TextChunkeReferenceChunkda analizzare - Struttura l’output in modo che il tuo frontend possa visualizzare citazioni interattive
- Esegui test con 3–5 fonti per convalidare il comportamento prima di passare alla produzione