Ορισμός Συναρτήσεων στην Python
Σε αυτήν τη σελίδα
Από τη Θεωρία στον Κώδικα
Τώρα που κατανοείτε τη διαδικασία των πέντε βημάτων και τη δομή του JSON Schema, ήρθε η ώρα να γράψετε πραγματικό κώδικα Python. Σε αυτό το μάθημα, θα δημιουργήσετε συναρτήσεις, θα συντάξετε τις προδιαγραφές τους και θα προετοιμάσετε τα πάντα για το API της Mistral—ό,τι πρέπει να υπάρχει πριν πραγματοποιήσετε την πρώτη κλήση δικτύου.
Εγκατάσταση του Mistral SDK
Ξεκινήστε εγκαθιστώντας το επίσημο πακέτο:
pip install mistralai
Στη συνέχεια, διαμορφώστε το κλειδί API σας. Η βέλτιστη πρακτική υπαγορεύει να μην το ενσωματώνετε ποτέ απευθείας στα αρχεία κώδικά σας. Αντ’ αυτού, διαβάστε το από μια μεταβλητή περιβάλλοντος, ώστε να μπορείτε να κάνετε commit τον κώδικά σας στον έλεγχο εκδόσεων με ασφάλεια.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Δημιουργία Συναρτήσεων Python
Ας εξετάσουμε ένα ολοκληρωμένο παράδειγμα: ένα σύστημα παρακολούθησης πληρωμών που υποστηρίζεται από ένα Pandas DataFrame. Αυτό είναι ένα κλασικό παράδειγμα από την τεκμηρίωση της Mistral και απεικονίζει τέλεια την έννοια· εδώ, το DataFrame παίζει τον ρόλο που θα είχε μια βάση δεδομένων σε περιβάλλον παραγωγής.
import pandas as pd
import json
# Payment data
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)
Ακολουθεί ο κώδικας που προσπελαύνει πραγματικά αυτά τα δεδομένα. Πρόκειται για τυπικές συναρτήσεις Python· τίποτα στην υλοποίησή τους δεν υποδηλώνει ότι ένα LLM θα τις οδηγήσει.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the status of a payment by its ID."""
if transaction_id in df["transaction_id"].values:
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": 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 by its ID."""
if transaction_id in df["transaction_id"].values:
date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
return json.dumps({"date": date})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
Δύο λεπτομέρειες υλοποίησης αξίζουν την προσοχή σας. Πρώτον, αυτές οι συναρτήσεις επιστρέφουν πάντα μια συμβολοσειρά JSON, ποτέ ένα ακατέργαστο αντικείμενο Python. Αυτή είναι η μορφή που αναμένει το μοντέλο ως αποτέλεσμα εργαλείου, επομένως το json.dumps() είναι υποχρεωτικό. Δεύτερον, διαχειρίζονται ρητά την περίπτωση όπου μια συναλλαγή δεν βρέθηκε, αντί να προκαλούν εξαίρεση. Αυτό το σφάλμα, διαμορφωμένο ως JSON, επιστρέφει στο μοντέλο όπως κάθε άλλο αποτέλεσμα, επιτρέποντάς του να ενημερώσει ευγενικά τον χρήστη ότι η συναλλαγή T9999 δεν υπάρχει. Θα δείτε αργότερα στο μάθημα γιατί αυτός ο reflex είναι απαραίτητος.
Συγγραφή Προδιαγραφών JSON
Κάθε συνάρτηση χρειάζεται μια προδιαγραφή ώστε το μοντέλο να μπορεί να την κατανοήσει. Εδώ εφαρμόζετε τη δομή από το προηγούμενο μάθημα στις δύο παραπάνω συναρτήσεις—σημειώστε την αυστηρή αντιστοιχία μεταξύ των πεδίων name και των πραγματικών ονομάτων των συναρτήσεων Python.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date a payment was made "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Οργάνωση Συναρτήσεων σε Λεξικό
Το μοντέλο επιστρέφει ένα όνομα συνάρτησης ως συμβολοσειρά. Χρειάζεστε έναν τρόπο να αντιστοιχίσετε αυτή τη συμβολοσειρά στο αντίστοιχο callable αντικείμενο, χωρίς να καταφύγετε στο eval ή σε έναν καταρράκτη εντολών if. Ένα λεξικό διανομής (dispatch dictionary) λύνει αυτό το πρόβλημα σε τρεις γραμμές.
from functools import partial
# Bind the DataFrame to each function
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
Το functools.partial αντιμετωπίζει μια συγκεκριμένη, πραγματική δυσκολία. Οι συναρτήσεις σας αναμένουν δύο ορίσματα—το DataFrame και το ID—αλλά το μοντέλο παρέχει μόνο ένα. Το μοντέλο δεν γνωρίζει τίποτα για το df, ούτε πρέπει. Το partial συμπληρώνει εκ των προτέρων αυτή την πρώτη παράμετρο μια και καλή. Ο ίδιος μηχανισμός εφαρμόζεται σε συνδέσεις βάσεων δεδομένων, πελάτες HTTP ή διακριτικά πιστοποίησης. Η δυναμική κλήση γίνεται τότε τετριμμένη.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
Η Επιλογή tool_choice
Κατά την αποστολή αυτών των εργαλείων στο API, η παράμετρος tool_choice αποφασίζει πόση ελευθερία δίνετε στο μοντέλο. Υπάρχουν τρεις πιθανές τιμές.
# The model decides whether to use a tool or respond directly (default)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Force the model to use a tool
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Prevent the model from using tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
Η λειτουργία "auto" είναι η πιο κοινή στην παραγωγή για καλό λόγο: ένας βοηθός παρακολούθησης πληρωμών θα πρέπει να μπορεί να λέει «γεια» χωρίς να ενεργοποιεί ένα ερώτημα βάσης δεδομένων. Το μοντέλο απαντά απευθείας σε γενικές ερωτήσεις και χρησιμοποιεί συναρτήσεις μόνο όταν είναι σχετικό. Ένα πλήρες μάθημα αργότερα στο μάθημα καλύπτει συγκεκριμένες περιπτώσεις χρήσης για τα any και none.
Βασικά σημεία
- Οι συναρτήσεις πρέπει να επιστρέφουν συμβολοσειρές JSON—ποτέ ακατέργαστα αντικείμενα Python
- Χρησιμοποιήστε ένα λεξικό διανομής για να αντιστοιχίσετε τα ονόματα των συναρτήσεων στις υλοποιήσεις τους
- Το
functools.partialείναι ιδανικό για την προ-συμπλήρωση παραμέτρων όπως συνδέσεις βάσεων δεδομένων ή DataFrames - Το
tool_choiceελέγχει αν το μοντέλο μπορεί ή πρέπει να χρησιμοποιήσει συναρτήσεις (auto,any,none) - Να διαχειρίζεστε πάντα τις περιπτώσεις σφάλματος στις συναρτήσεις σας (μη έγκυρες παράμετροι, ελλείποντα δεδομένα)