Υλοποίηση Παραπομπών σε Python
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026 με βάση τον οδηγό Citations & References της Mistral: το αποτέλεσμα του εργαλείου ακολουθεί την τεκμηριωμένη μορφή—ένα αντικείμενο με ευρετήριο τον αριθμό πηγής, χωρίς πεδία
typeήreference_id—και ταreference_idsστην απάντηση επιλύονται μέσωstr(ref_id)εντός αυτού του αντικειμένου. Πηγή: Citations & References.
Ο Πλήρης Αγωγός Παραπομπών
Θα συναρμολογήσετε τώρα έναν αγωγό RAG που παραπέμπει στις πηγές του, από την πρώτη κλήση API έως τη δομή δεδομένων που καταναλώνει η διεπαφή σας. Κρατήστε αυτή την αρχή στο μυαλό σας: το μοντέλο δεν ανακτά ποτέ έγγραφα μόνο του. Σηματοδοτεί ότι χρειάζεται μια αναζήτηση, εσείς εκτελείτε αυτή την αναζήτηση στη δική σας βάση δεδομένων και στη συνέχεια επιστρέφετε τα αποσπάσματα μαζί με τα αναγνωριστικά τους. Αυτή η αλληλεπίδραση παράγει μια απάντηση όπου κάθε ισχυρισμός παραμένει δεσμευμένος με ένα πραγματικό έγγραφο.
Συγκεκριμένα, ένας πλήρης κύκλος απαιτεί δύο κλήσεις στο chat.complete. Η πρώτη ενεργοποιεί την κλήση του εργαλείου· η δεύτερη παράγει την απάντηση με παραπομπές μόλις οι πηγές εισαχθούν στο ιστορικό. Θα αναλύσουμε αυτόν τον κύκλο χρησιμοποιώντας μια απλή περίπτωση: έναν βοηθό εσωτερικής τεκμηρίωσης στον οποίο ζητούνται βέλτιστες πρακτικές για την ανάπτυξη ενός LLM.
Ορισμός της Σύμβασης Μοντέλου στο Μήνυμα Συστήματος
Το μήνυμα συστήματος ορίζει τη σύμβαση: απαντήστε με βάση τις παρεχόμενες πηγές, κάντε συστηματικές παραπομπές και, πάνω απ’ όλα, παραδεχτείτε όταν λείπουν πληροφορίες αντί να καλύψετε το κενό. Αυτή η τελευταία οδηγία κάνει τη διαφορά στην παραγωγή, καθώς οι απαντήσεις τείνουν να αποκλίνουν σε ερωτήσεις που καλύπτονται ελάχιστα από τη βάση τεκμηρίωσης.
from mistralai.client import Mistral
import json
client = Mistral(api_key="your-api-key")
# Μήνυμα συστήματος που ενθαρρύνει τις παραπομπές
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]
Δήλωση του Εργαλείου Αναζήτησης
Το εργαλείο περιγράφει πώς μοιάζει μια αναζήτηση εγγράφων στο σύστημά σας: εδώ, μια απλή συνάρτηση search_documentation που δέχεται ένα ερώτημα κειμένου. Η πρώτη κλήση δεν αναμένει μια γραπτή απάντηση· αναμένει το μοντέλο να διατυπώσει το ερώτημα που θεωρεί σχετικό, γλιτώνοντάς σας από τη συγγραφή ενός επιπέδου αναδιατύπωσης.
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"]
}
}
}
# Πρώτη κλήση: το μοντέλο ζητά τη χρήση του εργαλείου
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=[reference_tool]
)
Επιστροφή Αποτελεσμάτων σε Μορφή Αναφοράς
Αυτό είναι το δομικό βήμα. Τα αποτελέσματα της μηχανής αναζήτησης επιστρέφουν σε ένα ToolMessage του οποίου το περιεχόμενο είναι το αντικείμενο αναφοράς από το προηγούμενο μάθημα: κάθε πηγή έχει έναν αριθμό ("0", "1"…), ένα URL, έναν τίτλο και τα επιλεγμένα αποσπάσματα. Αυτοί είναι οι αριθμοί που επαναχρησιμοποιεί το μοντέλο για να σημειώσει τις παραπομπές του και τους οποίους το frontend σας θα επιλύσει αργότερα σε συνδέσμους.
from mistralai.client.models import ToolMessage
# Αποτελέσματα αναζήτησης τεκμηρίωσης, σε μορφή αναφοράς 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"
}
}
# Προσθήκη της κλήσης εργαλείου και της απάντησης στο ιστορικό
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)
)
)
Σημειώστε ότι το αρχικό μήνυμα του μοντέλου επανεισάγεται στο ιστορικό πριν από το ToolMessage: χωρίς αυτό το ζεύγος κλήσης εργαλείου / αποτελέσματος εργαλείου, το API απορρίπτει τη συνέχεια. Η δεύτερη κλήση δεν χρειάζεται πλέον τους ορισμούς των εργαλείων, καθώς η αναζήτηση έχει ήδη πραγματοποιηθεί.
# Δεύτερη κλήση: το μοντέλο παράγει μια απάντηση με παραπομπές
final_response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
Διαχωρισμός Κειμένου από Αναφορές
Η απάντηση με παραπομπές δεν είναι πλέον ένα απλό string, αλλά μια ακολουθία τμημάτων που εναλλάσσουν πεζό λόγο και σημάδια παραπομπής. Η ανάλυση περιλαμβάνει τη διέλευση αυτής της ακολουθίας και την ταξινόμηση: τα αντικείμενα TextChunk ανασυνθέτουν το αναγνώσιμο κείμενο, ενώ τα αντικείμενα ReferenceChunk παρέχουν τα reference_ids που χρησιμοποιήθηκαν πραγματικά. Αυτή η διάκριση σας προσφέρει πολύτιμες πληροφορίες: ακριβώς ποιες πηγές χρησιμοποίησε το μοντέλο από αυτές που παρέχετε.
from mistralai.client.models import TextChunk, ReferenceChunk
def parse_cited_response(response):
"""Εξάγει κείμενο και παραπομπές από μια απάντηση με παραπομπές."""
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("=== Απάντηση ===")
print(result["text"])
print("\n=== Πηγές με Παραπομπές ===")
for ref_id in result["references_used"]:
source = references[str(ref_id)]
print(f" - {source['title']} : {source['url']}")
Προετοιμασία Εμφάνισης στο Frontend
Η ισοπέδωση της απάντησης σε απλό κείμενο θα έχανε τη θέση των παραπομπών και, κατά συνέπεια, την αξία τους. Είναι προτιμότερο να διατηρήσετε την ακολουθία και να την εμπλουτίσετε: επιλύστε κάθε ReferenceChunk έναντι ενός πίνακα αναφορών για να μεταφέρετε τον τίτλο και το URL κάθε πηγής. Η διεπαφή σας λαμβάνει έτσι μια διατεταγμένη λίστα μπλοκ που μπορεί να αποδώσει ως clickable συνδέσμους, tooltips ή διαδραστικούς αριθμούς παραπομπών, χωρίς να χρειάζεται ποτέ να επανερμηνεύσει το κείμενο.
def format_for_frontend(response, reference_map):
"""Μορφοποιεί την απάντηση με παραπομπές για το 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
Πριν ανοίξετε αυτόν τον αγωγό στην πλήρη βάση τεκμηρίωσής σας, εκτελέστε τον με μόλις τρεις έως πέντε πηγές, όπως στο παραπάνω παράδειγμα. Θα δείτε αμέσως αν το μοντέλο κάνει παραπομπές στο σωστό σημείο, αν αξιοποιεί πολλαπλά έγγραφα ή αν προσκολλάται συστηματικά στο πρώτο, επιτρέποντάς σας να διορθώσετε το μήνυμα συστήματος πριν η συμπεριφορά χαθεί στον όγκο.
Βασικά σημεία
- Ο αγωγός ακολουθεί μια ροή δύο κλήσεων: κλήση εργαλείου και στη συνέχεια απάντηση με παραπομπές
- Οι αναφορές περνούν μέσω
ToolMessage, σε ένα αντικείμενο με ευρετήριο τον αριθμό πηγής ("0","1"…) - Η απάντηση περιέχει ένα μείγμα
TextChunkκαιReferenceChunkπρος ανάλυση - Δομήστε την έξοδο ώστε το frontend σας να μπορεί να εμφανίζει διαδραστικές παραπομπές
- Δοκιμάστε με 3–5 πηγές για να επικυρώσετε τη συμπεριφορά πριν μεταβείτε σε παραγωγή