Πρακτικό Παράδειγμα: Ιχνηλάτης Πληρωμών
Σε αυτήν τη σελίδα
Ένα Πλήρες Έργο Από Άκρη σε Άκρη
Τα προηγούμενα μαθήματα απομόνωσαν κάθε μηχανισμό: ορισμούς εργαλείων, τον κύκλο κλήσης, τη διαχείριση σφαλμάτων και την ασφάλεια. Τώρα ήρθε η ώρα να τα συναρμολογήσετε. Θα δημιουργήσετε έναν πλήρη συνομιλιακό ιχνηλάτη πληρωμών, όπου οι χρήστες υποβάλλουν ερωτήσεις σε φυσική γλώσσα και το σύστημα αναζητά δεδομένα σε ένα Pandas DataFrame μέσω κλήσης συναρτήσεων. Αυτή η περίπτωση χρήσης αντλεί άμεσα από την επίσημη τεκμηρίωση του Mistral. Χωράει σε περίπου εκατό γραμμές κώδικα, ενώ αναδεικνύει τα πέντε δομικά στοιχεία μιας πραγματικής εφαρμογής: δεδομένα, επιχειρηματικές συναρτήσεις, προδιαγραφές JSON, δρομολόγηση και βρόχο συνομιλίας.
Τα Δεδομένα
Ένα DataFrame με πέντε συναλλαγές καλύπτει τα ενδιαφέροντα σενάρια: έναν πελάτη με πολλαπλές πληρωμές, μια εκκρεμή πληρωμή και μια αποτυχημένη πληρωμή.
import pandas as pd
import json
import os
from mistralai.client import Mistral
from functools import partial
# Transactions DataFrame
data = {
"transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
"customer_id": ["C001", "C002", "C003", "C002", "C001"],
"payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
"payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
"payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)
Επιχειρηματικές Συναρτήσεις
Τέσσερις συναρτήσεις καλύπτουν τις τυπικές ανάγκες ιχνηλάτησης πληρωμών. Οι τρεις πρώτες λειτουργούν σε μία μόνο συναλλαγή και διαφέρουν ως προς τη λεπτομέρεια: μόνο κατάσταση, μόνο ημερομηνία ή πλήρεις λεπτομέρειες. Αυτή η φαινομενική πλεοναστικότητα είναι σκόπιμη· επιτρέπει στο μοντέλο να ζητά μόνο ό,τι χρειάζεται, μειώνοντας τα περιττά δεδομένα στο πλαίσιο (context). Η τέταρτη αλλάζει οπτική γωνία και λειτουργεί βάσει πελάτη.
Σημειώστε την κοινή σύμβαση: όλες επιστρέφουν μια συμβολοσειρά JSON, ακόμη και σε περίπτωση αποτυχίας, και όλες διαχειρίζονται τα ελλείποντα αναγνωριστικά αντί να αφήνουν το Pandas να προκαλέσει εξαίρεση σε έναν κενό δείκτη.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the status of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"status": row["payment_status"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the date of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"date": row["payment_date"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_details(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves all details of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"customer_id": row["customer_id"],
"amount": float(row["payment_amount"]),
"date": row["payment_date"],
"status": row["payment_status"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def list_customer_transactions(df: pd.DataFrame, customer_id: str) -> str:
"""Lists all transactions for a given customer."""
customer_df = df[df["customer_id"] == customer_id]
if customer_df.empty:
return json.dumps({"error": f"Customer {customer_id} not found"})
transactions = []
for _, row in customer_df.iterrows():
transactions.append({
"transaction_id": row["transaction_id"],
"amount": float(row["payment_amount"]),
"date": row["payment_date"],
"status": row["payment_status"]
})
return json.dumps({"customer_id": customer_id, "transactions": transactions})
Η μετατροπή float(row["payment_amount"]) αξίζει μια δεύτερη ματιά: χωρίς αυτήν, το json.dumps αποτυγχάνει με τύπους NumPy. Αυτό είναι το είδος της λεπτομέρειας που εντοπίζετε μόνο κατά την εκτέλεση.
Προδιαγραφές JSON
Το μοντέλο δεν βλέπει κανέναν από τον παραπάνω κώδικα. Γνωρίζει μόνο αυτές τις περιγραφές. Η ρητή αναγραφή των πιθανών καταστάσεων στο retrieve_payment_status και η υπενθύμιση στο μοντέλο της μορφής T1001 σε κάθε περιγραφή παραμέτρου του επιτρέπουν να επιλέξει τη σωστή συνάρτηση και να εξαγάγει σωστά το αναγνωριστικό.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed)",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date of a payment",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_details",
"description": "Retrieves all details of a payment: amount, date, status, customer",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "list_customer_transactions",
"description": "Lists all transactions for a given customer",
"parameters": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Customer identifier (e.g., C001)"
}
},
"required": ["customer_id"]
}
}
}
]
Το Λεξικό Δρομολόγησης
Εδώ βρίσκεται η παγίδα: οι συναρτήσεις σας αναμένουν το df ως πρώτο όρισμα, αλλά το μοντέλο δεν θα το παρέχει ποτέ· δεν γνωρίζει ότι υπάρχει, και αυτό είναι απολύτως φυσιολογικό. Το functools.partial λύνει αυτό το ζήτημα κομψά, δεσμεύοντας εκ των προτέρων το DataFrame, ώστε κάθε καταχώριση στο λεξικό να γίνεται καλέσιμη μόνο με τα ορίσματα που παράγει το μοντέλο.
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
"retrieve_payment_details": partial(retrieve_payment_details, df),
"list_customer_transactions": partial(list_customer_transactions, df),
}
Ο Βρόχος Συνομιλίας
Το μήνυμα συστήματος ορίζει τον ρόλο, τη γλώσσα και την αναμενόμενη μορφοποίηση για τα ποσά. Η συνάρτηση chat συντονίζει τα υπόλοιπα και η δομή της αξίζει ιδιαίτερη προσοχή: ο βρόχος while message.tool_calls διαχειρίζεται μία κλήση, πολλαπλές παράλληλες κλήσεις ή μια αλυσίδα όπου το μοντέλο ζητά άλλη συνάρτηση αφού δει το πρώτο αποτέλεσμα. Ο εσωτερικός βρόχος εκτελεί όλες τις κλήσεις για τον τρέχοντα γύρο· ο εξωτερικός βρόχος επανακαλεί το μοντέλο όσο αυτό συνεχίζει να ζητά εργαλεία.
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"
messages = [
{
"role": "system",
"content": "You are a payment tracking assistant. "
"Respond in English. Use the available tools "
"to answer questions about transactions. "
"Format amounts in euros with 2 decimal places."
}
]
def chat(user_input: str) -> str:
"""Complete conversation turn with tool_calls handling."""
messages.append({"role": "user", "content": user_input})
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
# Loop while the model wants to call functions
while message.tool_calls:
messages.append(message)
for tool_call in message.tool_calls:
fn_name = tool_call.function.name
fn_params = json.loads(tool_call.function.arguments)
if fn_name in available_functions:
result = available_functions[fn_name](**fn_params)
else:
result = json.dumps({"error": f"Unknown function {fn_name}"})
messages.append({
"role": "tool",
"name": fn_name,
"content": result,
"tool_call_id": tool_call.id
})
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
messages.append(message)
return message.content
Τι Αποκαλύπτει η Συνομιλία
Δοκιμάστε το με τέσσερις διαδοχικούς γύρους. Ο δεύτερος είναι ο πιο διδακτικός: η φράση «αυτή η συναλλαγή» δεν περιέχει αναγνωριστικό, ωστόσο το μοντέλο καλεί το retrieve_payment_details με το T1001. Επίλυσε την αναφορά χρησιμοποιώντας το ιστορικό που διατηρείται στο messages, κάτι που θα ήταν αδύνατο αν επαναφέρατε τη λίστα σε κάθε κλήση. Ο τέταρτος γύρος δείχνει την άλλη όψη: καμία συνάρτηση δεν αναζητά αποτυχημένες πληρωμές, αλλά το μοντέλο κάνει ερώτημα στον σχετικό πελάτη και φιλτράρει μόνο του το αποτέλεσμα.
# Turn 1
print(chat("What is the status of payment T1001?"))
# -> "Payment T1001 has status: paid."
# Turn 2
print(chat("Give me all the details for this transaction."))
# -> "Here are the details for payment T1001:
# - Customer: C001
# - Amount: 125.50 euros
# - Date: March 15, 2026
# - Status: paid"
# Turn 3
print(chat("What are all the transactions for customer C002?"))
# -> "Customer C002 has 2 transactions:
# - T1002: 89.99 euros (paid, March 16, 2026)
# - T1004: 45.00 euros (paid, March 17, 2026)"
# Turn 4
print(chat("Are there any failed payments?"))
# -> "Yes, payment T1005 for customer C001 (210.75 euros) failed."
Η μορφοποίηση των ποσών με υποδιαστολή και οι ημερομηνίες γραμμένες ολόκληρες δεν προέρχονται από καμία γραμμή κώδικα: είναι αποτέλεσμα του prompt του συστήματος. Αυτό είναι το πιο χρήσιμο συμπέρασμα από αυτό το κεφάλαιο· το ήμισυ της αντιληπτής ποιότητας συμβαίνει στις περιγραφές και στο μήνυμα συστήματος, όχι στους μηχανισμούς κλήσης.
Βασικά σημεία
- Ένας πλήρης ιχνηλάτης πληρωμών απαιτεί 4 συναρτήσεις που καλύπτουν τις κύριες περιπτώσεις χρήσης
- Το
functools.partialδεσμεύει το DataFrame στις συναρτήσεις για καθαρή δρομολόγηση - Ο βρόχος
while message.tool_callsδιαχειρίζεται αυτόματα διαδοχικές και παράλληλες κλήσεις - Το μήνυμα συστήματος καθοδηγεί το μοντέλο σχετικά με τον τόνο, τη γλώσσα και τη μορφοποίηση
- Δοκιμάστε με συνομιλίες πολλών γύρων για να επαληθεύσετε ότι το μοντέλο διατηρεί το πλαίσιο